Python Mock Isolation Design

Use this skill when replacing a dependency in a Python test changes what the test proves. Mocks are useful at slow, nondeterministic, or external boundaries; they become harmful when they replace the behavior the test is supposed to validate.

Source Traceability

Primary source: Harry Percival, Test-Driven Development with Python, 3rd ed. Guidance is transformed and paraphrased from chapters 20, 21, 27, and Appendix A, especially manual monkeypatching, unittest.mock.patch, mock coupling, call argument inspection, test isolation, and the architectural route out of mock-heavy suites.

Workflow

1. Name the boundary.

   • External service, email, clock, filesystem, network, framework adapter, or expensive side effect.
   • If the dependency is local domain logic, prefer real code.

2. Choose the replacement.

   • Use a fake when state and behavior are simple and meaningful.
   • Use patch when replacing a collaborator looked up by the module under test.
   • Use monkeypatching sparingly and restore state automatically.
   • Use autospec/spec when interface drift matters.