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

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

## 2. Startup time

Build the app, then measure cold start:

```powershell
npm run build
npm run perf:startup
```

Optional parameters:

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

## 3. Health endpoint load

If the API is already running on port `4000`:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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
