/testing-perf

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:

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` |