# test-runner

Runs project test suites, isolates failure causes, and suggests fixes. The agent never modifies code directly, returning a diagnostic report instead.

- subagent · `type=agent` · Claude Code · 846 installs
- Author: davila7
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/development-team/test-runner.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/agents/test-runner

## What it does

The agent detects test frameworks across your project, handling tools like Jest or Pytest. It runs checks through shell commands. Exit codes serve as ground truth. When tests break, the subagent traces stack traces against the source code. This pinpoints whether the issue comes from application logic or environment mismatches.

By design, the agent lacks `Write` and `Edit` tools. Because of this restriction, it cannot touch project files or weaken test assertions to force a green run. Flaky tests receive special treatment. The subagent reruns them in isolation two or three times to catch intermittent timing issues. You get exact line references and actionable code fixes ready to apply.

## Install

### Claude Code (native platform)

1. **claude-code-templates**
```bash
npx claude-code-templates@latest --agent development-team/test-runner
```

2. **Manually: put the files in place**
- File: `.claude/agents/test-runner.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/test-runner.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/test-runner.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/development-team/test-runner.md

## When to use it
- pinpoint the root cause of failing local or CI test runs
- verify intermittent test failures through repeated isolated runs
- generate concrete patch proposals without risking deleted assertions
- distinguish real logic regressions from faulty mocks or environment issues

## Example prompts
- Run the test suite and diagnose why `test_payment_retry` failed
- Check if the new checkout logic broke any tests and pinpoint the causes
- Investigate the CI failure log and test whether that failure is flaky

## Similar
- [code-reviewer](https://affpapa.org/en/nevibecode/agents/anthropic-code-reviewer.md) — subagent · 31050 installs
- [code-reviewer](https://affpapa.org/en/nevibecode/agents/code-reviewer.md) — subagent · 31050 installs
- [test-engineer](https://affpapa.org/en/nevibecode/agents/test-engineer.md) — subagent · 9715 installs
- [code-reviewer](https://affpapa.org/en/nevibecode/agents/voltagent-community-code-reviewer.md) — subagent · 31050 installs
- [fullstack-developer](https://affpapa.org/en/nevibecode/agents/fullstack-developer.md) — subagent · 18117 installs
- [prompt-engineer](https://affpapa.org/en/nevibecode/agents/voltagent-community-prompt-engineer.md) — subagent · 16078 installs

From the same set: [davila7/claude-code-templates](https://affpapa.org/en/nevibecode/by/davila7/claude-code-templates.md) — 495 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md