Why test, and your first pytest

1 · Why test — and a first assertion essential

Without tests every change is a gamble. With them, one command tells you if you broke anything. At heart a test is an assert.

Here's the moment every developer has lived. You fix a small bug on a Friday afternoon — one line, obviously safe. You ship it. On Monday a colleague messages: the checkout page is throwing errors for anyone with a discount code. Your one-line fix quietly changed a shared helper, and nothing warned you, because the only thing checking that helper was you clicking through the app — and you didn't click the discount path. That gap between "I changed something small" and "I have no idea what else I touched" is exactly the fear that tests exist to kill.

Think of tests as a smoke alarm for your code. A smoke alarm doesn't stop you cooking; it just screams the instant something's wrong, so a small fire never becomes a house fire. A test suite does the same for behaviour: it doesn't stop you changing code, it screams the instant a change breaks something you'd already gotten right. Without it you're cooking with the alarm unplugged — everything's fine until the day it very much isn't, and by then the damage is in production.

So what is a test, stripped of all ceremony? It is code that runs your code and states, in code, what the answer must be. That statement is an assertion: assert add(2, 3) == 5 means "I claim this equals 5, and if it ever doesn't, stop everything and tell me." When the claim holds, the assert is silent and your program flows on. When it fails, Python raises an AssertionError — and that failure is not a nuisance, it's the whole point. A failing assertion is a precise, automated bug report you wrote before the bug existed.

Why does this change how you work, not just how safe you are? Because it flips your relationship with change. Untested code is brittle — you tiptoe around it, afraid to refactor, because you can't tell what a change will break. Tested code is malleable — you can rip out an ugly implementation, run one command, and know in seconds whether the behaviour still holds. That confidence to change fearlessly is the real product of testing; catching bugs is just the visible part. The common beginner mistake is treating tests as extra homework you do after the "real" work is done. In practice, tests are part of the work — they're how you find out your code does what you think it does, which is the one thing you can never verify just by reading it.

essence.pydef add(a, b):
    return a + b

# a "test" is just: run the code, assert the result
assert add(2, 3) == 5
assert add(-1, -1) == -2
print("all assertions passed")

all assertions passed

2 · Your first pytest test essential

pytest finds functions named test_* and runs them. Plain assert — pytest rewrites it to show values on failure.

Bare assertions work — until you have more than five of them. Picture a script full of assert lines. The first one that fails stops the whole file, so you never learn whether the other forty would have passed. There's no summary, no count, no "3 failed out of 50" — just one crash and a lot of unknowns. And you have to remember to run the script at all. That doesn't scale to a real codebase, and the fix is a test runner: a program whose entire job is to find your tests, run every one of them even when some fail, and hand you a tidy report.

In Python that runner is pytest, and its cleverest trick is how little it asks of you. You don't inherit from a base class or register anything; you just write ordinary functions whose names start with test_, and put plain assert statements inside. pytest scans your files, notices those test_ names, and runs each one. That automatic finding has a name — test discovery — and the test_ prefix is the convention that drives it. Name a function check_add and pytest walks right past it; name it test_add and it gets run. This is the single rule most beginners trip on: the prefix isn't decoration, it's the signal.

The second thing pytest gives you is assertion rewriting. If you write a plain assert x == 5 in a normal script and it fails, Python just says AssertionError — useless, because it won't tell you what x actually was. pytest rewrites your assertions behind the scenes so that a failure prints both sides: the value it got and the value you expected. That's why in pytest you use plain assert rather than a pile of special assertEqual-style methods — you get readable failures for free, in the language you already know. As you run your suite you'll hear two words constantly: green when everything passes and red when something fails. The daily rhythm of testing is simply keeping the bar green and reacting fast when it turns red.

test_calc.py# calc.py
def add(a, b): return a + b

# test_calc.py
from calc import add
def test_add():            assert add(2, 3) == 5
def test_add_negatives():  assert add(-1, -1) == -2

# run:  pytest -q   ->  2 passed

3 · Reading a failure intermediate

A failing test shows expected vs got — learning to read it is half of testing.

Beginners fear red; experienced testers read it. The first time a test fails, the instinct is to feel like you've done something wrong. But a failing test is the system working exactly as designed — it just caught something before your users did. The skill that separates people who get value from tests from people who just have them is the ability to look at a failure and calmly extract what it's telling you. And a good failure tells you a lot.

Every useful failure boils down to two values: what your code actually produced (call it got) and what you claimed it should produce (want). A failure line like got=4 want=5 is a doctor's diagnosis in miniature — it doesn't just say "you're sick," it points at the exact symptom. The moment you see both numbers, you can ask the one question that resolves every test failure: is the code wrong, or is my expectation wrong? Those are the only two possibilities, and they lead to opposite fixes.

