kite/backend/load_tests/README.md

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):

   pip install -r backend/requirements-dev.txt
   

2. Start the full stack:

   docker compose up
   

   Backend, PostgreSQL, and MinIO must all be healthy before running.

Running the load test

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:

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:

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.