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:
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.
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:
# pyproject.toml
[tool.pytest.ini_options]
addopts = ["-n", "auto", "--dist", "loadscope"]
markers = [
"slow: marks tests as slow",
"smoke: critical path tests for CI/CD",
]
# 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:
@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
1---2name: testing-perf3license: MIT4compatibility: "Claude Code 2.1.277+."5description: "Load and performance tests with k6 and Locust, plus pytest speed (xdist). Use when writing load tests or speeding up a test suite."6user-invocable: false7disable-model-invocation: false8targets:9 - library: "k6"10 version: ">=1.0.0"11 - library: "locust"12 version: ">=2.46.6"13metadata:14 source: https://skillmd.com/skills/yonatangross/testing-perf15 owner-agent: "test-generator"16 category: document-asset-creation17 version: "2.1.0"18 author: "OrchestKit"19 complexity: "medium"20 tags: "testing, performance, k6, locust, pytest, load-testing, benchmarking"21allowed-tools: "Read Glob Grep WebFetch WebSearch"22---2324# Performance & Load Testing Patterns2526Focused skill for performance testing, load testing, and pytest execution optimization. Covers k6, Locust, pytest-xdist parallel execution, custom plugins, and test type classification.2728## Quick Reference2930| Area | File | Purpose |31|------|------|---------|32| **k6 Load Testing** | `rules/perf-k6.md` | Thresholds, stages, custom metrics, CI integration |33| **Locust Testing** | `rules/perf-locust.md` | Python load tests, task weighting, auth flows |34| **Test Types** | `rules/perf-types.md` | Load, stress, spike, soak test patterns |35| **Execution** | `rules/execution.md` | Coverage reporting, parallel execution, failure analysis |36| **Pytest Markers** | `rules/pytest-execution.md` | Custom markers, xdist parallel, worker isolation |37| **Pytest Plugins** | `rules/pytest-plugins.md` | Factory fixtures, plugin hooks, anti-patterns |38| **k6 Patterns** | `references/k6-patterns.md` | Staged ramp-up, authenticated requests, test types |39| **xdist Parallel** | `references/xdist-parallel.md` | Distribution modes, worker isolation, CI config |40| **Custom Plugins** | `references/custom-plugins.md` | conftest plugins, installable plugins, hook reference |41| **Perf Checklist** | `checklists/performance-checklist.md` | Planning, setup, metrics, load patterns, analysis |42| **Pytest Checklist** | `checklists/pytest-production-checklist.md` | Config, markers, parallel, fixtures, CI/CD |43| **Test Template** | `scripts/test-case-template.md` | Full test case documentation template |4445## k6 Quick Start4647Set up a load test with thresholds and staged ramp-up:4849```javascript50import http from 'k6/http';51import { check, sleep } from 'k6';5253export const options = {54 stages: [55 { duration: '30s', target: 20 }, // Ramp up56 { duration: '1m', target: 20 }, // Steady state57 { duration: '30s', target: 0 }, // Ramp down58 ],59 thresholds: {60 http_req_duration: ['p(95)<500'], // 95th percentile under 500ms61 http_req_failed: ['rate<0.01'], // Less than 1% error rate62 },63};6465export default function () {66 const res = http.get('http://localhost:8000/api/health');67 check(res, {68 'status is 200': (r) => r.status === 200,69 'response time < 200ms': (r) => r.timings.duration < 200,70 });71 sleep(1);72}73```7475Run: `k6 run --out json=results.json tests/load/api.js`7677### k6 v1.0+ (May 2025) — what changed7879- **Native TypeScript**: `k6 run tests/load/api.ts` — no compilation step needed.80- **Auto extension provisioning**: `k6 run` pulls required extensions automatically; manual `xk6 build` is superseded for most workflows.81- **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.82- **OTLP output built in**: `k6 run --out experimental-opentelemetry=...` — stream results straight to your tracing backend.8384```typescript85import http from 'k6/http'86import browser from 'k6/browser'87import { check } from 'k6'8889export const options = { vus: 5, duration: '30s' }9091export default async function () {92 const page = await browser.newPage()93 await page.goto('https://example.com')94 check(page, { 'title present': async p => (await p.title()).length > 0 })95 await page.close()96}97```9899## Performance Test Types100101| Type | Duration | VUs | Purpose | When to Use |102|------|----------|-----|---------|-------------|103| **Load** | 5-10 min | Expected traffic | Validate normal conditions | Every release |104| **Stress** | 10-20 min | 2-3x expected | Find breaking point | Pre-launch |105| **Spike** | 5 min | Sudden 10x surge | Test auto-scaling | Before events |106| **Soak** | 4-12 hours | Normal load | Detect memory leaks | Weekly/nightly |107108## pytest Parallel Execution109110Speed up test suites with pytest-xdist:111112```toml113# pyproject.toml114[tool.pytest.ini_options]115addopts = ["-n", "auto", "--dist", "loadscope"]116markers = [117 "slow: marks tests as slow",118 "smoke: critical path tests for CI/CD",119]120```121122```bash123# Run with parallel workers and coverage124pytest -n auto --dist loadscope --cov=app --cov-report=term-missing --maxfail=3125126# CI fast path — skip slow tests127pytest -m "not slow" -n auto128129# Debug mode — single worker130pytest -n 0 -x --tb=long131```132133## Worker Database Isolation134135When running parallel tests with databases, isolate per worker:136137```python138@pytest.fixture(scope="session")139def db_engine(worker_id):140 db_name = f"test_db_{worker_id}" if worker_id != "master" else "test_db"141 engine = create_engine(f"postgresql://localhost/{db_name}")142 yield engine143 engine.dispose()144```145146## Key Thresholds147148| Metric | Target | Tool |149|--------|--------|------|150| p95 response time | < 500ms | k6 |151| p99 response time | < 1000ms | k6 |152| Error rate | < 1% | k6 / Locust |153| Business logic coverage | 90% | pytest-cov |154| Critical path coverage | 100% | pytest-cov |155156## Decision Guide157158| Scenario | Recommendation |159|----------|----------------|160| JavaScript/TypeScript team | k6 for load testing |161| Python team | Locust for load testing |162| Need CI thresholds | k6 (built-in threshold support) |163| Need distributed testing | Locust (built-in distributed mode) |164| Slow test suite | pytest-xdist with `-n auto` |165| Flaky parallel tests | `--dist loadscope` for fixture grouping |166| DB-heavy tests | Worker-isolated databases with `worker_id` |167168## Related Skills169170- `ork:testing-unit` — Unit testing patterns, pytest fixtures171- `ork:testing-e2e` — End-to-end performance testing with Playwright172- `ork:performance` — Core Web Vitals and optimization patterns