• The code is wrong. You expected 5, the function returned 4, and 5 is genuinely correct — so there's a real bug in the code, and the test just did its job. You fix the function.
• The expectation is wrong. You wrote want=5 but on reflection the right answer really is 4 — your test encoded a mistaken belief. You fix the test. (This is more common than beginners think, and it's why you should never "fix" a red test by blindly changing the expected value to match whatever the code returned — that just paves over the question instead of answering it.)

The lab below is a tiny hand-rolled imitation of what pytest prints, so you can practise reading that got-vs-want line in isolation before you meet pytest's fuller output. Real pytest surrounds these two values with more context — the file, the line, the exact expression — but the heart of every failure you'll ever debug is this same expected-versus-actual comparison. Learn to read it fast and half of testing is already yours.

failure.pydef add(a, b): return a + b

def check(expr_desc, got, want):
    status = "PASS" if got == want else "FAIL"
    print(f"{status}: {expr_desc}  got={got!r} want={want!r}")

check("add(2, 2)", add(2, 2), 5)     # FAIL — shows 4 vs 5, like pytest does
check("add(2, 3)", add(2, 3), 5)

FAIL: add(2, 2)  got=4 want=5
PASS: add(2, 3)  got=5 want=5

4 · The test pyramid intermediate

Imagine a suite that's all end-to-end tests. Every test spins up the whole system — database, web server, the works — clicks through a real user flow, and takes thirty seconds. You have two hundred of them. A full run takes over an hour, they fail intermittently because a network hiccup counts as a failure, and when one does fail it says "something in the checkout flow broke" without telling you where. Developers stop running the suite because it's too slow and too noisy, and a suite nobody runs protects nothing. That miserable outcome has a name — the inverted pyramid — and it's the most common way test suites go bad.

The test pyramid is the shape that avoids it. Picture a triangle: wide at the bottom, narrow at the top, with three layers. The bottom, widest layer is unit tests — each one exercises a single function in isolation, runs in milliseconds, and when it fails it points at the exact function that broke. Because they're so cheap and precise, you can afford hundreds of them, so they form the broad base. The middle layer is integration tests — these check that a few parts work together (your code plus a real database, say), which is slower and touches more, so you write fewer. The narrow tip is end-to-end tests — these drive the whole system like a user would, are the slowest and flakiest, and pinpoint the least, so you keep only a precious handful covering your most critical journeys.

Why this specific shape rather than "just test everything at every level"? Because each layer trades speed and precision for realism, and you want most of your feedback to come from the fast, precise end. A unit test that fails tells you the answer in one second; an e2e test that fails sends you hunting through the whole stack. The pyramid says: catch as many bugs as you can with cheap unit tests, use integration tests to catch the bugs that only appear when parts meet, and reserve slow e2e tests for proving the critical paths actually work front-to-back. The mistake to avoid is chasing realism by writing mostly e2e tests because "they test what the user sees" — you end up with the slow, flaky, un-diagnosable inverted pyramid, and the whole team quietly loses the fast feedback that made testing worth doing.

5 · Professional — organize the suite professional

Convention: a tests/ folder mirroring src/, files test_*.py, config in pyproject.toml. pytest discovers it all.

A test suite that isn't organized rots the same way a junk drawer does. At three tests, layout doesn't matter — you can keep them anywhere. At three hundred, spread across a project with no convention, nobody can answer the simplest question: "where's the test for this module, and does it even have one?" People stop adding tests because they can't find where the existing ones live, duplicates creep in, and the suite slowly stops reflecting the code. Structure is what keeps a growing suite discoverable, and discoverability is what keeps people actually using it.

The convention the Python world settled on is deliberately boring, and boring is the point — predictability is the feature. Tests live in a tests/ directory that mirrors your source layout, so src/orders.py is tested by tests/test_orders.py. Given any source file you can name its test file without looking, and given any test you can name the code it covers. That one-to-one mapping is what lets tooling automatically flag a module that has no test at all — you can't enforce "every module is tested" if there's no rule for where a module's test would be.

The other half of organizing is telling pytest how to behave once, in a config file, instead of remembering flags every run. The standard home is pyproject.toml — the same file that already describes your project — under a [tool.pytest.ini_options] section that pytest reads automatically. Here you pin down where tests live (testpaths), what flags always apply (addopts), and which custom labels, or markers, are allowed. Markers let you tag tests — slow, say — so you can run just the fast ones during development and the whole set in CI. A small but valuable guard is --strict-markers, which turns a mistyped marker into an error instead of a silently-ignored typo. The point of all this isn't bureaucracy: it's that a new teammate can clone the repo, type pytest with no arguments, and everything just runs the way the team intended — because the layout and the config carry the knowledge, not tribal memory.

pyproject.toml[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-q --strict-markers"
markers = ["slow: long-running tests (deselect with -m 'not slow')"]

6 · Tech-lead — a test strategy tech-lead

A lead defines what to test and to what depth so effort goes where risk is. A simple, codified policy beats vague "write more tests." Here's a risk model you can actually compute.

"Aim for 100% coverage" sounds responsible and is usually a trap. Testing effort is not free — every test costs time to write and time to maintain, and time is the one thing a team never has enough of. Spend it evenly across the codebase and you pour hours into exhaustively testing a logging helper that would barely matter if it broke, while the payments module that could cost real money gets the same attention as everything else. A lead's job isn't to demand more tests; it's to point the finite testing budget at the code where a bug would hurt most. That means having an opinion, written down, about what deserves rigor.

The cleanest way to form that opinion is to think about risk, and risk has two ingredients that multiply. The first is blast radius: if this code fails, how much breaks with it? A shared payments path can take down every checkout in the product; a one-off reporting script fails alone. The second is change rate: how often does this code get edited? Code that never changes rarely grows new bugs, but code touched every week is a moving target where regressions hide. Multiply the two and you get a risk score, because the truly dangerous code is what's both load-bearing and constantly changing — high blast radius times high churn. A stable, isolated module scores low even if it's important, because nobody's poking it.

Turning that score into a coverage target makes the policy concrete and, crucially, reviewable. Instead of "test more," you get "payments requires 95% coverage, reporting 70%, throwaway scripts 50%" — numbers anyone on the team can check a pull request against, and numbers that respond when a module's risk changes. That's the difference between a strategy and a slogan: a strategy is something you can compute and defend. The lab below encodes exactly this — a small function that reads blast radius and change rate and returns a required coverage percent. The trap it steers you around is treating coverage as a virtue in itself; coverage is a proxy for confidence, and confidence should be highest exactly where a failure would cost the most, not spread thin as a vanity metric.

strategy.py# Decide required coverage from a module's risk (blast radius x change rate).
def required_coverage(blast_radius, change_rate):   # each 1-5
    risk = blast_radius * change_rate
    if risk >= 16: return 95      # core, changes often -> near-total
    if risk >= 9:  return 85
    if risk >= 4:  return 70
    return 50                     # low-risk glue -> light

modules = {
    "payments":  (5, 4),   # huge blast radius, changes often
    "auth":      (5, 2),
    "reporting": (2, 3),
    "scripts":   (1, 1),
}
for name, (b, c) in modules.items():
    print(f"{name:10} -> require {required_coverage(b, c)}% coverage")

payments   -> require 95% coverage
auth       -> require 85% coverage
reporting  -> require 70% coverage
scripts    -> require 50% coverage

def add(a, b):
    return a + b

assert add(2, 3) == 5
assert add(-1, 1) == 0
print("all assertions passed")

import unittest

def add(a, b): return a + b

class TestAdd(unittest.TestCase):
    def test_positives(self):
        self.assertEqual(add(2, 3), 5)
    def test_mixed_signs(self):
        self.assertEqual(add(-1, 1), 0)

if __name__ == "__main__":
    unittest.main(verbosity=2)
# test_mixed_signs (...) ok
# test_positives (...) ok
# Ran 2 tests ... OK

def median(xs):
    xs = sorted(xs)
    n = len(xs)
    # BUG: integer division picks the wrong element for even-length lists
    return xs[n // 2]

try:
    assert median([1, 2, 3, 4]) == 2.5, f"got {median([1,2,3,4])}"
except AssertionError as e:
    print("RED:", e)     # RED: got 3

def median_fixed(xs):
    xs = sorted(xs); n = len(xs); m = n // 2
    return xs[m] if n % 2 else (xs[m-1] + xs[m]) / 2

assert median_fixed([1, 2, 3, 4]) == 2.5
assert median_fixed([1, 2, 3]) == 2
print("GREEN: fixed")

from collections import Counter

suite = ["unit", "unit", "unit", "unit", "integration", "integration", "e2e"]
c = Counter(suite)

def is_pyramid(c):
    return c["unit"] >= c["integration"] >= c["e2e"]

print(dict(c))            # {'unit': 4, 'integration': 2, 'e2e': 1}
assert is_pyramid(c), "suite is top-heavy: too many slow tests"
print("pyramid OK")

# Layout:
#   src/orders.py      -> tests/test_orders.py
#   src/pricing.py     -> tests/test_pricing.py
# Convention: test_<module>.py, one test class per public class.

import os

def test_path_for(src_path):
    d, fname = os.path.split(src_path)
    module = fname[:-3] if fname.endswith(".py") else fname
    return os.path.join("tests", f"test_{module}.py")

assert test_path_for("src/orders.py") == "tests/test_orders.py"
assert test_path_for("src/pricing.py") == "tests/test_pricing.py"
print("mapping OK")

def required_tier(blast_radius, change_freq):
    # blast_radius, change_freq in {"low","med","high"}
    rank = {"low": 0, "med": 1, "high": 2}
    score = rank[blast_radius] + rank[change_freq]
    return "critical" if score >= 3 else "standard" if score >= 1 else "light"

COMPONENTS = [
    {"name": "payments", "blast": "high", "freq": "high", "has_critical_tests": False},
    {"name": "logging",  "blast": "low",  "freq": "low",  "has_critical_tests": False},
]
def audit(components):
    gaps = []
    for c in components:
        tier = required_tier(c["blast"], c["freq"])
        if tier == "critical" and not c["has_critical_tests"]:
            gaps.append(c["name"])
    return gaps

print(required_tier("high", "high"))   # critical
print("under-tested:", audit(COMPONENTS))   # ['payments']

Knowledge check check yourself