Jartan-LLC Testing Philosophy
Integration Tests Verify Behavior, Not Internals
Integration tests must verify observable behavior through endpoints, not implementation details.
Good integration tests:
- Drive endpoints with an HTTP client
- Assert status codes and response bodies
- Verify side effects (emails sent, database rows created, audit entries logged)
- Test cross-cutting concerns (middleware, auth, rate limiting)
Bad integration tests:
- Calling internal service functions for behavior already observable via HTTP
- Using DB queries as the primary assertion surface (DB is for post-assertion verification)
- Testing internal query functions or utility functions -- those belong in unit tests
- Duplicating coverage already exercised by another test
Prefer Fixture Composition
If a test starts with boilerplate setup (register a user, log in, configure a setting), that belongs in a fixture. Test bodies should stay focused on what they're actually testing.
Build fixture stacks: user -> logged_in_user -> admin_user. Each level adds one concern. Tests request the level they need.
Canary Markers for Library Internals
When code depends on a library's private or poorly-documented internals, add a canary test that asserts the internal's shape directly -- don't rewrite production code to avoid the dependency when doing so would cost real accuracy or capability.
The canary turns an upstream rename or shape change into a loud test failure instead of a silent runtime bug.
Canary practices:
- Assert the specific attribute/method and the shape of its return value -- not just "no exception raised"
- Name the test so the failure message makes the breakage obvious (e.g.,
test_library_rate_limit_contract), since it'll likely be read by whoever just bumped a dep - Place it close to the module that uses the internal