| name | run-tests |
| description | Run project test suites, interpret failures, and iterate until green. |
| trigger | User says "run tests", "test this", "check if tests pass", "fix failing tests", or requests test verification |
| route | run-tests |
| output-contract | Final test count and pass/fail status; failure diagnosis with file paths; lint results |
Running Tests
Discover the test command
- Check
AGENTS.md or project config for a configured test command.
- Common patterns by ecosystem:
- Python:
uv run pytest tests/ -x -q or python -m pytest
- Node:
npm test or npx jest
- Rust:
cargo test
- Go:
go test ./...
Execution workflow
result = await self.shell.run("uv run pytest tests/ -x -q", timeout=120)
print(result.stdout)
print(result.stderr)
print(f"exit: {result.returncode}")
On failure
- Read the error output carefully — identify the failing test and assertion.
- Use
await self.shell.read(path) to inspect the failing test file.
- Inspect the implementation file that the test exercises.
- Fix the root cause (not the test, unless the test is wrong).
- Re-run only the failing test for fast iteration:
result = await self.shell.run("uv run pytest tests/test_foo.py::test_bar -x", timeout=60)
- Once the targeted test passes, run the full suite to catch regressions.
Rules
- Never delete or skip tests to make the suite pass.
- Never modify test assertions to match broken behaviour.
- If a test is genuinely wrong, explain why before changing it.
- Always run lint (
uv run ruff check src/) alongside tests.
- Report the final test count and status in your evidence.
