Unit Tests That Don’t Suck: Patterns for Maintainable Tests

Quickstart

If you want unit tests that don’t suck, start here. These are the highest-leverage habits that reduce flakiness and make tests cheaper to change than production code.

Overview

This post is a practical toolkit for writing maintainable tests—tests that act like documentation, catch regressions, and don’t punish you for improving your code.

Core concepts

Maintainable unit tests come from the same place maintainable code comes from: clean boundaries, explicit dependencies, and a clear contract.

1) What is a “unit”, really?

A unit is the smallest piece of behavior you can test in isolation. That doesn’t always mean “one method”. A unit can be a function, a class, or a small collaboration—so long as the test stays fast and deterministic.

2) Test doubles (stub, fake, mock) in plain language

3) AAA / Given-When-Then: readability is a feature

Tests are read more often than they are written. A consistent structure lets you scan: setup (why this test exists), action (what we do), assertion (what must be true).

4) Seams: where you should mock (and where you shouldn’t)

A seam is a place where you can replace a dependency: a constructor parameter, an interface, a function argument. Tests stay clean when seams are explicit in your design.

5) Coverage: a signal, not a goal

Coverage helps find “untested” areas, but it does not guarantee quality. A high-coverage suite can still be brittle and useless if it asserts internals or misses meaningful scenarios.

Step-by-step

Here’s a repeatable workflow for writing unit tests that stay useful through refactors. The goal is simple: protect behavior with minimal coupling.

Step 1 — Write the contract in one sentence

Before you write code or tests, write the behavior: “Given X, when Y happens, then Z should be true.” If you can’t say it simply, the unit boundary is probably too big (or unclear).

Step 2 — Prefer pure functions (when you can)

Pure functions (no IO, no hidden state) are the easiest units to test. If your logic can be extracted into a pure function, you get fast, deterministic tests almost for free.

Step 3 — Keep test data small and intentional

Most test pain comes from giant fixtures that nobody understands. Use tiny objects that highlight the behavior under test. If you need bigger setups repeatedly, use a builder/factory (but don’t hide meaning behind magic defaults).

Example 1 — A clean unit test with AAA + parameterization (pytest)

This example shows a simple pricing slice. Notice what we don’t do: no mocks, no IO, no randomness. We test behavior and edge cases, and failures are easy to interpret.

# pricing.py
from dataclasses import dataclass
from decimal import Decimal, ROUND_HALF_UP

@dataclass(frozen=True)
class LineItem:
    sku: str
    qty: int
    unit_price: Decimal

def subtotal(items: list[LineItem]) -> Decimal:
    total = sum((i.unit_price * i.qty for i in items), Decimal("0.00"))
    return total.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

def apply_discount(amount: Decimal, percent: int) -> Decimal:
    if percent < 0 or percent > 100:
        raise ValueError("percent must be 0..100")
    discounted = amount * (Decimal("100") - Decimal(percent)) / Decimal("100")
    return discounted.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)


# test_pricing.py (pytest)
import pytest
from decimal import Decimal
from pricing import LineItem, subtotal, apply_discount

@pytest.mark.parametrize(
    "items, expected",
    [
        ([LineItem("A", 2, Decimal("9.99"))], Decimal("19.98")),
        ([LineItem("A", 1, Decimal("9.99")), LineItem("B", 3, Decimal("1.00"))], Decimal("12.99")),
        ([], Decimal("0.00")),
    ],
)
def test_subtotal_sums_line_items(items, expected):
    # Arrange (items) is part of parameterization
    # Act
    result = subtotal(items)
    # Assert
    assert result == expected

def test_apply_discount_rounds_to_cents():
    assert apply_discount(Decimal("10.00"), 15) == Decimal("8.50")

@pytest.mark.parametrize("percent", [-1, 101])
def test_apply_discount_rejects_invalid_percent(percent):
    with pytest.raises(ValueError):
        apply_discount(Decimal("10.00"), percent)

Step 4 — When dependencies exist, inject seams

Many units aren’t pure: they depend on time, IDs, external services, or persistence. The maintainable move is to make those dependencies explicit and replaceable. Avoid patching globals if you can—patching hides the seam and tends to spread brittle tests across the suite.

