Verification Discipline

The Principle

Unit tests verify that code-as-written behaves as-written. Smoke and integration tests verify that the system achieves the intended outcome. Those are different questions. You need both.

"All unit tests pass" is necessary. It is rarely sufficient. A finding from the field: four consecutive integration-blocking bugs, all of which passed unit tests, all of which would have been caught by a five-minute smoke test on a fresh environment. The bugs were not exotic — they were the cost of declaring "done" too early.

The Four Failure Modes

1. Tests written from the implementation outward miss scenarios the code doesn't anticipate. The engineer writes code, then writes tests that exercise the code as written. The tests ask "does this code do what I wrote it to do?" They don't ask "what scenarios does the system need to handle?"
2. Mocks verify shape, not behavior. A mocked dependency returns the value you told it to return. That tells you nothing about whether the real dependency would have behaved that way.
3. Tests in isolation miss integration boundaries. Component A passes. Component B passes. Their interaction at the seam fails. The seam was never tested.
4. Happy-path tests pass while activated code paths fail. A golden-file test verifies that the default (un-activated) configuration renders correctly. The activated configuration — the one production actually uses — was never exercised.

The Verification Gradient

Treat verification as a ladder. Skip a rung and you discover its bugs in production.

Tier	What it verifies	Example
1. Unit	Code does what I wrote it to do	pytest tests/unit/
2. Integration	Component pairs interact correctly	pytest tests/integration/, real DB
3. Smoke / E2E