load-test

name	load-test
description	Generate and run load tests with k6, Locust, or Artillery. Auto-detects API framework, creates realistic user behavior flows (browsing, authenticated CRUD, search-heavy), runs ramp-up, sustained, spike, and stress test profiles with defined latency and error-rate thresholds, then produces a bottleneck analysis with optimization recommendations. Use when you need to benchmark API performance, find breaking points under traffic, test auto-scaling, validate SLAs, or identify slow endpoints before production deploy.
version	2.0.0
category	test
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Detect the project's API framework, generate realistic load test scenarios, execute them, and produce a performance analysis report.

INPUT: $ARGUMENTS

If arguments are provided, focus load testing on those specific endpoints or scenarios. If no arguments are provided, generate load tests for ALL critical API endpoints.

============================================================ PHASE 1: API AND TOOL DISCOVERY

Step 1.1 -- Detect API Framework

Scan for the API framework:

Indicator	Framework
package.json with fastify	Fastify
package.json with express	Express
package.json with @nestjs/core	NestJS
requirements.txt with fastapi	FastAPI
requirements.txt with flask	Flask
requirements.txt with django	Django
go.mod with gin or echo or net/http	Go
Gemfile with rails	Rails

Step 1.2 -- Discover Endpoints

Find all API endpoints (same discovery method as /integration-test).

Classify each endpoint by criticality:

Priority	Criteria
CRITICAL	Auth endpoints, payment, data writes, main CRUD
HIGH	List/search endpoints, frequently accessed reads
MEDIUM	Settings, profile, secondary features
LOW	Admin-only, rarely accessed, health checks

Step 1.3 -- Detect Load Testing Tool

Check if a load testing tool is already installed:

Indicator	Tool
k6/ directory or *.k6.js files	k6
locustfile.py or locust in requirements	Locust
artillery.yml or artillery in package.json	Artillery
jmeter/ directory or *.jmx files	JMeter

If no tool is detected, select based on stack:

• Node.js / TypeScript projects: k6 (JavaScript-based, excellent performance)
• Python projects: Locust (Python-native)
• Any project: Artillery (YAML config, easy setup)

Install the selected tool:

• k6: Check if k6 is available via k6 version, if not suggest installation
• Locust: pip install locust
• Artillery: npm install -D artillery

============================================================ PHASE 2: SCENARIO DESIGN

Step 2.1 -- Define Virtual User Behaviors

Create realistic user behavior flows, not just individual endpoint hits:

FLOW 1 -- BROWSING USER:

1. GET / (landing page or root)
2. GET /api/[main-resource] (list view)
3. GET /api/[main-resource]/:id (detail view, pick from list)
4. Sleep 2-5s (reading time)
5. GET /api/[main-resource]/:id/[related] (related data)
6. Repeat steps 2-5 with different resources

FLOW 2 -- AUTHENTICATED USER:

