Skip to main content

Tests Should Read Like Explanations

What this concept is​

Good tests explain what a unit of code is supposed to do. Their names, setup, assertions, and structure should make behavior visible without forcing the reader to untangle testing mechanics.

Why it matters here​

If production code is written for readers, test code is too. Dirty tests turn into a maintenance burden and eventually get ignored or deleted. Then the design loses protection.

Concrete example​

Opaque test:

def test_1():
    assert calc(2, 3, True) == 4

Clearer test:

def test_discount_is_capped_at_order_total():
    order_total = 4
    discount = 10

    assert apply_discount(order_total, discount) == 0

The second test teaches a rule, not just a result.

Common confusion / misconception​

Tests do not need to be tiny one-liners to be clean. They need one concept per test, minimal irrelevant setup, and names that explain behavior. Sometimes a little structure makes a test far clearer.

How to use it​

Prefer:

  • descriptive test names
  • one behavioral idea per test
  • helper functions that remove repetitive setup noise
  • assertions that show the intended contract
  • F.I.R.S.T. thinking: fast, independent, repeatable, self-validating, timely

Check yourself​

What makes a test more like documentation by example than like a script of setup steps?

Mini drill or application​

Rewrite one weak test you already have. Change the name, remove noisy setup, and make the assertion state a real rule rather than just a raw value.

Read this only if stuck​