Skip to content

4.testing.md

Latest commit

 

History

History
68 lines (50 loc) · 3.36 KB

4.testing.md

File metadata and controls

68 lines (50 loc) · 3.36 KB
Raw

4. Testing

Run all existing software tests and static/documentation checks.

Before a pull request

Complete setup, then run the three checks:

make pre-commit   # static checks and hooks
make test-all     # tests
make docs-build   # strict documentation build

make check runs all three at once (and first warns if the Git hooks are missing):

make check

All current tests are self-contained; there is no integration suite or coverage instrumentation yet. test-all runs the unit tests, then builds the wheel and loads its entry point in an isolated environment. Future integration suites must join test-all and CI.

Focused checks

Command Scope
make check pre-commit-status, pre-commit, test-all and docs-build
make test-all Unit tests plus the built-wheel smoke; required comprehensive check
make test-unit / make test-local Unit tests; use ARGS to select cases
make test-installation Build the wheel, install it in a throwaway env, load hello
make pre-commit Static hooks and strict docs; FILES="path/a path/b" selects files
make pre-commit-status Warn when the Git hooks are not installed
make docs-build Strict docs build only
make build-package Build and verify the wheel/sdist separately

For example:

make test-unit N=1 ARGS="-k release"

Tests use four workers by default (N=4). test-all rejects selection filters; empty collections fail. make test-installation builds the wheel and loads its entry point in an isolated environment; test-all runs it after the unit tests.

Writing tests

Use tests/unit/test_<module>.py; tests/README.md maps docs/release tests. Use tmp_path and monkeypatch so parallel tests share no state or local dotenv settings. Mark async tests with @pytest.mark.asyncio (strict mode). Release tests use isolated Git/GitHub/uv command substitutes and never publish.

CI

CI and both release branches run static checks and test-all; summaries include setup failures. Build/package installation checks remain separate, and no live-service validation is claimed.

Static and documentation hooks

Hooks check formatting and lint (Ruff), syntax and whitespace, secrets, Markdown and spelling, the lockfile and the strict docs build, workflow syntax (actionlint) and workflow security (zizmor). Commitizen runs only at the commit-msg stage. make install-dev installs the Git hooks in a checkout (not in CI or Docker); run make pre-commit-install if that step failed, and make pre-commit-status (part of make check) warns when they are missing. make pre-commit only runs the hooks and never installs them. See .pre-commit-config.yaml for the full list; pip-audit, bandit and markdown-link-check are disabled. .github/zizmor.yml holds the one zizmor exception: the release workflow's checkouts keep their credentials because they push.