1. POST /api/auth/login (obtain token)
2. GET /api/[user-resource] (user's data)
3. POST /api/[main-resource] (create something)
4. PUT /api/[main-resource]/:id (update it)
5. GET /api/[main-resource] (verify in list)
6. DELETE /api/[main-resource]/:id (cleanup)

FLOW 3 -- SEARCH-HEAVY USER:

1. GET /api/search?q=[term1] (broad search)
2. GET /api/search?q=[term2]&filter=[value] (filtered search)
3. GET /api/[resource]?sort=created&order=desc (sorted list)
4. GET /api/[resource]?page=2&limit=20 (pagination)

FLOW 4 -- API CONSUMER (if B2B/API product):

1. Rapid sequential API calls with different parameters
2. Batch operations if supported
3. Webhook delivery simulation

Use realistic think times between requests (1-5 seconds for humans, 100-500ms for API consumers).

Step 2.2 -- Define Load Profiles

Generate four standard load profiles:

RAMP-UP TEST:

• Start: 1 virtual user (VU)
• Ramp to target VUs over 2 minutes
• Hold at target for 5 minutes
• Ramp down over 1 minute
• Purpose: Find the performance baseline under normal load

SUSTAINED LOAD TEST:

• Constant load at expected peak traffic
• Duration: 10 minutes
• Purpose: Verify stability under sustained traffic

SPIKE TEST:

• Normal load for 2 minutes
• Sudden spike to 5x normal load for 1 minute
• Return to normal for 2 minutes
• Spike again to 10x for 30 seconds
• Return to normal for 2 minutes
• Purpose: Test auto-scaling and recovery

STRESS TEST:

• Start at normal load
• Increase by 20% every 2 minutes until failure
• Record the breaking point
• Purpose: Find system limits and failure modes

Step 2.3 -- Define Thresholds

Set pass/fail thresholds:

Metric	Threshold
HTTP error rate	< 1%
p95 response time	< 500ms
p99 response time	< 2000ms
Median response time	< 200ms
Requests per second (sustained)	> [baseline from ramp-up]
Failed requests	0 for non-stress tests

Adjust thresholds based on endpoint type:

• Read endpoints: stricter latency (p95 < 200ms)
• Write endpoints: allow higher latency (p95 < 1000ms)
• Search endpoints: moderate (p95 < 500ms)
• File upload endpoints: lenient (p95 < 5000ms)

============================================================ PHASE 3: TEST GENERATION

Step 3.1 -- Generate Test Scripts

FOR K6 (JavaScript):

Create k6/scenarios/ directory with:

• ramp-up.js: Ramp-up test with ramping-vus executor
• sustained.js: Constant load with constant-vus executor
• spike.js: Spike test with ramping-vus executor
• stress.js: Stress test with ramping-arrival-rate executor
• helpers/auth.js: Login helper, token management
• helpers/data.js: Test data generators (realistic names, emails, etc.)

Each script must:

• Use k6 groups to organize requests logically
• Include checks (response status, body content, response time)
• Use thresholds for pass/fail criteria
• Include realistic headers (User-Agent, Accept, Content-Type)
• Use parameterized data from CSV or JSON files

FOR LOCUST (Python):

Create locust/ directory with:

• locustfile.py: Main test with user classes
• scenarios/browsing.py: Browsing user behavior
• scenarios/authenticated.py: Authenticated user flows
• scenarios/search.py: Search-heavy user behavior
• helpers/auth.py: Authentication helper
• helpers/data.py: Test data generators

Each user class must:

• Use @task decorators with weights
• Include wait_time (between, constant)
• Handle auth token lifecycle
• Use on_start for login

FOR ARTILLERY (YAML + JS):

Create artillery/ directory with:

• ramp-up.yml: Ramp-up scenario
• sustained.yml: Sustained load scenario
• spike.yml: Spike test scenario
• stress.yml: Stress test scenario
• functions.js: Custom JS functions for data generation and auth
• data/users.csv: Test user data

Each config must:

• Define phases with duration and arrivalRate
• Use scenarios with weighted flows
• Include custom metrics capture
• Set ensure thresholds

Step 3.2 -- Generate Test Data

Create realistic test data files:

• users.csv or users.json: 100+ unique test users with realistic data
• search-terms.json: 50+ realistic search queries
• resource-data.json: Sample payloads for POST/PUT endpoints

Test data rules:

• Use realistic but clearly fake data (e.g., "[e-mail]")
• Include variety (different string lengths, numeric ranges)
• Include edge cases in data (unicode, special chars, max-length values)
• Never use production data or real credentials

============================================================ PHASE 4: EXECUTION

Step 4.1 -- Pre-flight Checks

Before running load tests:

• Verify the API server is running and responding
• Verify test data endpoints are accessible
• Run a single-user dry run of each scenario to catch script errors
• Confirm no rate limiting is enabled on the test environment

Step 4.2 -- Run Tests

Execute in this order:

1. Ramp-up test (establish baseline)
2. Sustained load test (verify stability)
3. Spike test (verify resilience)
4. Stress test (find breaking point)

Run commands:

Tool	Command
k6	k6 run --out json=results/[test].json k6/scenarios/[test].js
Locust	locust -f locust/locustfile.py --headless -u [users] -r [rate] -t [time] --csv=results/[test]
Artillery	artillery run artillery/[test].yml -o results/[test].json

Capture output for each test run.

Step 4.3 -- Results Collection

Parse results from each test run and extract:

• Total requests sent
• Requests per second (avg, min, max)
• Response times (min, median, p95, p99, max)
• Error rate (% of non-2xx responses)
• Error breakdown by status code
• Data transferred
• Virtual users at peak
• Threshold pass/fail status

============================================================ SELF-HEALING VALIDATION (max 3 iterations)

After generating and running tests, validate:

1. All generated test files compile/parse without syntax errors.
2. Run the generated tests — capture pass/fail results.
3. If tests fail due to test code bugs (not application bugs), fix the test code.
4. Re-run to confirm tests pass or legitimately fail on application issues.
5. Repeat up to 3 iterations.

IF STILL FAILING after 3 iterations:

• Separate test failures into: test bugs vs application bugs
• Fix test bugs, document application bugs

============================================================ OUTPUT

Load Test Report

Environment

• API Framework: [detected]
• Load Testing Tool: [selected]
• Target URL: [base URL]
• Endpoints tested: [count]

Endpoints Under Test

Endpoint	Method	Priority	Auth Required

Results by Test Profile

Ramp-Up Test (Baseline)

Metric	Value	Threshold	Status
Total requests	N	-	-
Avg RPS	N	-	-
Median latency	Nms	< 200ms	PASS/FAIL
p95 latency	Nms	< 500ms	PASS/FAIL
p99 latency	Nms	< 2000ms	PASS/FAIL
Error rate	N%	< 1%	PASS/FAIL

Sustained Load Test

[same table format]

Spike Test

[same table format + recovery time metric]

Stress Test

• Breaking point: N concurrent VUs / N RPS
• Failure mode: [what happened -- timeouts, 5xx, connection refused]
• Recovery: [did the system recover after load reduced?]

Endpoint Performance Breakdown

Endpoint	Median	p95	p99	Error Rate	Bottleneck?

Bottleneck Analysis

• Slowest endpoints: [list with latency]
• Highest error rate: [list with rates]
• Likely bottlenecks: [database queries, external APIs, CPU, memory]
• Recommendations: [caching, connection pooling, query optimization, indexing]

Performance Grade

• FAST: All thresholds pass, p95 < 200ms, handles 2x expected load
• ACCEPTABLE: All thresholds pass under normal load, some degradation at peak
• SLOW: Some thresholds fail under normal load, optimization needed
• CRITICAL: Significant failures under expected load, requires immediate attention

NEXT STEPS:

• "Performance bottlenecks found? Run /perf for detailed performance optimization."
• "Run /integration-test to verify correctness under normal conditions."
• "Run /test-suite to see overall test health including load test coverage."
• "Set up CI integration to run load tests on every deploy."

DO NOT:

• Do NOT run load tests against production environments.
• Do NOT use real user credentials or PII in test data.
• Do NOT run stress tests without confirming the target is a test/staging environment.
• Do NOT set unrealistic thresholds (sub-millisecond for complex queries).
• Do NOT generate tests that only hit a single URL repeatedly. Test realistic user flows.
• Do NOT skip the dry run. Script errors under load are hard to diagnose.
• Do NOT ignore error responses. Investigate every non-2xx status code.
• Do NOT report raw numbers without context. Always compare against thresholds.

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /load-test — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.