Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/run-tests.md
Open on GitHub

What 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-tests and start with whatever my last change touches.
  • Tests are red after the refactor in src/api/users.ts. Use /project-starter:run-tests and fix the code if that is where the bug sits.
  • Run /project-starter:run-tests and tell me which failures look flaky.

How to install run-tests

Manually: put the files in place

.claude/commands/run-tests.md

Call it with /run-tests. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Testing and QA →

From the same set46

The whole set →
validate-build The validate-build command detects a project’s build system and runs checks for Node.js, Python, Go, or Rust. Use it after changes and before committing. CX Codex +1 ★ 1,424repo stars mentor mentor puts the assistant into teaching mode: it explains the reasoning behind code, walks through how it works and suggests what to try next. CX Codex +1 ★ 1,424repo stars review Sets Claude Code to run strict engineering reviews, triaging issues from critical security flaws to minor stylistic fixes. CX Codex +1 ★ 1,424repo stars lint-check lint-check runs the linters your project already configures, sorts findings by severity and can auto-fix style. Useful right before a commit instead of waiting for CI. CX Codex +1 ★ 1,424repo stars parallel-review parallel-review runs code review across multiple directories or files simultaneously, one subagent per target. CX Codex +1 ★ 1,424repo stars code-simplifier The code-simplifier command reviews recent changes and proposes cleaner code without changing behavior. Use it after implementing a feature or refactoring. CX Codex +1 ★ 1,424repo stars security-scan security-scan is a command for Claude Code that checks a repository for hardcoded secrets, vulnerable dependencies, injection, XSS and weak config before a commit or PR. CX Codex +1 ★ 1,424repo stars verify-changes verify-changes executes adversarial multi-subagent verification across recent code diffs to weed out bugs and false alarms. CX Codex +1 ★ 1,424repo stars

Project sponsors

Companies that keep this analytics open