testing-perf — Claude Code skill: k6, Locust, pytest-xdist load tests
The testing-perf skill for Claude Code runs load and performance tests with k6 and Locust and parallelizes pytest with xdist. It activates when writing load tests or speeding up test suite runs.
MIT 120 installs ★ 305 updated 2026-11-07
npx skills add yonatangross/orchestkit --skill testing-perf -a claude-codeWhat testing-perf does
Includes rules for k6 (thresholds, stages, custom metrics), Locust (task weighting, auth flows), test type classification (load, stress, spike, soak), pytest markers, and xdist parallel execution with worker database isolation. Requires k6 1.0+ or Locust 2.46.6+. Compatible with Claude Code 2.1.277+.
k6 v1.0 brought native TypeScript, removed the k6/experimental/browser path (now k6/browser), and added built-in OTLP output. For database tests, the skill shows a fixture using worker_id so each xdist worker writes to a separate database copy.
What it helps with
- write a load test with p95 thresholds and a target number of virtual users
- speed up pytest suite execution with parallel workers and scope grouping
- isolate databases between xdist workers to prevent test conflicts
- choose between k6 and Locust based on team stack and CI needs
- set up staged ramp-up for a load scenario
Example prompts for the agent
- Write a k6 test with three-stage ramp-up: 30 seconds to 20 VUs, one minute steady, 30 seconds to zero
- Add pytest-xdist with worker database isolation and coverage
- Show a Locust scenario with weighted tasks and error rate under 1%
How to install testing-perf
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-perf -a claude-code2Manually: put the files in place
~/.claude/skills/testing-perf/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/testing-perf/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-perf -a codex2Manually: put the files in place
.agents/skills/testing-perf/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-perf -a cursor2Manually: put the files in place
.cursor/skills/testing-perf/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/testing-perf2Manually: put the files in place
.github/skills/testing-perf/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-perf -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/testing-perfManually: put the files in place
.devin/skills/testing-perf/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-perf -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about testing-perf
How to install testing-perf in Claude Code?
Run npx skills add yonatangross/orchestkit --skill testing-perf -a claude-code, then open ~/.claude/skills/testing-perf/SKILL.md.
What does testing-perf do?
Provides rules and templates for k6 and Locust load testing, parallel pytest execution with xdist and database isolation, test type selection (load, stress, spike, soak), and metric threshold setup.
Which k6 version does testing-perf require?
The skill targets k6 1.0+. This version ships native TypeScript and removed the k6/experimental/browser path — now import browser from 'k6/browser'.
Source text
SKILL.md · MIT
---
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
© OrchestKit · MIT · yonatangross/orchestkit