Testing and CI

Local validation

Install development dependencies:

python -m pip install -e '.[dev]'

Run the same local checks used by CI:

python -m compileall -q src tests scripts
python -m pytest -q
bash -n scripts/ssh-smoke.sh scripts/package-smoke.sh scripts/runtime-evidence.sh
NO_MKDOCS_2_WARNING=1 mkdocs build --strict
scripts/release-check.sh

Release check

scripts/release-check.sh

The release check combines metadata, generated documentation, plugin coverage, tests, strict docs and package smoke into one local gate. Use AUTOMAX_RELEASE_CHECK_SKIP_DOCS=1 or AUTOMAX_RELEASE_CHECK_SKIP_PACKAGE=1 only while debugging a narrower failure.

Package smoke

scripts/package-smoke.sh

This validates build/install behavior from packaging metadata.

SSH smoke

Use the extended SSH smoke when a real host is available:

AUTOMAX_SSH_HOST=web01.example.com \
AUTOMAX_SSH_USER=deploy \
AUTOMAX_SSH_KEY_FILE=$HOME/.ssh/id_ed25519 \
scripts/ssh-smoke.sh

Privileged package, systemd, user and group checks are opt-in. See Extended SSH smoke.

Runtime evidence suite

Use the runtime evidence suite when a disposable lab or VM target is available:

AUTOMAX_SSH_HOST=web01.example.com \
AUTOMAX_SSH_USER=deploy \
AUTOMAX_SSH_KEY_FILE=$HOME/.ssh/id_ed25519 \
scripts/runtime-evidence.sh

The suite runs the SSH smoke, exports Markdown and JSON run evidence, creates a portable evidence ZIP and writes checksums under dist/runtime-evidence/. It exits with code 77 when no runtime target is configured.

GitHub Actions

The CI workflow runs Python tests across the supported Python matrix, runs Ruff, checks Python 3.9 compatibility, runs release metadata guardrails and builds MkDocs strictly. The documentation workflow publishes the MkDocs site to GitHub Pages.

The CodeQL workflow runs GitHub code scanning for Python on pushes, pull requests and a weekly schedule. It uses github/codeql-action/*@v4, which runs on the Node.js 24 action runtime.