back_end_oudelaa/PERFORMANCE_TESTING.md

Performance Testing

This project now includes built-in scripts to check correctness, startup time, endpoint latency, and basic load.

1. Correctness first

Run these before any performance test:

npm run build
npm test -- --runInBand
npm run test:e2e -- --runInBand

2. Startup time

Build the app, then measure cold start:

npm run build
npm run perf:startup

Optional parameters:

node scripts/startup-benchmark.js --port 4200 --timeout 45000

3. Health endpoint load

If the API is already running on port 4000:

npm run perf:health

This runs a simple GET benchmark against http://127.0.0.1:4000/api/v1/health.

4. Custom endpoint load

Examples:

node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/health --duration 20 --concurrency 50
node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/feed/trending --header "Authorization: Bearer YOUR_TOKEN" --duration 30 --concurrency 25
node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/auth/login --method POST --body "{\"email\":\"user@example.com\",\"password\":\"secret\"}" --duration 20 --concurrency 10

Supported options:

• --url
• --method
• --duration
• --concurrency
• --timeout
• --warmup
• --min-success-rate (percentage from 0 to 100)
• --min-rps (minimum requests per second)
• --max-p95 (maximum p95 latency in milliseconds)
• --max-p99 (maximum p99 latency in milliseconds)
• --header "Key: Value"
• --body
• --body-file

Automated performance gates

Add one or more gates to turn a benchmark into a CI regression check:

node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/health --duration 15 --concurrency 20 --min-success-rate 99.9 --min-rps 1000 --max-p95 100 --max-p99 150

Or run the provided health baseline:

npm run perf:health:gate

All configured gates must pass. The JSON summary contains the individual gate results, followed by a readable PASS/FAIL report. A performance regression exits with code 2; invalid arguments or runtime errors exit with code 1. Calibrate thresholds on production-like staging hardware rather than copying local numbers into deployment policy.

The gate parser, evaluator, and process exit behavior have a standalone test suite:

npm run test:perf

5. What to watch

• requestsPerSecond: throughput
• successRate: percentage of successful requests
• non2xxCount: server or validation failures
• timeoutCount: slow requests
• latencyMs.p95 and latencyMs.p99: tail latency under load

6. Practical test order

1. build
2. unit tests
3. e2e tests
4. startup benchmark
5. health benchmark
6. authenticated benchmarks for hot endpoints:
   • auth/login
   • feed/me
   • feed/trending
   • posts
   • chat/messages
   • notifications

7. Real API benchmark examples

Login:

node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/auth/login --method POST --header "Content-Type: application/json" --body "{\"email\":\"user@example.com\",\"password\":\"secret123\"}" --duration 20 --concurrency 10

Trending feed with bearer token:

node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/feed/trending --header "Authorization: Bearer YOUR_ACCESS_TOKEN" --duration 30 --concurrency 25

Authenticated user feed:

node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/feed/me?limit=20 --header "Authorization: Bearer YOUR_ACCESS_TOKEN" --duration 30 --concurrency 15

Notifications:

node scripts/load-test.js --url http://127.0.0.1:4000/api/v1/notifications --header "Authorization: Bearer YOUR_ACCESS_TOKEN" --duration 20 --concurrency 15

8. Limits

These scripts are useful local benchmarks, not full production profiling. They do not replace:

• database profiling
• CPU and memory profiling
• distributed load tools like k6 or Gatling
• multi-instance tests behind a reverse proxy