| name | django-pytest-performance-suite |
| description | Use when building Django performance regression coverage with pytest-benchmark for ORM, views, schema, transactions, or backend behavior. Match the project's production database engine and topology; never prescribe one. Excludes one-off profiling, browser rendering, APM, and non-Django services. Return deterministic scenarios, correctness and query/operation guards, calibrated budgets, reports, and baseline maintenance. |
Django Pytest Performance Suite
Workflow
- Inspect the existing Django, database, pytest, command, and CI conventions. Record the production backend, driver, engine version, topology, relevant options, and workload scale.
- Choose high-value uncached work: ORM queries, builders/read models, request wrappers, serializers, admin paths, migrations, schema operations, transactions, or database-backend behavior.
- Define the database-fidelity contract before implementing tests. Reproduce the production-relevant engine and access mode; document any deliberate approximation and forbid production latency claims from it.
- Create a separate performance lane with dedicated settings, marker, commands, and on-demand CI. Keep it out of the default unit-test loop.
- Seed realistic scenarios deterministically. Fix time, identifiers, randomness, ordering, and external side effects; build expensive data outside benchmark rounds.
- Run correctness before timing. Normalize results, compare a snapshot or summary hash, then enforce a query or operation cap appropriate to the measured layer.
- Benchmark stable work with
pytest-benchmark. Exclude setup and instrumentation unless their cost is the explicit subject of the case.
- Calibrate timing budgets from repeated clean runs on the intended stable runner. Report machine-readable and human-readable results with environment and database context.
- Keep correctness refresh and timing-baseline acceptance as separate, explicit maintenance actions. Add a coverage registry only for a bounded family of surfaces where drift is a real risk.
Use the repository's package manager and task runner. Preserve existing test conventions unless they prevent an isolated, reproducible lane.
Decisions
- Never choose PostgreSQL, Turso, SQLite, or another database merely because the skill prefers it. Follow the target project's production contract.
- For embedded production databases, benchmark through the real Django backend and driver against an isolated local file or memory mode only when that mode matches the contract.
- For client-server or remote databases, preserve the relevant protocol and topology. Measure managed-network latency separately when CI cannot reproduce it faithfully.
- Prefer
RequestFactory only when a request surface is under test and middleware is outside the measured contract.
- Use full normalized snapshots for reviewable results and summaries plus hashes for very large payloads.
- Treat query or operation caps as deterministic early warnings and timing budgets as runner-specific guardrails.
- Never update snapshots or budgets automatically after a failure.
Freshness
Verify current Django, pytest, pytest-benchmark, database-backend, and driver behavior from the target repository and primary documentation when it affects instrumentation or configuration. Record the checked versions in reports; do not freeze a package or database version in this skill.
Validation
Run untimed correctness and query/operation checks before timing. Repeat strict runs on the intended runner to quantify variance before enforcing a budget. Verify that ordinary tests exclude the performance marker, reports identify every case and environment, and maintenance commands cannot conflate semantic changes with performance changes.
Resources
