Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill testing-perf -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/testing-perf/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/testing-perf/

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

Similar skills

All skills for Testing and QA →

From the same set86

The whole set →
visualize-plan visualize-plan turns a proposed change into before-and-after architecture views, a risk map, and an execution sequence. Use it to review a plan or changes on the current branch. CX Codex +1 124installs market-sizing market-sizing is a Claude Code skill that calculates TAM, SAM and SOM using top-down and bottom-up methods, then cross-validates them. It runs when sizing a market or preparing pitch slides. CX Codex +1 124installs ai-ui-generation ai-ui-generation — a skill for Claude Code and Codex that enforces rules for generating, reviewing, and integrating AI-built UI components. Triggers on UI component creation and MCP visual rendering. CX Codex +1 123installs product-analytics The product-analytics skill evaluates A/B tests, cohort retention, and funnels. It helps explain adoption changes, conversion losses, and experiment outcomes. CX Codex +1 120installs chain-patterns chain-patterns — a set of patterns for multi-stage pipelines: MCP checks, handoff files, checkpoint recovery, isolated worktree agents, and cron monitoring. CX Codex +1 118installs design-to-code design-to-code — a skill for Claude Code that turns screenshots, descriptions, and URLs into React components. Assembles UI elements while reusing existing Storybook pieces and design tokens. CX Codex +1 116installs testing-unit The testing-unit skill provides patterns for unit tests, HTTP mocks, fixtures, and test data in Vitest, Jest, and pytest. It applies while writing tests or setting up test doubles. CX Codex +1 116installs design-context-extract design-context-extract extracts colors, typography, spacing, components, and motion from screenshots, URLs, or recordings. It returns tokens or Tailwind-ready output. CX Codex +1 112installs

Project sponsors

Companies that keep this analytics open