module-test-isolation

Isolate module-level mutable state in pytest tests to prevent cross-test pollution.

Updated Mar 30, 2026
One-click install
npx skills add https://github.com/ZaxbyHub/ragappv3 --skill module-test-isolation-zaxbyhub
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: module-test-isolation
Source: https://github.com/ZaxbyHub/ragappv3/tree/main/.opencode/skills/module-test-isolation
Command: npx skills add https://github.com/ZaxbyHub/ragappv3 --skill module-test-isolation-zaxbyhub

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Tests that pass in isolation but fail in combined pytest sessions are usually victims of leaked module-level mutable state — global registries, singletons, class attributes, and dependency override dicts that one test mutates and another inherits. ## Core Features & Use Cases - Pattern Catalog: Documents common pollution sources such as module-level dicts (connection pool caches, active-user caches), rate-limiter singletons, and FastAPI dependency_overrides. - Mitigation Patterns: Provides a reset-hook conftest fixture and a per-test pool pattern with try/finally teardown to guarantee state cleanup. - Diagnostic Commands: Supplies grep commands to locate module-level mutable state, singletons, and class attributes across a Python codebase. - Use Case: A test creates a SQLite pool at tmp_path/test.db and the next test at the same path reuses a stale pool with different settings; apply the reset fixture to clear _pool_cache between tests. ## Quick Start Ask the assistant to review a failing pytest test for module-level state leaks and add a reset fixture to conftest.py.

Frequently Asked Questions about module-test-isolation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my pytest test pass alone but fail with other tests?▼

The test likely depends on or leaks module-level mutable state such as a global dict, singleton, or class attribute. Run it in isolation and then combined with likely polluters; a failure only in combined mode confirms a test-isolation defect.

How do I reset global state between pytest tests?▼

Add an autouse fixture in conftest.py that yields, then clears shared caches and closes pools in teardown. For example, clear _pool_cache and _ACTIVE_USER_CACHE after every test so no state leaks into the next one.

How do I find module-level mutable state in a Python codebase?▼

Use grep to find module-level dict assignments, singleton instantiations, and class attributes. The skill provides grep patterns targeting dict literals, capitalized constructor calls at module scope, and class definitions.

Do FastAPI dependency_overrides leak between tests?▼

Yes, dependency_overrides is a global dict on the FastAPI app, so overrides persist across tests unless cleared. Wrap overrides in try/finally and call app.dependency_overrides.clear() in teardown.

What are common test isolation anti-patterns in Python?▼

Anti-patterns include global dicts that grow without teardown, singletons tracking state across tests, class attributes set by one test and read by another, and module-level imports that capture patched objects for all tests.