​
Testing Taxonomy

​
Goal

Keep tests/ predictable by separating test types while moving non-test utilities to scripts/debug/.

​
Canonical Test Folders

  • tests/unit/: small, isolated logic tests.
  • tests/integration/: multi-component integration tests.
  • tests/contract/: behavior and API contracts.
  • tests/e2e/: end-to-end flow tests.
  • tests/smoke/: lightweight critical-path checks.
  • tests/fixtures/: reusable fixtures/data.
  • tests/helpers/: test support helpers.

​
Migration Policy

  • Keep existing tests runnable during migration.
  • Move in small batches and update all workflow/script references in the same change.
  • Do not place debug or repair utilities in tests/; use scripts/debug/.

​
Marker Policy

  • Taxonomy markers are standardized as module-level pytestmark declarations.
  • Folder-to-marker mapping:
  • tests/unit/* -> @pytest.mark.unit
  • tests/integration/* -> @pytest.mark.integration
  • tests/contract/* -> @pytest.mark.contract
  • tests/e2e/* -> @pytest.mark.e2e
  • tests/smoke/* -> @pytest.mark.smoke
  • This keeps pytest -m <marker> selection aligned with repository structure and avoids ambiguous marker drift.

​
Naming Policy

  • Backend tests must use test_*.py.
  • Frontend colocated tests use *.test.tsx or *.integration.test.tsx.
  • Avoid check_*, verify_*, fix_*, debug_* under tests/; move those utilities to scripts/debug/.
  • Contract enforcement: tests/contract/test_repo_structure_hygiene.py (runs tools/repo-maintenance/verify_repo_structure.py).

​
Frontend Test Placement Policy

  • Use colocated frontend tests: *.test.tsx or *.integration.test.tsx next to component/feature module.
  • Do not introduce new __tests__/ directory trees for frontend code.

​
Current Phase-1 Moves

  • tests/unit/: timezone/tone/model-config examples.
  • tests/integration/: auth org-flow and AI-usage integration examples.
  • tests/contract/: simulation basic contract and responder-selection contract.
  • tests/e2e/: background consequence propagation e2e.
  • tests/smoke/: admin runtime user smoke.

​
Current Phase-2 Moves

  • tests/contract/: dynamic agent router orchestration, selector group chat unit policy, inter-agent communication policy.
  • tests/contract/: simulation settings references, simulation policy propagation SLA validation, simulation state ledger.
  • tests/integration/: simulation admin realism routes.
  • tests/smoke/: realism benchmark harness.

​
Current Phase-3 Moves

  • tests/contract/: market-readiness and release-cycle gate tests.
  • tests/contract/: consequence engine and consequence route contract checks.
  • tests/smoke/: soak harness and soak drift snapshot checks.
  • tests/integration/: memory coherence, simulation events service, and channel chatter integration checks.

​
Current Phase-4 Moves

  • tests/unit/: datetime/lifecycle/guardrail-focused utility and safety tests.
  • tests/contract/: OpenAPI redaction and simulation settings mem0 guard contract checks.
  • tests/integration/: auth, API integration, login RBAC, and message reaction route tests.

​
Current Phase-5 Moves

  • tests/unit/: ai-usage recorder, analytics timeline, character loader, scoring, and import sanity tests.
  • tests/contract/: ai-usage backfill, autogen log redaction/API route contract, and simulation realism/validation contracts.
  • tests/smoke/: agent tone/autogen/mem0/message scheduler smoke checks.
  • tests/integration/: selector group chat, repositories, org CLI, mongodb protocol, simulation admin RBAC, and task follow-up/toolkit route integrations.
  • Root tests/ now keeps taxonomy folders plus shared files (conftest.py, package markers) rather than a flat test_*.py mix.