Testing Guidelines
Follow these principles when writing tests.
Core Principles
1. Mock External Services, Use Real Fixtures
ALWAYS mock third-party network services. ALWAYS use fixtures based on real-world data.
- Fixtures must be scrubbed of PII (use dummy data like
foo@example.com, user-123)
- Capture real API responses, then sanitize them
- Never make actual network calls in tests
2. Prefer Integration Tests Over Unit Tests
Focus on end-to-end style tests that validate inputs and outputs, not implementation details.
- Test the public interface, not internal methods
- Unit tests are valuable for edge cases in pure functions, but integration tests are the priority
- If refactoring breaks tests but behavior is unchanged, the tests were too coupled to implementation
3. Minimize Edge Case Testing
Don't test every variant of a problem.
- Cover the common path thoroughly
- Skip exhaustive input permutations
- Skip unlikely edge cases that add maintenance burden without value
- One representative test per category of input is usually sufficient
4. Always Add Regression Tests for Bugs
When a bug is identified, ALWAYS add a test that would have caught it.
- The test should fail before the fix and pass after
- Name it descriptively to document the bug
- This prevents the same bug from recurring
Note: Regression tests are for unintentional broken behavior (bugs), not intentional changes. Intentional feature removals, deprecations, or breaking changes do NOT need regression tests—these are design decisions, not defects.
5. Cover Every User Entry Point
ALWAYS have at least one basic test for each customer/user entry point.
- CLI commands, API endpoints, public/exported functions
- Test the common/happy path first
- This proves the entry point works at all
Note: "Entry point" means the public interface—exported functions, CLI commands, API routes. Internal/private functions are NOT entry points, even if they handle user-facing flags or options. Test entry points; internal functions get coverage through those tests.
6. Tests Validate Before Manual QA
Tests are how we validate ANY functionality works before manual testing.
- Write tests first or alongside code, not as an afterthought
- If you can't test it, reconsider the design
- Passing tests should give confidence to ship
Technical Guidelines
File Organization
- Co-locate tests with source files when possible
- Use the project's standard test file naming convention
Test Isolation
Every test must:
- Run independently without affecting other tests
- Use temporary directories for file operations
- Clean up resources after completion
Pure Function Tests
For pure functions without side effects, no special setup is needed—just test inputs and outputs directly.
Checklist Before Submitting
