Skip to content

Test and document changes

Test in layers

Run the smallest relevant test while developing, then the required repository checks before handoff:

python -m npe2 validate src/napari_vipp/napari.yaml
python -m ruff check .
python -m pytest

High-risk changes need more than a happy-path unit test. Consider:

  • invalid/empty/minimal inputs;
  • 2D, 3D, leading axes, and anisotropic scale;
  • dynamic and multi-output persistence;
  • manual-node stale/current transitions;
  • generated Python compiling and running;
  • I/O round trips for supported fields and dtypes;
  • cancellation, memory retention, and repeated UI actions;
  • bundled examples reopening and satisfying a meaningful invariant.

For an accelerated implementation also cover:

  • CPU-only import/discovery and missing/broken optional-provider behavior;
  • admitted and rejected dtype/shape/parameter/environment matrices;
  • exact or explicitly bounded CPU/GPU parity on adversarial and representative fixtures before performance timing;
  • device residency, transfer boundaries, memory-model bounds, and host finalizers;
  • synchronized progress, cancellation at each honest checkpoint, fair lease behavior, and zero-residue cleanup on every exit path;
  • classified runtime OOM with visible one-segment retry versus Strict failure;
  • immutable policy/evidence hash validation and exact-workload benchmark invalidation/reuse; and
  • identical request/provenance/publication behavior in interactive, batch, generated Python/CLI, and export surfaces.

Real-device tests are opt-in and must state the exact hardware, driver, runtime, scientific-stack, and policy identity. Run the real_cuda selection only on an appropriate isolated host; mocks and a successful kernel probe do not establish scientific admission.

The test suite must never read or append to a user's machine-local Auto timing history. Its autouse fixture sets NAPARI_VIPP_PIPELINE_TIMING_HISTORY_PATH to a per-test temporary JSON path, which test subprocesses inherit. History-specific tests may point the variable at another tmp_path; do not unset it or use the normal platform application- data location. This isolation is a developer safeguard, not a user-facing compute option.

Prefer a small parameterized test over many near-identical cases. Keep an end-to-end UI test only when it protects behavior that cannot be established at a lower layer.

Update the manual

Public documentation is maintained only in vipp-mkdocs. The application repository keeps plans, implementation contracts, and evidence—not another manual. Follow the writing checklist and link companion application/documentation changes in their pull requests.

Write for the user's task first. Put exact lists and settings in reference; explain scientific decisions in the task page where they occur. Qualify claims about validation, metadata, scalability, batch provenance, and compatibility.

For UI images:

  • use bundled synthetic or clearly licensed public data;
  • use the dark napari theme and the documented release;
  • show VIPP undocked and large for workflow context;
  • crop to the relevant graph portion for a concept or control;
  • include the napari viewer for high-resolution/3D scientific inspection;
  • remove paths, private metadata, tooltips, clipping, and transient state;
  • write alt text and a caption that tells the reader what to notice.

Run mkdocs build --strict and inspect both light and dark manual themes at desktop and narrow widths. Follow links from the page, not only search results.

Run python scripts/check_manual.py as well. With both repositories available, add --application-repo ../napari-vipp to verify README and relocation-note destinations against this checkout.

Keep reference counts honest

The node and example counts are release facts. When the registries change, regenerate/compare the public lists and update counts in the same change. Do not claim a parameter-level generated reference unless the build actually checks it against the registry.