Test Smells Reference

Overspecified Tests and Over-Mocking

Symptom: Refactoring breaks many tests even though behaviour is unchanged; arrange sections dominated by expectation setup; tests "know" the call graph.

Fix: Assert end result; collapse internal collaborators into the unit boundary; replace mocks with fakes or spies; move mocks to external side effects only.

Weak Assertions Under High Coverage

Symptom: Coverage numbers look strong, but tests only check existence, status codes, or one shallow field.

Fix: Strengthen the oracle around business-critical outputs, state transitions, invariants, and negative cases; use mutation-oriented thinking to ask what change would survive.

Flaky or Slow Tests

Symptom: Reruns pass; failures cluster around time, concurrency, order dependence, remote services, or shared state.

Fix: Improve isolation; remove shared mutable fixture state; control time and async boundaries; quarantine only temporarily; keep unit suite free of flakiness.

Mystery Guests and Obscure Setup

Symptom: Reader cannot tell from the test alone why the fixture leads to the assertion; large SQL files, global fixtures, or hidden setup determine outcomes.

Fix: Prefer explicit builders, minimal fixtures, and test-local setup that communicates only the facts needed to understand the scenario.

Duplicated or Over-Abstracted Test Logic

Symptom: Each test repeats noisy construction code, or shared helpers become so clever that the scenario disappears.

Fix: Use builders and small helper abstractions, but keep the test readable from top to bottom.

Untestable Design

Symptom: Tests need magic hooks, global state management, or huge object graphs.

Fix: Make dependencies explicit; split business logic from orchestration; introduce ports/adapters; treat the difficulty of testing as design feedback rather than as a signal to buy more mocking tools.