Testing

The test suite separates reproducible offline checks from tests that require locally obtained official DICOM artifacts or network access.

Offline gates

Run before every change is considered complete:

make lint
make typecheck
make test

These map to:

uv run --dev ruff check .
uv run --dev mypy
uv run --dev pytest

The default suite uses synthetic and small attributed fixtures. It must not require an official DICOM download.

Focused tests

uv run --dev pytest tests/unit/test_query_resolver.py
uv run --dev pytest tests/unit/test_mcp_server.py
uv run --dev pytest tests/agent_regression

Use the most focused test while iterating, then run the full offline gates.

Test groups

tests/unit/
tests/agent_regression/
tests/fixtures_synthetic/
tests/fixtures_minimal_attributed/
tests/integration_requires_dicom_download/

Unit tests

Cover source discovery, manifest integrity, parsing, migrations, imports, repositories, resolvers, CLI behavior, MCP registration/protocol behavior, configuration, JSON schemas, distribution audit, and related utilities.

Agent regression

Committed prompt cases define expected deterministic tool traces before answer synthesis. The suite checks routing and evidence preservation rather than making free-form model text authoritative.

Synthetic fixtures

Project-authored DocBook structures exercise parser branches offline.

Minimal attributed fixtures

Tiny attributed excerpts are used only when synthetic material cannot faithfully reproduce the behavior under test.

Official-artifact integration

Tests under integration_requires_dicom_download use a local official cache or explicit network enablement. They are separate so ordinary contributors do not need to redistribute or automatically download the standard.

Integration commands

Run smoke integration against an available local official cache:

make test-dicom-integration

The underlying target is:

uv run --dev pytest tests/integration_requires_dicom_download

Run current-release discovery only when network access is intentionally enabled:

make test-dicom-current

This sets:

DICOM_KB_RUN_CURRENT=1

Run the strict official-edition release gate:

make test-dicom-release

This sets:

DICOM_KB_RUN_RELEASE=1

The release gate must fail rather than quietly skip when the required full part set or semantic rows are absent.

Build smoke test

After parser or migration changes:

uv run --dev dicom-kb build-fixture \
  --edition 2026b \
  --db /tmp/dicom-kb-test.sqlite \
  --force

uv run --dev dicom-kb verify \
  --edition 2026b \
  --db /tmp/dicom-kb-test.sqlite

Run representative CLI and Python queries against the result.

What to assert

For public query changes, assert:

• status and result fields;
• references;
• warnings;
• classification;
• parse confidence;
• trace shape;
• CLI JSON;
• MCP schema, dispatch, and protocol output;
• Python Pydantic output;
• ambiguous and not-found behavior;
• malformed input behavior.

For parser changes, assert:

• source references;
• ordering;
• include and cross-reference behavior;
• parser warnings;
• import counts;
• build metrics;
• quality-gate behavior;
• no forbidden distribution artifact is introduced.

Record skipped prerequisites

When official-edition or current-release tests cannot run, record the missing local prerequisite in release notes or review output. Do not describe a skipped gate as passed.