Example 2 — Deterministic unit tests with fakes (Jest)

Instead of mocking Date globally, we inject a clock. Instead of mocking random everywhere, we inject a random source. This keeps the unit test stable and makes the production code easier to reason about.

// src/tokenService.js
export function createTokenService({ clock, random }) {
  return {
    issue(userId) {
      const ts = clock.now().toISOString();
      const nonce = random.hex(8);
      return `${userId}.${ts}.${nonce}`;
    },
  };
}

// test/tokenService.test.js
import { createTokenService } from "../src/tokenService.js";

test("issue() is deterministic with fakes", () => {
  const fixed = new Date("2026-01-01T00:00:00.000Z");

  const svc = createTokenService({
    clock: { now: () => fixed },
    random: { hex: () => "deadbeef" },
  });

  expect(svc.issue("u123")).toBe("u123.2026-01-01T00:00:00.000Z.deadbeef");
});

Step 5 — Assert the minimum that proves the behavior

The goal isn’t “lots of assertions.” The goal is “the right assertions.” A maintainable test proves one behavior and stays quiet otherwise.

Step 6 — Turn bugs into regression tests (the best tests)

The highest ROI tests come from real failures. When you fix a bug, write a test that fails on the old behavior and passes on the fix. Keep it as small as possible, and name it after the scenario (not the ticket number).

Step 7 — Keep the suite fast with CI guardrails

Even great tests become painful if they’re slow or inconsistent in CI. Add a simple pipeline that runs unit tests on every push, fails fast, and keeps feedback tight.

name: tests
on:
  push:
  pull_request:

jobs:
  unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: "pip"
      - run: pip install -r requirements.txt
      - run: pytest -q --maxfail=1 --disable-warnings --junitxml=test-results/junit.xml
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: junit
          path: test-results/junit.xml

Common mistakes

Most test pain is predictable. These are the patterns behind “we stopped trusting the suite,” and the fixes that usually help immediately.

FAQ

How many unit tests should I write?

Write enough unit tests to protect the behaviors you care about: business rules, edge cases, and regressions you’ve actually hit. Aim for high-signal coverage, not maximum test count. If tests feel expensive to maintain, reduce coupling and simplify the unit boundary.

Should I do TDD to get maintainable unit tests?

TDD can help you design seams and keep functions small, but it’s not required. What matters most is the discipline: write tests that specify behavior, keep them deterministic, and refactor tests when they become noisy.

Mock vs stub vs fake — which one should I use?

Prefer fakes for stable tests (e.g., in-memory repositories), use stubs for simple canned responses, and reserve mocks for verifying interactions at the boundary (like “an email was sent”). If you’re mocking deep internal collaborators, you’re probably over-coupling tests to implementation.

How do I test time-dependent code without brittle patches?

Don’t read time directly inside the unit. Inject a clock (or pass now as an argument) and use a fixed time in tests. This makes tests deterministic and avoids global patching that leaks between test cases.

What should be unit tested vs integration tested?

Unit tests are best for domain logic and behavior that can run without external systems. Use integration tests for the correctness of boundaries: database queries, HTTP wiring, serialization, and framework integration. Keep integration tests fewer, slower, and more realistic.

My tests are readable but still break a lot. Why?

The most common reason is asserting implementation details: internal method calls, exact structures, or tightly coupled mocks. Move assertions up to observable behavior, replace deep mocks with fakes, and keep each test focused on one scenario.

Cheatsheet

A scan-fast checklist for writing unit tests that stay maintainable.

Wrap-up

Maintainable unit tests aren’t about more tests—they’re about better contracts. When you test behavior, keep dependencies explicit, and make tests deterministic, your suite becomes a safety net instead of a chore.

Related posts

• E2E Testing Without Flakiness: A Practical Playbook
• Mobile Testing Strategy: Unit, UI, Snapshot, and E2E
• Python in 60 Minutes: From Zero to Useful
• Top 25 Python Errors (And the 1-Line Fixes)
• Python Dataclasses: Cleaner Models With Less Boilerplate
• Make Python Faster: 12 Micro-Optimizations That Matter