# Load Tests

This directory contains k6 load test suites for StellaOps performance testing.

## Prerequisites

- [k6](https://k6.io/docs/getting-started/installation/) installed
- Target environment accessible
- (Optional) Grafana k6 Cloud for distributed testing

## Test Suites

### TTFS Load Test (`ttfs-load-test.js`)

Tests the Time to First Signal endpoint under various load conditions.

**Scenarios:**
- **Sustained**: 50 RPS for 5 minutes (normal operation)
- **Spike**: Ramp from 50 to 200 RPS, hold, ramp down (CI burst simulation)
- **Soak**: 25 RPS for 15 minutes (stability test)

**Thresholds (per Advisory §12.4):**
- Cache-hit P95 ≤ 250ms
- Cold-path P95 ≤ 500ms
- Error rate < 0.1%

**Run locally:**
```bash
k6 run tests/load/ttfs-load-test.js
```

**Run against staging:**
```bash
k6 run --env BASE_URL=https://staging.stellaops.local \
       --env AUTH_TOKEN=$STAGING_TOKEN \
       tests/load/ttfs-load-test.js
```

**Run with custom run IDs:**
```bash
k6 run --env BASE_URL=http://localhost:5000 \
       --env RUN_IDS='["run-1","run-2","run-3"]' \
       tests/load/ttfs-load-test.js
```

## CI Integration

Load tests can be integrated into CI pipelines. See `.gitea/workflows/load-test.yml` for an example.

```yaml
load-test-ttfs:
  runs-on: ubuntu-latest
  needs: [deploy-staging]
  steps:
    - uses: grafana/k6-action@v0.3.1
      with:
        filename: tests/load/ttfs-load-test.js
      env:
        BASE_URL: ${{ secrets.STAGING_URL }}
        AUTH_TOKEN: ${{ secrets.STAGING_TOKEN }}
```

## Results

Test results are written to `results/ttfs-load-test-latest.json` and timestamped files.

Use Grafana Cloud or local Prometheus + Grafana to visualize results:

```bash
k6 run --out json=results/metrics.json tests/load/ttfs-load-test.js
```

## Writing New Load Tests

1. Create a new `.js` file in this directory
2. Define scenarios, thresholds, and the default function
3. Use custom metrics for domain-specific measurements
4. Add handleSummary for result export
5. Update this README

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `BASE_URL` | Target API base URL | `http://localhost:5000` |
| `RUN_IDS` | JSON array of run IDs to test | `["run-load-1",...,"run-load-5"]` |
| `TENANT_ID` | Tenant ID header value | `load-test-tenant` |
| `AUTH_TOKEN` | Bearer token for authentication | (none) |