testing-perf v2.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/2aff67bbb1f8fad3.

---
name: testing-perf
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Load and performance tests with k6 and Locust, plus pytest speed (xdist). Use when writing load tests or speeding up a test suite."
user-invocable: false
disable-model-invocation: false
targets:
  - library: "k6"
    version: ">=1.0.0"
  - library: "locust"
    version: ">=2.46.6"
metadata:
  owner-agent: "test-generator"
  category: document-asset-creation
  version: "2.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "testing, performance, k6, locust, pytest, load-testing, benchmarking"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
---

# Performance & Load Testing Patterns

Focused skill for performance testing, load testing, and pytest execution optimization. Covers k6, Locust, pytest-xdist parallel execution, custom plugins, and test type classification.

## Quick Reference

| Area | File | Purpose |
|------|------|---------|
| **k6 Load Testing** | `rules/perf-k6.md` | Thresholds, stages, custom metrics, CI integration |
| **Locust Testing** | `rules/perf-locust.md` | Python load tests, task weighting, auth flows |
| **Test Types** | `rules/perf-types.md` | Load, stress, spike, soak test patterns |
| **Execution** | `rules/execution.md` | Coverage reporting, parallel execution, failure analysis |
| **Pytest Markers** | `rules/pytest-execution.md` | Custom markers, xdist parallel, worker isolation |
| **Pytest Plugins** | `rules/pytest-plugins.md` | Factory fixtures, plugin hooks, anti-patterns |
| **k6 Patterns** | `references/k6-patterns.md` | Staged ramp-up, authenticated requests, test types |
| **xdist Parallel** | `references/xdist-parallel.md` | Distribution modes, worker isolation, CI config |
| **Custom Plugins** | `references/custom-plugins.md` | conftest plugins, installable plugins, hook reference |
| **Perf Checklist** | `checklists/performance-checklist.md` | Planning, setup, metrics, load patterns, analysis |
| **Pytest Checklist** | `checklists/pytest-production-checklist.md` | Config, markers, parallel, fixtures, CI/CD |
| **Test Template** | `scripts/test-case-template.md` | Full test case documentation template |

## k6 Quick Start

Set up a load test with thresholds and staged ramp-up:

```javascript
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 20 },  // Ramp up
    { duration: '1m', target: 20 },   // Steady state
    { duration: '30s', target: 0 },   // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],  // 95th percentile under 500ms
    http_req_failed: ['rate<0.01'],    // Less than 1% error rate
  },
};

export default function () {
  const res = http.get('http://localhost:8000/api/health');
  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 200ms': (r) => r.timings.duration < 200,
  });
  sleep(1);
}
```

Run: `k6 run --out json=results.json tests/load/api.js`

### k6 v1.0+ (May 2025) — what changed

- **Native TypeScript**: `k6 run tests/load/api.ts` — no compilation step needed.
- **Auto extension provisioning**: `k6 run` pulls required extensions automatically; manual `xk6 build` is superseded for most workflows.
- **Browser module import**: `import browser from 'k6/browser'` — **the old `k6/experimental/browser` path was removed in v0.52+**. Any generated code using `/experimental/` will fail.
- **OTLP output built in**: `k6 run --out experimental-opentelemetry=...` — stream results straight to your tracing backend.

```typescript
import http from 'k6/http'
import browser from 'k6/browser'
import { check } from 'k6'

export const options = { vus: 5, duration: '30s' }

export default async function () {
  const page = await browser.newPage()
  await page.goto('https://example.com')
  check(page, { 'title present': async p => (await p.title()).length > 0 })
  await page.close()
}
```

## Performance Test Types

| Type | Duration | VUs | Purpose | When to Use |
|------|----------|-----|---------|-------------|
| **Load** | 5-10 min | Expected traffic | Validate normal conditions | Every release |
| **Stress** | 10-20 min | 2-3x expected | Find breaking point | Pre-launch |
| **Spike** | 5 min | Sudden 10x surge | Test auto-scaling | Before events |
| **Soak** | 4-12 hours | Normal load | Detect memory leaks | Weekly/nightly |

## pytest Parallel Execution

Speed up test suites with pytest-xdist:

```toml
# pyproject.toml
[tool.pytest.ini_options]
addopts = ["-n", "auto", "--dist", "loadscope"]
markers = [
    "slow: marks tests as slow",
    "smoke: critical path tests for CI/CD",
]
```

```bash
# Run with parallel workers and coverage
pytest -n auto --dist loadscope --cov=app --cov-report=term-missing --maxfail=3

# CI fast path — skip slow tests
pytest -m "not slow" -n auto

# Debug mode — single worker
pytest -n 0 -x --tb=long
```

## Worker Database Isolation

When running parallel tests with databases, isolate per worker:

```python
@pytest.fixture(scope="session")
def db_engine(worker_id):
    db_name = f"test_db_{worker_id}" if worker_id != "master" else "test_db"
    engine = create_engine(f"postgresql://localhost/{db_name}")
    yield engine
    engine.dispose()
```

## Key Thresholds

| Metric | Target | Tool |
|--------|--------|------|
| p95 response time | < 500ms | k6 |
| p99 response time | < 1000ms | k6 |
| Error rate | < 1% | k6 / Locust |
| Business logic coverage | 90% | pytest-cov |
| Critical path coverage | 100% | pytest-cov |

## Decision Guide

| Scenario | Recommendation |
|----------|----------------|
| JavaScript/TypeScript team | k6 for load testing |
| Python team | Locust for load testing |
| Need CI thresholds | k6 (built-in threshold support) |
| Need distributed testing | Locust (built-in distributed mode) |
| Slow test suite | pytest-xdist with `-n auto` |
| Flaky parallel tests | `--dist loadscope` for fixture grouping |
| DB-heavy tests | Worker-isolated databases with `worker_id` |

## Related Skills

- `ork:testing-unit` — Unit testing patterns, pytest fixtures
- `ork:testing-e2e` — End-to-end performance testing with Playwright
- `ork:performance` — Core Web Vitals and optimization patterns