Skip to content

[T-106] API performance test: p95 ≤ 200 ms on list endpoints with 10 000 runs (locust headless, nightly) #160

Closed

Description

@CodewithJha

Task T-106 · Milestone M7 — API · Size S · Priority P2 · Epic #7

Implements NFR-PERF-004 · NFR-SCAL-001

Branch test/t-106-api-performance-test-p95-200 — one task = one branch = one PR (doc 32 §6)

Summary

Add tests/perf/locustfile.py and a nightly job seeding 10 000 runs and running locust headless for 60 s, failing if p95 > 200 ms on list endpoints.

Context / motivation

Doc 18 §6: PERF-004 verified with locust against a seeded DB.

Scope

In scope

  • Query plan check (EXPLAIN) documented for runs list.

Implementation guidance

  • backend/tests/perf/locustfile.py: a user class hitting GET /campaigns, GET /campaigns/{id}/runs (various filters/sorts, paging 5 pages deep), GET /runs/{id} and GET /campaigns/{id}/modes, weighted by realistic dashboard usage.
  • Nightly job (appended to e2e.yml): seed --size large (10 000 runs), run locust --headless -u 20 -r 5 -t 60s --csv perf, then a small checker reading perf_stats.csv against backend/tests/perf/thresholds.toml (p95_ms = 200 per endpoint group, NFR-PERF-004).
  • Record EXPLAIN (ANALYZE, BUFFERS) for the runs-list query in the job log and in docs/evidence/T-106-perf.md on the first green run.
  • Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff PLR2004); public APIs typed (mypy strict) and documented.

Acceptance criteria

  • Nightly job reports p95 and fails above threshold (threshold from config file).
  • A threshold breach fails the job with a readable table.
  • Evidence doc committed after the first green run.
  • Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
  • Docs, config reference and CHANGELOG Unreleased updated where behaviour, keys or interfaces changed.
  • Definition of Done (doc 32 §3) satisfied.

Tests required

  • The perf job.

Dependencies

Blocked by: #159 (T-107), #149 (T-081d)

Blocks: #217 (T-130)

Parallelization notes

Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:

  • backend/tests/perf/locustfile.py
  • .github/workflows/e2e.yml (perf job)

Test/CI only.

Definition of Done

Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-106 (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.

References

Design docs: doc 18 §6 · doc 12 §7 · doc 02 §5

Requirements: NFR-PERF-004 · NFR-SCAL-001 (traceability: doc 28)

External:

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:apiREST + SSE API (FastAPI)area:ciCI/CD workflowsmilestone:M7M7 — APIpriority:P2Important, not blockingsize:S<= 1 daytaskChild task of a milestone epictype:testTest suites and test infrastructure

    Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions