Load Test

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:

Step 1.2 -- Discover Endpoints

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

Classify each endpoint by criticality:

Step 1.3 -- Detect Load Testing Tool

Check if a load testing tool is already installed:

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:

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., "loadtest-user-001@example.com")
• 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:

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

Results by Test Profile

Ramp-Up Test (Baseline)

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

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.