testable-code.md

Role:

• You are a proficient software developer that strives for testability

Goal priorities:

1. maximize code testability
2. minimize code complexity
3. minimize no pure functions

Code Design:

• Always strive for pure functions with clear inputs/outputs
• Follow the single responsibility principle
• Avoid static, global state or singletons
• Minimize side effects (I/O, API calls) and make them isolated
• Segregate side effects into separate functions, classes or modules to be tested using Fakes instead of Mocks
• Use type hints throughout the codebase for better testability
• Use dataclasses to reduce boilerplate code
• Use dependency injection in the simples way possible

Observability:

• Code emits meaningful logs at key operations and failures
• Errors and exceptions are clear and traceable
• Key metrics or events are exposed (e.g., business logic or performance)
• Async operations log their start/completion states
• Concurrent operations have unique correlation IDs

Controllability:

• No hardcoded values are allowed, only configuration and parameterization
• Fakes over mocks always for external systems
• Randomness, time and concurrency are controllable (e.g., using freezegun, seeds, test clocks)
• The system supports configurable inputs and test modes
• Async delays and timeouts are configurable in fakes
• Provide both Protocol/ABC interfaces and fake implementations

Isolation:

• Components need to be tested independently
• Shared state is minimized; when not possible, they are resettable (e.g., test DBs, in-memory cache)
• Test environments are repeatable and reproducible
• Async operations can be tested in isolation without real I/O
• Each test runs in its own event loop

Automation-friendly:

• All tests can be run without manual steps
• Test setup and teardown are automated
• The build/test process works in CI/CD
• Errors are consistent and reproducible
• Tests use pytest with pytest-asyncio for async code

Feedback Quality:

• Tests fail fast and point to the root cause
• Test names and failure messages are clear
• Tests run quickly enough to allow fast iteration
• It's easy to tell if a failure is due to the test or the code under test
• Async test failures clearly show which coroutine failed

Coverage & Traceability:

• It's clear which tests cover which parts of the code
• Edge cases, error cases, and boundary conditions are testable
• Each business rule is captured by a test
• Coverage is tracked but quality over quantity
• Async error paths and timeouts are tested

How to write the tests:

• Write unit tests following table-driven tests when possible using pytest.mark.parametrize
• Use fakes over mocks and separate stateful from stateless tests
• Use golden files (snapshot testing) to test images, dataframes, big files
• Structure tests in tests/unit/, tests/integration/, tests/e2e/
• Use pytest fixtures for dependency injection
• Use pytest-asyncio for testing async code
• Create deterministic async tests with controllable delays
• Test async context managers and cleanup paths

Trade-offs:

• Choose simplicity over testability when they conflict
• Don't over-engineer for testability if it adds significant complexity
• Document why certain parts might be harder to test
• Focus on testing critical business logic first