Python Testing (Pytest)

Guides agents through executing, isolating, and debugging Python tests with pytest. Enforces clean fixture usage (conftest.py), parametrization, and mocking.

1. Purpose

Run and debug Python automated tests. A "Pytest Fixture" provides reproducible test dependencies. A "Parametrized Test" runs one test over multiple input/output pairs.

2. When to Use

Use this skill when:

• Running Python test suites with pytest.
• Filtering test runs by keyword (pytest -k "test_pattern").
• Writing fixtures or mocking external APIs with unittest.mock.

3. When Not to Use

• Do not use for TypeScript tests; use ts-testing.
• Do not use for linting; use py-lint-and-typecheck.

4. Required Inputs

• test_path: Path to test file or directory (e.g. tests/test_orders.py).
• keyword_filter: Optional test function name or substring (-k).

5. Missing-Input Behavior

1. If test_path is missing: run pytest in current directory or search tests/ directory.
2. Never modify assert actual == expected values to force a broken test to pass.

6. Procedure

Follow these numbered actions:

1. Action 1: Run Targeted Test
   • Execute: pytest <test_path> -k "<keyword>" -v
2. Action 2: Inspect Failures & Tracebacks
   • Read failure message and line numbers.
3. Action 3: Trace Root Cause to Implementation
   • Inspect the code file being tested.
4. Action 4: Apply Fix & Re-run
   • Confirm targeted test passes.
5. Action 5: Run Full Test Suite
   • Run pytest to confirm zero regressions.

7. Decision Rules

• If test fails due to missing module: verify virtualenv or pip install -e . installation.
• If test outputs stdout needed for debugging: add -s flag (pytest -s ...).

8. Output Format

Emit the report using this template:

### Pytest Execution Report: [Test File]

- **Command**: `pytest [path] -k "[filter]" -v`
- **Status**: [PASSED | FAILED]
- **Duration**: [e.g. 0.08s]

#### Summary
- Tests Run: [Count] | Passed: [Count] | Failed: [Count]

#### Resolution
- [Root cause and fix description]

9. Verification Checklist

• Targeted pytest command executed with clean exit code 0.
• No test assertions corrupted.
• Full suite passes without regression.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Test requires cloud services or proprietary database credentials.

12. Examples

Example 1: Successful Execution

Input:

File: tests/test_calc.py
Filter: test_divide

Output:

### Pytest Execution Report: tests/test_calc.py

- **Command**: `pytest tests/test_calc.py -k "test_divide" -v`
- **Status**: PASSED
- **Duration**: 0.04s

#### Summary
- Tests Run: 2 | Passed: 2 | Failed: 0

#### Resolution
- Fixed ZeroDivisionError by adding check in `calc.py`.

Example 2: Ambiguous or Missing Input

Input:

Run python tests.

Output:

### Pytest Execution Report: Halted - Ambiguous Target

- **Status**: Halted

Please specify the test file or function name you want to run.

Example 3: Expected Final Output

Output:

### Pytest Execution Report: tests/test_api.py

- **Command**: `pytest tests/test_api.py -v`
- **Status**: PASSED
- **Duration**: 0.22s

#### Summary
- Tests Run: 6 | Passed: 6 | Failed: 0