pytest-code-review — Claude Code skill: what it does, how to install
pytest-code-review reviews pytest test files for async patterns, fixture scopes, parametrization, and mock targets. Catches unawaited coroutines and broken patch paths before CI runs.
Apache-2.0 239 installs ★ 89 updated 2026-09-15
npx skills add existential-birds/beagle --skill pytest-code-review -a claude-codeWhat pytest-code-review does
This skill directs the AI agent through a five-step review process for test_*.py and conftest.py files. It forces the model to register scoped files, check async patterns, and audit fixtures before issuing any findings. Feedback must cite specific line numbers or test node IDs instead of restating generic rules. Generic complaints are blocked.
The rules target typical pitfalls in Python test suites: substituting synchronous Mock where AsyncMock is needed, unawaited coroutines, and missing finally cleanup in yield fixtures. The checklist also flags copy-pasted test cases that belong in @pytest.mark.parametrize. For mocks, the agent insists on patching symbols at their call site rather than where they were initially defined.
Mocks targeting the wrong import path will trigger explicit gate violations.
What it helps with
- detect unawaited coroutines and incorrect
AsyncMockusage in tests - verify resource cleanup in
finallyblocks for yield fixtures - reduce duplicated assertions using
@pytest.mark.parametrize - catch
patch()targets applied to definition sites instead of call sites
Example prompts for the agent
- Review
tests/test_auth.pyand check for invalidpatch()call site paths - Audit
tests/test_billing.pyandconftest.pyagainst the pytest checklist - Check
tests/test_api.pyfor unawaited coroutines in async test functions
How to install pytest-code-review
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pytest-code-review -a claude-code2Manually: put the files in place
~/.claude/skills/pytest-code-review/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pytest-code-review/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pytest-code-review -a codex2Manually: put the files in place
.agents/skills/pytest-code-review/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pytest-code-review -a cursor2Manually: put the files in place
.cursor/skills/pytest-code-review/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install existential-birds/beagle plugins/beagle-python/skills/pytest-code-review2Manually: put the files in place
.github/skills/pytest-code-review/SKILL.md1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pytest-code-review -a gemini-cli2Platform CLI
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-python/skills/pytest-code-reviewManually: put the files in place
.devin/skills/pytest-code-review/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pytest-code-review -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pytest-code-review
How do I install pytest-code-review in Claude Code?
Run npx skills add existential-birds/beagle --skill pytest-code-review -a claude-code. The skill file is placed in ~/.claude/skills/pytest-code-review/SKILL.md.
What does pytest-code-review do?
It audits pytest suites against five sequential review gates, checking async coroutines, fixture scopes, yield cleanup, and import paths for patch().
How does the skill verify mocks and patches?
It requires mocks to track calls with methods like assert_called_once_with and verifies that patch() targets where a symbol is consumed rather than where it is declared.
Source text
SKILL.md · Apache-2.0
--- name: pytest-code-review description: Reviews pytest test code for async patterns, fixtures, parametrize, and mocking. Use when reviewing test_*.py files, checking async test functions, fixture usage, or mock patterns. --- # Pytest Code Review ## Quick Reference | Issue Type | Reference | |------------|-----------| | async def test_*, AsyncMock, await patterns | [references/async-testing.md](references/async-testing.md) | | conftest.py, factory fixtures, scope, cleanup | [references/fixtures.md](references/fixtures.md) | | @pytest.mark.parametrize, DRY patterns | [references/parametrize.md](references/parametrize.md) | | AsyncMock tracking, patch patterns, when to mock | [references/mocking.md](references/mocking.md) | ## Review gates Work in order. Do not assert pytest-specific problems until each applicable gate passes. 1. **Scoped files** — **Pass when:** You list every `test_*.py` and any `conftest.py` you will cite; no findings for files outside that list. 2. **Async vs sync** — **Pass when:** Per scoped file, you note whether it uses `async def test_*` / `await`; if yes, open [references/async-testing.md](references/async-testing.md) before criticizing async usage. 3. **Fixtures** — **Pass when:** If shared setup matters, you name the `conftest.py` path(s) or state none; for yield fixtures, confirm cleanup exists before claiming resource leaks. 4. **patch / mocks** — **Pass when:** For any `patch` or mock critique, you give the import path where the symbol is **used** (call site), or mark N/A; open [references/mocking.md](references/mocking.md) when mocking is central to the review. 5. **Findings** — **Pass when:** Each finding includes a file path and line(s) or test node id, not a generic rule restatement. ## Review Checklist - [ ] Test functions are `async def test_*` for async code under test - [ ] AsyncMock used for async dependencies, not Mock - [ ] All async mocks and coroutines are awaited - [ ] Fixtures in conftest.py for shared setup - [ ] Fixture scope appropriate (function, class, module, session) - [ ] Yield fixtures have proper cleanup in finally block - [ ] @pytest.mark.parametrize for similar test cases - [ ] No duplicated test logic across multiple test functions - [ ] Mocks track calls properly (assert_called_once_with) - [ ] patch() targets correct location (where used, not defined) - [ ] No mocking of internals that should be tested - [ ] Test isolation (no shared mutable state between tests) ## When to Load References - Reviewing async test functions → async-testing.md - Reviewing fixtures or conftest.py → fixtures.md - Reviewing similar test cases → parametrize.md - Reviewing mocks and patches → mocking.md ## Review Questions 1. Are all async functions tested with async def test_*? 2. Are fixtures properly scoped with appropriate cleanup? 3. Can similar test cases be parametrized to reduce duplication? 4. Are mocks tracking calls and used at the right locations?
© existential-birds · Apache-2.0 · existential-birds/beagle