run-tests — Claude Code command: what it does, how to install
run-tests runs the project's tests in tiers: the ones your changes touch first, then the whole unit suite, then integration.
MIT ★ 1,424 updated 2026-10-06
.claude/commands/run-tests.mdWhat run-tests does
The command first works out how tests are run here. It looks for jest, vitest, mocha, ava or tap in package.json, checks for pytest.ini, pyproject.toml or setup.cfg, and picks up *_test.go or Cargo.toml. Then it reads git diff --name-only HEAD~1 and maps each changed file to its test by naming convention, so those run first.
The next tier is the full unit suite. Integration tests follow, and only when the tier before came back green. Failures get taken apart one at a time: the error message, the assertion that broke, the source line behind it, a suggested fix. The report holds a summary, the failing tests, anything that passed on a retry, and coverage when the project produces it.
When tests fail it goes after the source code, not the assertion, and reruns up to three times. The diff starts at HEAD~1, so a repo with no commit history gives the affected-test tier nothing to compare against.
What it helps with
- run only the tests your change touches
- map a changed file to its test file
- tell a real failure from a flaky test after a retry
- get a broken assertion traced back to source
- drive a red suite to green without running everything
Example prompts for the agent
- Run
/project-starter:run-testsand start with whatever my last change touches. - Tests are red after the refactor in
src/api/users.ts. Use/project-starter:run-testsand fix the code if that is where the bug sits. - Run
/project-starter:run-testsand tell me which failures look flaky.
How to install run-tests
Manually: put the files in place
.claude/commands/run-tests.mdCall it with /run-tests. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/run-tests.mdCall it with /prompts:run-tests. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/run-tests.prompt.mdManually: put the files in place
.gemini/commands/run-tests.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about run-tests
How do I install run-tests in Claude Code?
Place the command file at .claude/commands/run-tests.md inside your project. It ships with the project-starter plugin, so the call is /project-starter:run-tests.
What does run-tests do?
It runs tests in tiers: the ones affected by your changes, then the full unit suite, then integration. Failures get analysed and the code is patched, up to three attempts.
Why does it miss some affected tests?
The changed-file list comes from git diff --name-only HEAD~1, so it only covers the latest commit. With no commit history there is nothing to diff, and the fast tier has no input.
Source text
run-tests.md · MIT
--- description: Runs project tests intelligently. Identifies affected tests from changes and runs them first, then full suite. --- # Run Tests Run tests efficiently with tiered approach: affected tests first, then full suite. ## Phase 1: Detect Test Framework Identify testing setup: ```bash # Node.js cat package.json | grep -E '"(jest|vitest|mocha|ava|tap)"' # Python ls pytest.ini pyproject.toml setup.cfg 2>/dev/null | head -1 # Go ls *_test.go 2>/dev/null | head -1 # Rust ls Cargo.toml 2>/dev/null ``` ## Phase 2: Identify Affected Tests Based on git diff, find related tests: ```bash # Get changed files git diff --name-only HEAD~1 # Find corresponding test files # Convention: foo.ts -> foo.test.ts or foo.spec.ts ``` ## Phase 3: Run Tests (Tiered Approach) ### Tier 1: Affected Tests Only (Fast) ```bash # Node.js with Jest/Vitest npm test -- --findRelatedTests [changed files] npx vitest run --changed # Python with pytest pytest [specific test files] -x --tb=short # Go go test -run [TestName] ./... ``` ### Tier 2: Full Unit Test Suite If Tier 1 passes: ```bash npm test pytest tests/unit/ go test ./... cargo test ``` ### Tier 3: Integration Tests If Tier 2 passes: ```bash npm run test:integration pytest tests/integration/ go test -tags=integration ./... ``` ## Phase 4: Analyze Failures For each failure: 1. Parse error message 2. Identify failing assertion 3. Trace to source code 4. Suggest fix ## Output Format ``` ## Test Results: [PASS/FAIL] ### Summary - Total: X tests - Passed: Y - Failed: Z - Skipped: W - Duration: [time] ### Failed Tests 1. **test_name** - `file:line` - Expected: [value] - Actual: [value] - Likely cause: [analysis] - Suggested fix: [fix] ### Flaky Test Detection - [Any tests that passed on retry] ### Coverage (if available) - Lines: X% - Branches: Y% - Functions: Z% ### Recommendation [SAFE TO COMMIT / FIX REQUIRED / INVESTIGATE FLAKY] ``` ## Continue Until Green If tests fail: 1. Report the failure clearly 2. Attempt to fix the failing code (not just the test) 3. Re-run tests 4. Repeat until green or max 3 attempts ## Usage This command ships with the project-starter plugin. Invoke with: `/project-starter:run-tests`
© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2