Run Tests
Execute the project's test suite, analyze failures, attempt fixes, and re-run. Designed as a reusable sub-workflow called by /develop, /bugfix, and /pre-commit.
Uses test-strategy skill for test writing patterns and coverage targets.
1. Detect Test Stack
Read TESTING.md (if exists) for test commands, infrastructure, and credentials. Fall back to CLAUDE.md and project config to determine:
| Signal |
Stack |
Runner |
package.json + vitest/jest |
TypeScript/JS |
npx vitest run / npx jest |
pom.xml / build.gradle |
Java |
mvn test -q / gradle test |
pyproject.toml / pytest.ini |
Python |
pytest -x -q |
go.mod |
Go |
go test ./... |
*.csproj |
.NET |
dotnet test |
2. Run Tests
Execute the test suite:
// turbo
<test-command>
Capture:
- Exit code: 0 = all pass, non-zero = failures
- Output: Test names, pass/fail counts, error messages, stack traces
Test runner stdout > 2000 tokens is normalized by the tool-output-normalize.py hook (G2) before injection back into context — large failure dumps get summarized envelope metadata + extracted top-k failures rather than raw dump. This protects context budget on noisy suites.
3. Analyze Failures
If tests fail, for each failure:
- Read the failing test — understand what it asserts
- Read the error message and stack trace — identify the actual vs expected
- Classify the failure:
| Classification |
Action |
| Code bug — test is correct, implementation is wrong |
Fix the implementation (Step 4) |
| Test bug — test is wrong or outdated |
Fix the test (Step 4) |
| Environment issue — missing dependency, port conflict, DB down |
Report to user (Step 5) |
| Flaky test — passes on re-run without changes |
Flag for investigation |
4. Fix and Re-Run
For auto-fixable failures:
- Apply the appropriate stack-specific role (
Agent(frontend-engineer), Agent(java-engineer), Agent(python-engineer), etc.)
- Apply the minimal fix — do not refactor unrelated code
- Re-run the failing test(s) specifically:
| Stack |
Run Single Test |
| Vitest |
npx vitest run <test-file> |
| Jest |
npx jest <test-file> |
| pytest |
pytest <test-file>::<test-name> -v |
| JUnit/Maven |
mvn test -pl <module> -Dtest=<TestClass>#<method> |
| Go |
go test -run <TestName> ./path/... |
- If the fix works, re-run the full suite to check for regressions
- Max 3 fix attempts per failure — if still failing after 3 tries, escalate to user
5. Coverage Check (if available)
Run coverage report:
| Stack |
Command |
| Vitest |
npx vitest run --coverage |
| Jest |
npx jest --coverage |
| pytest |
pytest --cov=<package> --cov-report=term-missing |
| Go |
go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out |
| JUnit |
mvn jacoco:report |
Compare against test-strategy skill targets:
- Line coverage ≥ 80% (hard minimum 60%)
- Branch coverage ≥ 75% (hard minimum 50%)
- New code coverage ≥ 90%
6. Summary
## Test Results
| Metric | Value |
|--------|-------|
| Total tests | X |
| Passed | X |
| Failed | X |
| Skipped | X |
| Duration | Xs |
| Coverage | X% (target: 80%) |
### Failures Fixed
- [test name] — [what was wrong] — [fix applied]
### Remaining Failures (needs attention)
- [test name] — [error] — [classification]
### Coverage Gaps
- [file/module] — [current%] — [uncovered lines]
**Overall**: ✅ PASS / ❌ FAIL — [action needed]
Integration
- Called by:
/develop, /bugfix, /pre-commit
- Skills:
test-strategy skill
- Roles:
Agent(qa-engineer) (test strategy), stack-specific role (implementation)
- Hooks:
tool-output-normalize.py (G2 normalization for test runner stdout per Step 2)
1---2name: run-tests3description: Use this skill when verifying code by running tests, analyzing failures, or addressing coverage gaps — to run the test suite, analyze failures, auto-fix obvious issues, and re-run; serves as a sub-workflow for /develop, /bugfix, and /pre-commit and uses the `test-strategy` skill.4---56<!-- ARCHITECTURAL NOTE: intentional model-invocable companion — deliberately no `context: fork` and no `disable-model-invocation`. Reusable sub-workflow composed into the caller's main thread by `/develop`, `/bugfix`, and `/pre-commit`; forking it would break that composition and disabling model-invocation would stop auto-load on test-verification tasks. Not a defect — do not reclassify. -->78# Run Tests910Execute the project's test suite, analyze failures, attempt fixes, and re-run. Designed as a reusable sub-workflow called by `/develop`, `/bugfix`, and `/pre-commit`.1112Uses `test-strategy` skill for test writing patterns and coverage targets.1314## 1. Detect Test Stack1516Read `TESTING.md` (if exists) for test commands, infrastructure, and credentials. Fall back to `CLAUDE.md` and project config to determine:1718| Signal | Stack | Runner |19|---|---|---|20| `package.json` + vitest/jest | TypeScript/JS | `npx vitest run` / `npx jest` |21| `pom.xml` / `build.gradle` | Java | `mvn test -q` / `gradle test` |22| `pyproject.toml` / `pytest.ini` | Python | `pytest -x -q` |23| `go.mod` | Go | `go test ./...` |24| `*.csproj` | .NET | `dotnet test` |2526## 2. Run Tests2728Execute the test suite:2930```31// turbo32<test-command>33```3435Capture:36- **Exit code**: 0 = all pass, non-zero = failures37- **Output**: Test names, pass/fail counts, error messages, stack traces3839**Test runner stdout > 2000 tokens is normalized** by the `tool-output-normalize.py` hook (G2) before injection back into context — large failure dumps get summarized envelope metadata + extracted top-k failures rather than raw dump. This protects context budget on noisy suites.4041## 3. Analyze Failures4243If tests fail, for each failure:44451. **Read the failing test** — understand what it asserts462. **Read the error message and stack trace** — identify the actual vs expected473. **Classify the failure**:4849| Classification | Action |50|---|---|51| **Code bug** — test is correct, implementation is wrong | Fix the implementation (Step 4) |52| **Test bug** — test is wrong or outdated | Fix the test (Step 4) |53| **Environment issue** — missing dependency, port conflict, DB down | Report to user (Step 5) |54| **Flaky test** — passes on re-run without changes | Flag for investigation |5556## 4. Fix and Re-Run5758For auto-fixable failures:59601. Apply the appropriate stack-specific role (`Agent(frontend-engineer)`, `Agent(java-engineer)`, `Agent(python-engineer)`, etc.)612. Apply the minimal fix — do not refactor unrelated code623. Re-run the failing test(s) specifically:6364| Stack | Run Single Test |65|---|---|66| Vitest | `npx vitest run <test-file>` |67| Jest | `npx jest <test-file>` |68| pytest | `pytest <test-file>::<test-name> -v` |69| JUnit/Maven | `mvn test -pl <module> -Dtest=<TestClass>#<method>` |70| Go | `go test -run <TestName> ./path/...` |71724. If the fix works, re-run the full suite to check for regressions735. **Max 3 fix attempts per failure** — if still failing after 3 tries, escalate to user7475## 5. Coverage Check (if available)7677Run coverage report:7879| Stack | Command |80|---|---|81| Vitest | `npx vitest run --coverage` |82| Jest | `npx jest --coverage` |83| pytest | `pytest --cov=<package> --cov-report=term-missing` |84| Go | `go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out` |85| JUnit | `mvn jacoco:report` |8687Compare against `test-strategy` skill targets:88- Line coverage ≥ 80% (hard minimum 60%)89- Branch coverage ≥ 75% (hard minimum 50%)90- New code coverage ≥ 90%9192## 6. Summary9394```95## Test Results9697| Metric | Value |98|--------|-------|99| Total tests | X |100| Passed | X |101| Failed | X |102| Skipped | X |103| Duration | Xs |104| Coverage | X% (target: 80%) |105106### Failures Fixed107- [test name] — [what was wrong] — [fix applied]108109### Remaining Failures (needs attention)110- [test name] — [error] — [classification]111112### Coverage Gaps113- [file/module] — [current%] — [uncovered lines]114115**Overall**: ✅ PASS / ❌ FAIL — [action needed]116```117118## Integration119120- **Called by**: `/develop`, `/bugfix`, `/pre-commit`121- **Skills**: `test-strategy` skill122- **Roles**: `Agent(qa-engineer)` (test strategy), stack-specific role (implementation)123- **Hooks**: `tool-output-normalize.py` (G2 normalization for test runner stdout per Step 2)
avav25