Load-Test Harness

# Load-Test Harness

A Claude Code project configuration for designing, running, and evaluating load and stress tests.

## What it does

When this harness is active, Claude Code acts as a performance-testing engineer. It helps
you define realistic load scenarios, shape ramp profiles, set SLO thresholds, execute a
run, and produce a pass/fail report against those thresholds.

- **Scenario definitions:** Claude prompts you for endpoints, payloads, and concurrency
  targets before generating any script, so the test reflects real traffic patterns.
- **Ramp profiles:** Supports constant load, step ramps, and spike/soak variants. Claude
  explains the trade-off of each before you choose.
- **SLO gates:** You specify p95/p99 latency budgets and max error-rate; the report marks
  each SLO as PASS or FAIL against the measured values.
- **Tool focus:** The `settings.json` restricts bash to load-test runners and read-only
  commands, so Claude stays in test-analysis mode.

## Files in this harness

| File | Purpose |
|------|---------|
| `README.md` | This guide — Claude reads it as its working instructions |
| `settings.json` | Claude Code project settings — copy to `.claude/settings.json` |

## Setup

1. Copy `settings.json` to `.claude/settings.json` in your project root.
2. Open your project in Claude Code.
3. Tell Claude which load-testing tool you use and where the target service runs, e.g.:
   "We use k6 against a staging server at https://api-staging.example.com."

Claude will scaffold a scenario script, a `slo.json` thresholds file, and a run command.

## Workflow reference

### Defining a scenario
Tell Claude: "Define a load scenario for the `POST /orders` endpoint."

Claude will ask:
- What does a realistic request payload look like?
- What virtual-user count represents typical peak traffic?
- Are there authentication headers or session state to simulate?

Then it generates a k6/Locust/Artillery script and a companion `slo.json`.

### Running a test
Tell Claude: "Run the orders scenario at 50 VUs for 5 minutes."

Claude will execute the script, stream live metrics, and produce a structured summary
when the run completes.

### Evaluating results
Tell Claude: "Evaluate the last run against our SLOs."

Claude reads the test output, compares each metric against `slo.json`, and returns
a report with a PASS or FAIL verdict for each threshold and an overall go/no-go.

## Example output

```
SLO Report — POST /orders — 2026-07-07
──────────────────────────────────────
p95 latency   target: ≤ 300 ms   measured: 218 ms   ✓ PASS
p99 latency   target: ≤ 800 ms   measured: 540 ms   ✓ PASS
error rate    target: ≤ 0.1 %    measured: 0.03 %   ✓ PASS
throughput    target: ≥ 200 rps  measured: 312 rps  ✓ PASS

Overall verdict: PASS
```

## Commands

- `/loadtest <scenario>` — Run a named scenario and stream live metrics until completion.
- `/define-slo` — Interactively define SLO thresholds (latency, error rate, throughput)
  and write them to `slo.json`.
- `/slo-report` — Evaluate the most recent test run against `slo.json` and return a
  structured PASS/FAIL report.

## Allowed bash commands

The harness permits load-test runners and read-only inspection:

- `Bash(npx k6*)`, `Bash(k6*)` — k6 load tests
- `Bash(locust*)` — Locust load tests
- `Bash(npx artillery*)` — Artillery load tests
- `Bash(curl*)` — health-check the target before a run
- `Bash(git diff*)`, `Bash(git status*)`, `Bash(cat*)` — inspect scripts and results

Destructive commands and pushes are blocked.

## Known limitations

- The harness does not provision infrastructure; the target service must already be running.
- Distributed load (multiple load-generators) requires manual setup outside the harness.

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(**)",
      "Edit(**)",
      "Bash(npx k6*)",
      "Bash(k6*)",
      "Bash(locust*)",
      "Bash(npx artillery*)",
      "Bash(artillery*)",
      "Bash(curl*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git log*)",
      "Bash(cat*)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(git reset --hard*)",
      "Bash(git restore*)",
      "Bash(git clean*)",
      "Bash(rm -rf*)"
    ]
  }
}