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