From 5a93257ac05dea09f9670265412aea6ac9714ab2 Mon Sep 17 00:00:00 2001 From: curo1305 Date: Wed, 3 Jun 2026 18:48:47 +0200 Subject: [PATCH] =?UTF-8?q?feat(06-03):=20implement=20Locust=20load=20test?= =?UTF-8?q?=20=E2=80=94=20self-bootstrap=20strategy,=204=20tasks,=20SLA=20?= =?UTF-8?q?listener=20(D-04/D-05/D-06)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/load_tests/README.md | 91 ++++++++++++++++++++++++ backend/load_tests/locustfile.py | 118 +++++++++++++++++++++++-------- 2 files changed, 178 insertions(+), 31 deletions(-) create mode 100644 backend/load_tests/README.md diff --git a/backend/load_tests/README.md b/backend/load_tests/README.md new file mode 100644 index 0000000..67a256e --- /dev/null +++ b/backend/load_tests/README.md @@ -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. diff --git a/backend/load_tests/locustfile.py b/backend/load_tests/locustfile.py index fbf44b6..d68617b 100644 --- a/backend/load_tests/locustfile.py +++ b/backend/load_tests/locustfile.py @@ -1,72 +1,128 @@ """Locust load test for DocuVault — D-04, D-05, D-06. -Run: +Strategy: self-bootstrapping (Option A) — on_start registers the load-test +user (409 ignored if already exists), then logs in to get an access token. + +Run (headless, matches Phase 6 SLA gate): 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 -Prerequisites: a user with LOAD_TEST_EMAIL/LOAD_TEST_PASSWORD must exist in the -DB, or on_start will register one automatically (idempotent — 409 is ignored). +Prerequisites: + pip install -r backend/requirements-dev.txt + docker compose up # backend, postgres, minio must be running -Full implementation is in plan 06-03. This skeleton defines the class shape and -SLA listener so downstream CI tooling can import the file without errors. +Exit codes (enforced by check_sla listener): + 0 — all SLA thresholds met + 1 — p95 > 200 ms, OR p99 > 500 ms, OR fail_ratio > 1% + +Cleanup the load-test user: + docker compose exec postgres psql -U docuvault -c \\ + "DELETE FROM users WHERE email='loadtest@example.com';" """ import os +from io import BytesIO from locust import HttpUser, between, events, task TEST_EMAIL = os.environ.get("LOAD_TEST_EMAIL", "loadtest@example.com") TEST_PASSWORD = os.environ.get("LOAD_TEST_PASSWORD", "Loadtest123!@#") +TEST_HANDLE = "loadtestuser" + +# Minimal synthetic PDF — valid enough for the upload parser +_FAKE_PDF = b"%PDF-1.4\n1 0 obj<>endobj\nxref\n0 2\ntrailer<>\n%%EOF" class DocuVaultUser(HttpUser): - """Simulated DocuVault end-user. + """Simulated DocuVault end-user exercising all authenticated endpoints. - Scenarios (weighted tasks): - - list_documents (weight 5) — GET /api/documents/ - - upload_document (weight 2) — POST /api/documents/upload-url flow - - refresh_token (weight 1) — POST /api/auth/refresh + Task weights mirror a realistic read-heavy session per D-05: + 5 — list documents (most common action) + 3 — get single document + 2 — upload a document + 1 — refresh access token """ wait_time = between(0.5, 2.0) access_token: str = "" def on_start(self) -> None: - """Authenticate before running tasks. - - Registers the load-test user if it does not exist (409 is silently - ignored), then performs a login to obtain an access token. - """ - raise NotImplementedError("implementation in 06-03") + self.client.post( + "/api/auth/register", + json={"handle": TEST_HANDLE, "email": TEST_EMAIL, "password": TEST_PASSWORD}, + ) + resp = self.client.post( + "/api/auth/login", + json={"email": TEST_EMAIL, "password": TEST_PASSWORD}, + name="POST /api/auth/login", + ) + if resp.status_code == 200: + self.access_token = resp.json().get("access_token", "") + else: + self.environment.runner.quit() def _auth_headers(self) -> dict: - """Return Authorization header dict for authenticated requests.""" - raise NotImplementedError("implementation in 06-03") + return {"Authorization": f"Bearer {self.access_token}"} @task(5) def list_documents(self) -> None: - """GET /api/documents/ — highest-frequency task.""" - raise NotImplementedError("implementation in 06-03") + self.client.get("/api/documents/", headers=self._auth_headers(), name="GET /api/documents/") + + @task(3) + def get_document(self) -> None: + resp = self.client.get( + "/api/documents/", + headers=self._auth_headers(), + name="GET /api/documents/ (for get_document)", + ) + if resp.status_code == 200: + docs = resp.json() + if docs: + doc_id = docs[0]["id"] + self.client.get( + f"/api/documents/{doc_id}", + headers=self._auth_headers(), + name="GET /api/documents/{id}", + ) @task(2) def upload_document(self) -> None: - """Two-step presigned upload: POST /upload-url → PUT MinIO → POST /{id}/confirm.""" - raise NotImplementedError("implementation in 06-03") + # Direct single-step upload to /api/documents/upload (confirmed against documents.py: + # accepts UploadFile `file` + Form `target_backend` — simpler than the presigned flow). + self.client.post( + "/api/documents/upload", + headers=self._auth_headers(), + files={"file": ("load_test.pdf", BytesIO(_FAKE_PDF), "application/pdf")}, + data={"target_backend": "minio"}, + name="POST /api/documents/upload", + ) @task(1) def refresh_token(self) -> None: - """POST /api/auth/refresh — rotates the httpOnly refresh cookie.""" - raise NotImplementedError("implementation in 06-03") + self.client.post( + "/api/auth/refresh", + headers=self._auth_headers(), + name="POST /api/auth/refresh", + ) @events.quitting.add_listener def check_sla(environment, **kwargs) -> None: - """Fail the Locust run if SLA thresholds are breached. + """Gate the Locust exit code on D-06 SLA thresholds.""" + stats = environment.runner.stats.total + p95 = stats.get_response_time_percentile(0.95) + p99 = stats.get_response_time_percentile(0.99) + fail_ratio = stats.fail_ratio - Thresholds (from D-06): - - p95 response time > 200 ms → exit code 1 - - p99 response time > 500 ms → exit code 1 - - error ratio > 1% → exit code 1 - """ - raise NotImplementedError("implementation in 06-03") + if fail_ratio > 0.01: + print(f"SLA FAIL: fail_ratio={fail_ratio:.2%} > 1%") + environment.process_exit_code = 1 + elif p95 > 200: + print(f"SLA FAIL: p95={p95:.0f}ms > 200ms") + environment.process_exit_code = 1 + elif p99 > 500: + print(f"SLA FAIL: p99={p99:.0f}ms > 500ms") + environment.process_exit_code = 1 + else: + print(f"SLA PASS: p95={p95:.0f}ms p99={p99:.0f}ms fail_ratio={fail_ratio:.2%}")