feat(06-03): implement Locust load test — self-bootstrap strategy, 4 tasks, SLA listener (D-04/D-05/D-06)

2026-06-03 18:48:47 +02:00
parent fb35f0e988
commit 5a93257ac0
2 changed files with 178 additions and 31 deletions
@@ -0,0 +1,91 @@
+# DocuVault Load Tests
+
+Phase 6 load test suite targeting the D-04/D-05/D-06 SLA requirements.
+
+## Prerequisites
+
+1. Install load-test dependencies (host or dedicated venv — **not** the production container):
+
+   ```bash
+   pip install -r backend/requirements-dev.txt
+   ```
+
+2. Start the full stack:
+
+   ```bash
+   docker compose up
+   ```
+
+   Backend, PostgreSQL, and MinIO must all be healthy before running.
+
+## Running the load test
+
+```bash
+locust --headless \
+       --users 50 \
+       --spawn-rate 10 \
+       --run-time 5m \
+       --host http://localhost:8000 \
+       --csv backend/load_tests/results \
+       -f backend/load_tests/locustfile.py
+```
+
+Exit code `0` = SLA targets met. Exit code `1` = at least one threshold breached.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOAD_TEST_EMAIL` | `loadtest@example.com` | Email used to register/login the load-test user |
+| `LOAD_TEST_PASSWORD` | `Loadtest123!@#` | Password for the load-test account (meets AUTH-01 strength rules) |
+
+Override before running:
+
+```bash
+LOAD_TEST_EMAIL=mytest@staging.example.com \
+LOAD_TEST_PASSWORD='MyS3cure!Pass' \
+locust --headless ...
+```
+
+## SLA thresholds (D-06)
+
+| Metric | Threshold | On breach |
+|--------|-----------|-----------|
+| p95 response time | < 200 ms | exit code 1 |
+| p99 response time | < 500 ms | exit code 1 |
+| Error ratio | ≤ 1% | exit code 1 |
+
+## Task weights (D-05 realistic session)
+
+| Task | Weight | Endpoint |
+|------|--------|----------|
+| List documents | 5 | `GET /api/documents/` |
+| Get document | 3 | `GET /api/documents/{id}` |
+| Upload document | 2 | `POST /api/documents/upload` (direct multipart, `target_backend=minio`) |
+| Refresh token | 1 | `POST /api/auth/refresh` |
+
+## Credential strategy
+
+`on_start()` uses **self-bootstrapping** (Option A): it calls `POST /api/auth/register`
+first (idempotent — 409 is silently ignored if the user already exists), then logs in.
+No manual seeding step required.
+
+## Cleanup
+
+Remove the load-test user from the database when no longer needed:
+
+```bash
+docker compose exec postgres psql -U docuvault -c \
+    "DELETE FROM users WHERE email='loadtest@example.com';"
+```
+
+## Results
+
+CSV files are written to `backend/load_tests/results_*.csv` by the `--csv` flag.
+These files are gitignored. To view a summary after a headless run, add `--html backend/load_tests/report.html`.
+
+## Notes
+
+- Load tests run **outside** the production container — install on the host or a test venv.
+- Do **not** run against a production URL without an explicit `--host` override and stakeholder sign-off.
+- The synthetic upload file (`_FAKE_PDF`) is a minimal valid PDF — it will be stored in MinIO during the run and cleared when the load-test user is deleted.