python-fastapi-test-conventionslisted

# Testing Guidelines Test pyramid, conventions, and rules for the backend codebase. --- ## Test Pyramid | Layer | What to test | DB needed? | Mock what? | Volume | |--------------|----------------------------------|----------------|---------------|-----------------------| | Repository | Queries return correct results | Yes (test DB) | Nothing | Per query method | | Service | Business logic, orchestration | No | Repositories | Most tests here | | Integration | Route → Service → DB wiring | Yes (test DB) | Nothing | Happy path only | | Domain | Business rules, invariants | No | Nothing | Only when entities contain logic | --- ### Repository tests - Use a real test database (not mocks) - Test each query method: found, not found, edge cases - Verify constraints (unique, FK, nullable) - **Repositories return `None` for not-found queries** — use `scalar_one_or_none()`. Tests assert `None`, not `pytest.raises` - **Not-found tests must populate the table first** — create a record via factory before asserting `None` for a different query. Testing against an empty table proves nothing — of course it returns `None` when there's no data. The real test is: can this query correctly return `None` when data exists but doesn't match the filter? ```python # Bad — empty table, trivially passes def test_get_by_id_returns_none_when_not_