run-tests

Run pytest suites in parallel with coverage and CI-style XML reports.

112|6|Updated Mar 19, 2026
One-click install
npx skills add https://github.com/agentculture/culture --skill run-tests-agentculture
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: run-tests
Source: https://github.com/agentculture/culture/tree/main/.claude/skills/run-tests
Command: npx skills add https://github.com/agentculture/culture --skill run-tests-agentculture

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Running tests manually is slow and error-prone, and coverage results can become misleading when stale artifacts from previous runs are combined with current results.

Core Features & Use Cases

  • Parallel pytest runs: Uses pytest-xdist to run tests across CPU cores for faster feedback after changes.
  • Coverage with safe artifact handling: Enables coverage reporting and ensures stale .coverage shards are removed before combining worker results.
  • CI-matching mode: Provides a full CI-like invocation (parallel, coverage, and optional XML report) to detect issues that only show up under CI conditions.
  • When to use: After refactors, before merging, while validating a hotfix, or when diagnosing flaky tests by running a specific file without parallelism.

Quick Start

Use the command bash .claude/skills/run-tests/scripts/test.sh -p to run the pytest suite in parallel with verbose output.

Frequently Asked Questions about run-tests

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run pytest in parallel to speed up test execution after code changes?

Run pytest in parallel by using the test harness script with the parallelism flag, which leverages pytest-xdist to distribute tests across CPU cores for faster feedback. This provides rapid validation after refactors or hotfixes.

Why does my pytest code coverage report show misleading or incomplete results?

Misleading pytest code coverage results often occur when stale `.coverage` shards from previous runs are combined with current results. The test harness removes stale artifacts before combining worker outputs to ensure accurate reporting.

How do I validate my tests with a CI-like quality gate before merging a pull request?

Validate tests with a CI-like quality gate by running the test harness in CI mode, which enables parallel execution, coverage reporting, and optional XML output to detect issues that only appear under CI conditions before merging.

Can I run a specific failing pytest file without parallel execution to debug flaky tests?

Yes, you can run a specific failing pytest file without parallelism to diagnose flaky tests. The test harness supports targeted debugging by allowing execution of individual test files without distributing them across CPU cores.

Do I need pytest-xdist to run tests with this bash test runner?

pytest-xdist is required for parallel test execution with this bash test runner. The script uses it to distribute tests across CPU cores and combines the resulting coverage shards from each worker for the final report.

What is the best way to combine coverage data from parallel pytest workers?

The best way to combine coverage data from parallel pytest workers is to clear stale `.coverage` shards before execution and let the test harness safely merge the worker results, failing safely if reports cannot be produced.