Menu
ALWAYS invoke this skill when writing or fixing tests for Python.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
ALWAYS invoke this skill when auditing ADRs for Python or after writing an ADR. NEVER implement from an unaudited ADR.
ALWAYS invoke this skill when auditing code for Python or after writing code. NEVER modify a spec to match code without auditing the code first.
ALWAYS invoke this skill when auditing tests for Python or after writing tests. NEVER use auditing-python for test code.
Python ADR conventions enforced across architect and auditor skills. Loaded by other skills, not invoked directly.
ALWAYS invoke this skill when auditing PDRs or after writing a PDR. NEVER audit PDRs without this skill.
ALWAYS invoke this skill when auditing test evidence quality, after writing tests for a spec node, or before closing an outcome.
| name | testing-python |
| description | ALWAYS invoke this skill when writing or fixing tests for Python. |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
This skill WRITES tests. It does not just design or plan.
<mode_detection> Determine which mode you're in:
WRITE mode - Tests don't exist yet or you're starting fresh
ls {node_path}/tests/*.py returns nothing or minimal filesFIX mode - Tests exist but were rejected by reviewer
/auditing-python-tests output shows REJECT with specific issuesAlways check which mode before proceeding. </mode_detection>
<quick_start>
Input: Node spec path (e.g., spx/21-infra.enabler/43-parser.outcome/)
Output: Test files written to {node}/tests/ directory
Workflow:
Check mode → WRITE or FIX → Execute → Verify → Report
</quick_start>
<write_mode_workflow>
Read the node spec and related files:
# Read node spec
cat {node_path}/{slug}.outcome.md
# Read parent node for context (if nested)
cat {parent_path}/{slug}.enabler.md
# Check for ADRs/PDRs that constrain testing approach
ls {node_path}/../*.adr.md {node_path}/../*.pdr.md 2>/dev/null
Extract from the spec:
Note on Analysis sections: The Analysis section documents what the spec author examined. It provides context but is not binding — implementation may diverge as understanding deepens. Use it as a starting point, not a contract.
For each assertion, apply the /testing methodology:
| Evidence Type | Minimum Level |
|---|---|
| Pure computation/algorithm | 1 |
| File I/O with temp dirs | 1 |
| Standard dev tools (git, curl) | 1 |
| Project-specific binary | 2 |
| Database, Docker | 2 |
| Real credentials, external APIs | 3 |
Create test files following /standardizing-python-testing:
Mandatory elements:
-> None return type on every test function@given).unit.py, .integration.py, .e2e.py)uv run --extra dev pytest {node_path}/tests/ -v
Tests should FAIL with ImportError or AssertionError (implementation doesn't exist yet).
If the implementation module doesn't exist yet, tests fail on import — breaking the quality gate. Add the node to spx/EXCLUDE and run the project's sync command:
# Add node path to spx/EXCLUDE (paths relative to spx/)
echo "76-risc-v.outcome" >> spx/EXCLUDE
# Sync to pyproject.toml
just sync-exclude
This excludes the node's tests from pytest, mypy, and pyright until the implementation exists. Ruff still checks style. See the spec-tree /understanding skill's references/excluded-nodes.md for the full convention.
Remove the entry from spx/EXCLUDE when implementation begins.
</write_mode_workflow>
<fix_mode_workflow>
Find the most recent /auditing-python-tests output. Look for:
For each rejection reason:
| Rejection Category | Fix Action |
|---|---|
Missing -> None | Add return type to test functions |
| Evidentiary gap | Rewrite test to actually verify the assertion |
| Mocking detected | Replace with dependency injection |
| Missing property tests | Add @given tests for parsers/serializers |
| Silent skip | Change skipif to pytest.fail() for required deps |
| Magic values | Extract to named constants |
| Wrong filename suffix | Use .unit.py, .integration.py, or .e2e.py |
# Run tests again
uv run --extra dev pytest {node_path}/tests/ -v
# Check types
uv run --extra dev mypy {node_path}/tests/
# Check linting
uv run --extra dev ruff check {node_path}/tests/
## Tests Fixed
### Issues Addressed
| Issue | Location | Fix Applied |
| --------------- | -------------- | ------------------------------------ |
| Missing -> None | test_foo.py:15 | Added return type |
| Magic value | test_foo.py:23 | Extracted to EXPECTED_VALUE constant |
### Verification
Tests run and fail for expected reasons (RED phase complete).
</fix_mode_workflow>
<test_writing_checklist>
Before declaring tests complete:
/testing Stage 2).unit.py, .integration.py, .e2e.py)-> None return type@given)</test_writing_checklist>
<patterns_reference>
See /standardizing-python-testing for:
</patterns_reference>
<output_format>
WRITE mode output:
## Tests Written
### Node: {node_path}
### Test Files Created
| File | Level | Outcomes Covered |
| ------------------------ | ----- | ---------------- |
| `tests/test_foo.unit.py` | 1 | Outcome 1, 2 |
### Test Run (RED Phase)
Tests fail as expected. Ready for review.
FIX mode output:
## Tests Fixed
### Issues Addressed
| Issue | Location | Fix Applied |
| ------- | ----------- | ----------- |
| {issue} | {file:line} | {fix} |
### Verification
Tests pass checklist. Ready for re-review.
</output_format>
<success_criteria>
Task is complete when:
{node}/tests/ directory/standardizing-python-testing standards</success_criteria>