Testing
The test suite uses unittest.
No external service and no model are needed.
Run
python3 -m unittest discover -s tests
A single file:
python3 -m unittest tests.test_ledger -v
A single test:
python3 -m unittest tests.test_architecture.SurveyTest.test_survey_json_has_scope_tree_and_plan
Coverage of the new architecture
tests/test_architecture.py: scope, partition tree, segment planner, survey CLI.tests/test_ledger.py: ledger sync, query, full-read cycle, watcher, audit, guard.tests/test_hint_plugin.py: the Hermes guard hook.tests/test_workspace.py: the workspace survey.tests/test_quality_check.py: the answer-quality rubric and runner.tests/test_config.py: config.toml parsing and precedence.tests/test_initialize.py: prerequisite checks and config writing.tests/test_security.py: auth, scopes, request bounds, redaction, injection.tests/test_knowledge_migrations.py: old SQLite upgrades and checksums.tests/test_backend_migrations.py: PostgreSQL, MySQL, and MariaDB upgrades.tests/test_ledger_migrations.py: local ledger upgrades and root identity.tests/test_plugin_parity.py: four-bundle parity and hook decision vectors.tests/test_tls_proxy.py: TLS terminator forwarding and auth.tests/test_benchmark_docs.py: local-only benchmark guards and mock server.
The suite also covers the index, refresh, plan, session, workspace, MCP, and providers. The default run is standard-library only; database, queue, host-CLI, and Node tests skip cleanly when their environment is absent.
External test environments
POSTGRES_URL=... MYSQL_URL=... MARIADB_URL=... \
python3 -m unittest tests.test_knowledge_service tests.test_backend_migrations
The URLs must point at disposable databases. CI uses service containers for
PostgreSQL 16, MySQL 8.4, and MariaDB 11.4. Node is required for the OpenCode
guard vectors; openssl is required for the TLS proxy test.
What is not tested
- A model reading a full-window segment.
- Answer quality at full-window scale or against a control arm.
- A live OpenCode, Claude Code, or Codex session. The bundles and hook vectors are tested directly.
- A very large repository at the new ledger scale.
- The watcher as a long-running service.
The quality harness itself is tested offline with a fixed rubric and a fake
model command.
The live answer-quality run is recorded under benchmarks/quality/.
Acceptance
A change is ready when:
- the full suite passes;
- a fresh index and a survey work on a temporary repository;
- a full-read plan, read, done, and verify cycle complete;
- the documentation links resolve;
- no new command requires a model call.