Comprehensive pytest testing and debugging framework. Use when running tests, debugging failures, fixing broken tests, or investigating test errors. Includes systematic investigation workflow with external AI tool consultation and verification strategies.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
reference.mdThe Skill(foundry:run-tests) skill provides systematic pytest testing with a 5-phase investigation workflow. It runs tests, investigates failures, consults external AI tools when available, and guides fix implementation.
Key capabilities:
This skill uses the Foundry MCP server (foundry-mcp). Tools use the router+action pattern: mcp__plugin_foundry_foundry-mcp__<router> with action="<action>".
Test execution:
mcp__plugin_foundry_foundry-mcp__test action="run" - Full test run with optionsmcp__plugin_foundry_foundry-mcp__test action="run-quick" - Quick run (fail-fast, skip slow)mcp__plugin_foundry_foundry-mcp__test action="run-unit" - Unit tests onlymcp__plugin_foundry_foundry-mcp__test action="presets" - List available presetsmcp__plugin_foundry_foundry-mcp__test action="discover" - Discover tests without runningAI consultation:
mcp__plugin_foundry_foundry-mcp__provider action="list" - Check available AI toolsmcp__plugin_foundry_foundry-mcp__provider action="execute" - Consult AI for debuggingCode documentation (optional):
mcp__plugin_foundry_foundry-mcp__code action="find-function" - Find function definitionsmcp__plugin_foundry_foundry-mcp__code action="trace-calls" - Trace call graphsRun Tests
|
v
Pass? --Yes--> Done
|
No
v
Investigate (form hypothesis)
|
v
Gather Context (optional: use code docs)
|
v
Consult External Tools (mandatory if available)
|
v
Fix & Verify
Decision rules:
Quick run (stop on first failure):
mcp__plugin_foundry_foundry-mcp__test action="run-quick"
Full suite with verbose output:
mcp__plugin_foundry_foundry-mcp__test action="run" verbose=true
Specific test:
mcp__plugin_foundry_foundry-mcp__test action="run" target="tests/test_module.py::test_function"
Categorize the failure:
| Category | Description |
|---|---|
| Assertion | Expected vs actual mismatch |
| Exception | Runtime errors (AttributeError, KeyError) |
| Import | Missing dependencies or module issues |
| Fixture | Fixture or configuration issues |
| Timeout | Performance or hanging issues |
| Flaky | Non-deterministic failures |
Extract key information:
Form hypothesis: What's causing the failure?
If code documentation exists:
mcp__plugin_foundry_foundry-mcp__code action="doc-stats"
mcp__plugin_foundry_foundry-mcp__code action="find-function" symbol="function_name"
mcp__plugin_foundry_foundry-mcp__code action="trace-calls" symbol="function_name"
For complex failures or unfamiliar code, use Claude Code's built-in subagents:
| Scenario | Subagent | Thoroughness |
|---|---|---|
| Find related test files | Explore | quick |
| Understand module dependencies | Explore | medium |
| Multi-file state/fixture investigation | Explore | very thorough |
| Complex debugging across packages | general-purpose | N/A |
Example: Investigating shared state (flaky tests)
Use the Explore agent (very thorough) to find:
- All fixtures in conftest.py files
- Global state or module-level variables
- Files importing the failing module
- Test files that modify shared resources
Benefits:
For detailed investigation patterns with subagents, see
reference.md#subagent-investigation-patterns
Check availability:
mcp__plugin_foundry_foundry-mcp__provider action="list"
Decision:
Consultation:
mcp__plugin_foundry_foundry-mcp__provider action="execute" provider_id="gemini" prompt="..."
For tool selection guidance by failure type, see
reference.md#tool-selection
mcp__plugin_foundry_foundry-mcp__test action="run" target="tests/test_module.py::test_function"mcp__plugin_foundry_foundry-mcp__test action="run"| Preset | Behavior |
|---|---|
| quick | Stop on first failure, exclude slow tests |
| unit | Unit tests only |
| integration | Integration tests only |
| full | Complete suite with verbose output |
Always use foreground execution with timeout:
Bash(command="pytest src/", timeout=300000) # Wait up to 5 minutes
Never poll background processes - this creates spam in the conversation.
For detailed troubleshooting, failure categories, and AI tool selection: