Skip to content

Test Strategy

The test suite covers route flows, service behavior, storage adapters, scan persistence, runner orchestration, and operational hardening. Tests run with pytest and don't require AWS credentials or a running database.

Running tests

pytest

For faster feedback while working on a specific area:

pytest tests/test_projects_flow.py      # project and repository workflows
pytest tests/test_v16_adapter.py        # scan engine adapter behavior
pytest tests/test_scan_persistence.py   # scan state and findings storage
pytest tests/test_hardening.py          # quotas, limits, worker state
pytest tests/test_archive_safety.py     # archive extraction safety

What the tests cover

Area What's tested
Auth and session flows Login, token validation, session creation
Project and repository workflows Create, ingest, threat profile, scan, findings
Scan runner orchestration ECS task launch, status, cancellation
v16 adapter compatibility Event mapping, finding upsert, cancellation token
S3 storage adapter Upload, download, presigned URLs
Postgres scan persistence Scan lifecycle, finding upsert, migration state
Billing service Usage calculation
Hardening Quota enforcement, worker heartbeats, cleanup
Archive safety Path traversal detection, size limits
Codex container lifecycle Container creation, cleanup, stale containers

Testing approach

Unit tests focus on one service or module in isolation with mocked dependencies. Use these when testing business logic that doesn't need real storage.

Flow tests (like test_projects_flow.py) test a complete user journey — create project, add repo, ingest, scan, check findings. These use a real (in-memory or test) storage layer.

Adapter tests (like test_v16_adapter.py) test the boundary between the backend and v16. These help catch contract changes that would break scan execution.

When to add tests

  • Changing scan state transitions → test_scan_persistence.py
  • Changing the v16 event contract → test_v16_adapter.py
  • Changing archive handling → test_archive_safety.py
  • Adding a new quota or limit → test_hardening.py
  • Adding a new storage operation → test_s3_file_storage.py
  • New project/scan/finding endpoint → test_projects_flow.py

Changes that touch scan state, persistence, queue behavior, or ECS orchestration should have focused test coverage before deployment.