Skip to content

Backend Tests

All tests live in the tests/ directory and run with pytest. Here's a guide to what each test file covers and when to run it.

Test files

File What it covers Run when...
test_projects_flow.py End-to-end project/repository/scan/finding workflow Changing project, repo, scan, or finding APIs
test_projects_runner.py ECS runner launch, status, and cancellation Changing runner orchestration (app/projects/runner.py)
test_v16_adapter.py Backend-to-v16 event mapping and finding upsert Changing app/projects/v16_adapter.py or the v16 event contract
test_scan_persistence.py Scan lifecycle state transitions and findings storage Changing scan status logic or finding persistence
test_auth_sessions_flow.py Auth login/refresh and legacy session flow Changing app/auth/ or app/sessions/
test_git_upload.py Git upload creation and metadata Changing app/git_upload/
test_hardening.py Quota enforcement, worker heartbeats, cleanup Changing app/hardening/
test_billing_service.py Usage calculation and billing summary Changing app/billing/
test_s3_file_storage.py S3 upload, download, presigned URLs Changing app/storage/s3.py
test_archive_safety.py Path traversal detection, size limits Changing app/storage/archive.py
test_codex_container_manager.py Codex container lifecycle and cleanup Changing app/projects/codex_container_manager.py

Running specific tests

Run a whole file:

pytest tests/test_projects_flow.py

Run a specific test function:

pytest tests/test_projects_flow.py::test_create_scan_and_check_findings

Run with verbose output:

pytest -v tests/test_hardening.py

Run with print statements visible:

pytest -s tests/test_v16_adapter.py

Test structure

Most test files follow this pattern:

  1. Setup — create a minimal in-memory or test-mode service instance
  2. Action — call a service method or simulate an API request
  3. Assert — verify the output or state change

Tests are designed to be independent — each test creates its own data and doesn't depend on other tests having run first.

Test infrastructure

Tests don't require a running Postgres database, AWS credentials, or Docker. They use: - In-memory or temporary-file storage backends - Mocked AWS clients for SQS, S3, and ECS - A test version of the FastAPI app (via TestClient)