Testing¶

Put each contract in the suite that owns the boundary. A focused integration test may cross boundaries, but do not repeat the same happy path throughout the tree.

Suite ownership¶

The operation-authoring guide explains the exact InvocationCase, RawRuleCase, NumpySupportCase, derivative-role, and lifetime evidence required for a new public form.

Python gates¶

Set up the locked development environment with Python 3.12 through 3.14:

uv sync --all-groups --locked
uv run pre-commit install --install-hooks

Hook installation is per clone. Before review, verify the complete repository hygiene configuration independently of the files staged in the current commit:

uv run pre-commit run --all-files

The installed pre-commit hook may fix files and require restaging. The commit-msg hook enforces Conventional Commits. Avoid --no-verify, which bypasses all checks.

The canonical static and test gates are:

uv run ruff format --check .
uv run ruff check .
uv run pyrefly check
uv run pytest
uv run pytest packages/advect/tests/advect_conformance_tests \
  --hypothesis-profile=thorough

Pyrefly checks the runtime package and the release/browser-documentation scripts listed in pyproject.toml. Dynamic provider-qualification and benchmark scripts, plus tests, remain outside this production typing gate; their necessary boundary suppressions stay local.

Run the owning suite while iterating. Run the full Python suite for changes to traced operations, derivative rules, shared transform behavior, or public support declarations.

Hypothesis should own shrinkable numerical domains and combinatorial invariants. CI does not retain the local .hypothesis database, so promote a discovered failure to @example or a focused regression. Do not replace an open numerical domain with a two-value matrix or loosen tolerances to hide a nonsmooth case.

Rust and native gates¶

Use Rust 1.94 or newer with Clippy and rustfmt:

rustup toolchain install stable --component clippy rustfmt
cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-targets
cargo deny --all-features check -W unmaintained
uv run pytest packages/advect/tests/advect_native_tests
uv build --package advect --wheel --out-dir dist/wheelhouse --clear

CI runs the locked workspace Clippy and test gates on both Rust 1.94 and the current stable toolchain.

For an internal advect-runtime change whose adapter contract is unchanged, the focused Clippy and test forms (-p advect-runtime) plus format and cargo deny are sufficient while iterating. Run the workspace forms above for a native change. A runtime change also needs the Python/native boundary tests and wheel build when it alters the accepted graph format, validation result, ownership, execution behavior, or another adapter-visible contract.

An outer StagedProgram envelope change instead runs Python static checks and advect_core_tests, with test_stage_durability.py as the focused regression owner. It does not require a wheel build when the enclosed runtime graph and PyO3 contract are unchanged. The operation-authoring guide lists the proportional command sets.

Documentation gates¶

uv run mkdocs build --strict
uv run python scripts/run_doc_snippets.py docs

The native snippet runner is necessary but not sufficient for browser support. When runnable snippets or the playground boundary changes, build the Pyodide wheel and run the browser lane described in the documentation guide.

Specialized evidence¶

• NumPy surface changes run uv run pytest packages/advect/tests/advect_numpy_tests/test_support_evidence.py locally. NumPy 2.0–2.5 range evidence is owned by the numpy-compatibility matrix in .github/workflows/ci.yml; one locally installed minor is not range qualification.
• Array API operation changes run uv run pytest packages/advect/tests/advect_grad_tests/test_array_api_operation_qualification.py and uv run python -m scripts.qualify_array_api_operations for every affected revision, as shown in the operation-authoring guide. Provider changes also run uv run pytest packages/advect/tests/advect_array_api_compat_tests. CuPy is qualified only on a CUDA host; record it as unverified when unavailable.
• JAX, PyTorch, or HIPS changes run uv run --no-sync pytest packages/advect/tests/advect_interop_tests in an environment containing all qualified host dependencies.
• xarray changes run uv run pytest packages/advect/tests/advect_xarray_tests.
• Blocking performance evidence compares exact reference and candidate wheels through uv run python -m scripts.bench_advect_regression --help.
• Runtime memory acceptance uses uv run python -m scripts.bench_runtime_memory --profile cpu-runtime --acceptance.

Provider correctness, one local dependency version, or a non-gating benchmark must not be reported as a broader compatibility or performance claim.