Skip to content

Testing

ACP Kit is tested primarily at the public behavior boundary, not by deeply mocking private runtime internals.

That matters for an adapter: correctness lives in session behavior, ACP updates, approvals, plan state, and tool projection more than in any one private helper.

What The Suite Covers

The main tests/pydantic/ suite covers:

  • ACP session lifecycle
  • transcript and message-history replay
  • session-local model selection
  • slash commands for models, modes, and thinking
  • native plan state and provider-backed plan state
  • deferred approval flow
  • factory and AgentSource integration
  • capability bridges
  • filesystem and command projection
  • host backends and ClientHostContext
  • Codex auth helper integration

Recent high-value scenarios include:

  • persisted file-backed session restart and continuation
  • malformed saved session files in public load/list flows
  • interleaved multi-session isolation
  • root CLI -> adapter entrypoint routing
  • hook event-stream contract failures

Canonical Commands

Repo-wide checks:

uv run ruff check
uv run ty check
uv run basedpyright
make tests
make check

Branch coverage for the adapter:

make coverage-branch

Run coverage and save the formatted summary to COVERAGE:

make save-coverage

Current enforced thresholds:

  • line coverage must stay at or above 97%
  • branch coverage must stay at or above 95%

Check the coverage thresholds without rewriting tracked files:

make check-coverage

Focused adapter suite:

python3.11 -B -m pytest tests/pydantic tests/test_acpkit_cli.py -q

Test Style

The preferred test style is:

  • assert on ACP method behavior
  • assert on emitted session updates
  • assert on visible tool or hook listings
  • assert on persisted session state
  • assert on provider and bridge integration

The suite intentionally avoids:

  • mocking private helper call order
  • overfitting to implementation details that do not affect ACP behavior

Docs Validation

When editing documentation, also validate the docs build:

uv run --extra docs --extra pydantic --extra codex mkdocs build --strict

Pre-commit

ACP Kit keeps lightweight config hooks on every commit, and only runs expensive validation when the staged change set looks major.

  • always on pre-commit: uv run --extra dev ruff check --fix, YAML validation, and TOML validation
  • conditional on pre-commit: make check-coverage and make prod
  • the heavy hooks run only when staged files touch core code, tests, scripts, workflows, or tool config

That split is intentional:

  • normal commits stay fast
  • major runtime, test, tooling, or workflow changes still hit the stronger gate

Install the hook:

uv run pre-commit install

Force the heavy hooks even for a small staged change:

ACPKIT_FORCE_MAJOR_HOOKS=1 git commit