Python Testing

---
name: python-testing
description: Write focused, deterministic, well-documented pytest tests for AI-authored code.
license: MIT
compatibility: claude cursor opencode
metadata:
  version: "1.0.0"
  languages: python
  audience: developers
  workflow: testing
  since: "2025-02-24"
---

## What I do

I help with three pytest workflows:
1. **Write tests** — generate focused, well-documented tests following project conventions
2. **Check coverage** — detect untested lines per file or folder
3. **Bootstrap setup** — install dev dependencies and apply recommended pytest configuration

Supporting files in this skill:
- `assets/pytest.ini.template` — ready-to-copy pytest configuration
- `scripts/analyze_coverage.sh [path]` — coverage analysis helper (whole src or specific folder/module)
  - Run from repo root as: `./.claude/skills/python-testing/scripts/analyze_coverage.sh [path]`
  - Or use repo-root-safe path: `"$(git rev-parse --show-toplevel)/.claude/skills/python-testing/scripts/analyze_coverage.sh" [path]`

## When to use me

Use when you want to:
- Write new tests for a module or feature
- Review and improve existing test quality
- Check coverage for a specific file, folder, or the whole project
- Bootstrap pytest for a new project (deps + config)

## Example usage

"Write tests for the `slugify` function in `src/utils/text.py`"
"Check coverage for `src/services/payment.py`"
"Set up pytest for this project with coverage and async support"

---

## Conventions

### Naming
- Files: `test_<module_or_feature>.py`
- Functions: `test_<unit>__<behavior>__<condition>`
- Mark every AI-generated test with `@pytest.mark.ai`

### Docstring (required on every test)
Three-part format:
```
Purpose: What this test verifies.
Why this matters: Business or technical consequence if it breaks.
Setup summary: What's arranged and what's asserted.
```

### Structure
- AAA pattern: Arrange – Act – Assert
- No conditionals or loops in test body (use parametrization)
- One responsibility per test

### Fixtures
- Centralize in `<domain>_fixtures.py`
- Register via `pytest_plugins = ["tests.fixtures"]` in `conftest.py`
- Return typed objects; modify only what changes per test

### Mocking
- Use `mocker` fixture (pytest-mock)
- Mock at the import boundary of the code under test
- Use `spec=True` for type safety

### Coverage
- Target ≥ 80% for AI-authored tests
- `./.claude/skills/python-testing/scripts/analyze_coverage.sh` — full src coverage
- `./.claude/skills/python-testing/scripts/analyze_coverage.sh src/services` — coverage for a specific folder
- `./.claude/skills/python-testing/scripts/analyze_coverage.sh src/utils/text.py` — coverage for a single file

### Test scope & quality
- Test every public function and method you touched
- Cover happy paths plus negative scenarios, validation failures, and async edge cases
- Keep tests deterministic and isolated (clean up temp data, reset mocks)
- Mock only external dependencies using `pytest-mock`'s `mocker` or hand-rolled fixtures
- Document why each test matters using the required docstring template

### Test cases to include
- Happy path scenarios that reflect realistic inputs
- Edge cases such as empty inputs, boundary values, and timeout paths
- Error handling or exception flows (raise and capture specific exceptions)
- Dependency failures (e.g., network timeouts, missing files) while staying fast
- Concurrency and async behavior when applicable (use `pytest.mark.asyncio` or trio)

## Test quality checklist
- [ ] Tested all public functions and methods touched by the change
- [ ] Covered happy path scenarios plus edge cases and negative flows
- [ ] Added or updated tests for error handling and exception cases
- [ ] Mocked external dependencies appropriately and kept mocks scoped
- [ ] Ensured all tests are deterministic and repeatable
- [ ] Kept tests focused (one assertion per behavior) and avoided loops/conditionals
- [ ] Documented each test with the three-part docstring
- [ ] Verified coverage with `scripts/analyze_coverage.sh` when changes affect multiple modules

### Setup (new project)
1. Install dev dependencies:
   - uv: `uv add --dev pytest pytest-cov pytest-asyncio pytest-mock`
   - pip: `pip install pytest pytest-cov pytest-asyncio pytest-mock`
2. Copy `assets/pytest.ini.template` → `pytest.ini` at the project root
3. Add `tests/` directory with an empty `__init__.py` and `conftest.py`