Unit tests & assertions

1 · Arrange, Act, Assert essential

Open a real project's test folder and you'll notice something eerie: the good tests all look the same. Not because everyone copied each other, but because a readable test has a natural shape, and once you've debugged a few messy ones you converge on it. The messy tests are the ones where setup, the call, and the check are tangled together across fifteen lines — when one fails at 2am you can't tell what was being verified, let alone why it broke. The clean ones you can read in three seconds. That shape has a name: Arrange, Act, Assert.

Think of it like a physics experiment written up in a lab notebook. First you set up the apparatus (arrange your inputs and objects). Then you run the one experiment (act — call the function under test exactly once). Then you record whether the result matched your prediction (assert). A good scientist never runs three experiments in one breath and never eyeballs the result — and a good test does the same, isolating a single behaviour so that when the assert fails, the failure is the diagnosis.

Here's the precise definition and why each beat earns its place. Arrange builds the world the test needs: the input values, the object under test, any preconditions — but no logic you're trying to verify. Act is the single line that exercises the behaviour under test; keeping it to one call is what lets a reader instantly see the subject of the test. Assert states the expectation as a machine-checkable claim, so the test decides pass/fail on its own rather than asking a human to squint at printed output. The tool that makes the assert bite is Python's assert statement: it does nothing when its condition is true and raises AssertionError when it's false, which is exactly the behaviour a test runner like pytest hooks into to report a red result.

The common mistake is smearing the three beats together — arranging inside the assert, or acting twice and checking once so you can't tell which call was wrong. The moment a test does more than one act, ask whether it's really two tests wearing one coat. AAA isn't bureaucracy; it's the discipline that turns a failing test from a mystery into a signpost.

aaa.pydef apply_discount(price, pct):
    if not 0 <= pct <= 100: raise ValueError("pct must be 0-100")
    return round(price * (1 - pct/100), 2)

# Arrange / Act / Assert
price, pct = 100.0, 20
result = apply_discount(price, pct)
assert result == 80.0
print("AAA test passed:", result)

AAA test passed: 80.0

2 · Edge cases essential

Here's a pattern that repeats in almost every post-mortem you'll ever read. The code shipped with a test. The test passed. Weeks later it fell over — on an empty list, on a quantity of zero, on the very first day of the month, on a discount of exactly 100%. The test wasn't wrong; it just tested the one comfortable input the author had in mind (the "happy path") and none of the awkward ones at the edges of the valid range. Real bugs don't live in the middle of the range. They lurk at the boundaries.

Picture the set of inputs your function accepts as a fenced field. The happy path is somewhere in the safe green middle. But the bugs pile up along the fence line: the smallest legal value, the largest, the exact threshold where an if flips from one branch to the other, zero, an empty collection, a single-element collection. These are the places where an off-by-one slips in, where < should have been <=, where a divide-by-length blows up because the length was 0. Testers call this boundary-value analysis, and it's the highest-yield habit in the whole discipline: a handful of boundary tests catch more bugs than a hundred random middle-of-the-range ones.

So the technique is deliberate: for every function, ask "what are the extremes and the special values here?" and write an assertion for each. For apply_discount the boundaries are the ends of the legal percentage range — 0% (should change nothing) and 100% (should zero the price) — plus a zero price (a different axis of edge), plus an input that forces the rounding to actually do something. Notice that last one drags in a second, sharper lesson: floating-point numbers are not exact. 9.99 * 0.9 may land on 8.9910000000001 rather than a clean 8.99, so comparing floats with == is a trap that fails intermittently. The fix is math.isclose, which asks "close enough, within a tiny tolerance?" — the correct question for anything computed in floating point.

The mistake to avoid is treating edge cases as an afterthought you'll "add later." Later never comes, and the boundary is precisely where your one happy-path test gave you false confidence. Write the edges with the happy case, one clear assertion each, so a failure names exactly which boundary broke.

edges.pyfrom math import isclose
def apply_discount(price, pct): return round(price*(1-pct/100), 2)

assert apply_discount(50, 0)   == 50.0     # no discount
assert apply_discount(50, 100) == 0.0      # full discount
assert isclose(apply_discount(9.99, 10), 8.99)
assert apply_discount(0, 20)   == 0.0      # zero price
print("all edge cases pass")

all edge cases pass

3 · Testing exceptions intermediate

Beginners test only the sunny day. They check that apply_discount(100, 20) returns 80 and move on, quietly assuming nobody will ever pass a discount of 150% or a negative price. But someone always does — a typo in a config file, a corrupted upstream message, a user fat-fingering a form — and the interesting question is what your code does then. Does it raise a clear error you can catch and log, or does it silently return garbage that poisons everything downstream? The answer is part of your function's contract, which means it deserves a test just as much as the happy path.

Here's the mental flip that trips people up the first time: for a normal test, an exception means failure. For an exception test, an exception is success — and the failure is when no exception fires. It's like testing a smoke alarm. You don't test it by confirming it stays quiet in clean air; you test it by holding a lit match under it and checking that it screams. A test that expects a ValueError passes precisely when the ValueError is thrown, and fails if the code sails through without complaint.

The bare-metal way to express that is a try/except: call the function, and if the expected exception is caught, good; if control falls past the try with no exception, raise an AssertionError yourself because the code failed to complain. That's exactly what the runnable helper below spells out, so you can see the machinery. In practice you don't write that boilerplate — pytest gives you pytest.raises as a context manager: with pytest.raises(ValueError): apply_discount(100, 150) passes only if the block raises ValueError. You should also pin down the message, not just the type, with pytest.raises(ValueError, match="between 0 and 100") — match takes a regular expression checked against the error text.

The subtle mistake is asserting only the exception type and ignoring its message. Two different bugs can both raise ValueError; if your test doesn't check which one, it can pass on the wrong error entirely. Lock in both the type and a distinctive fragment of the message, and your test proves the guard fired for the reason you intended.

Code should fail correctly on bad input. In pytest you use pytest.raises; the underlying idea is a try/except assertion, shown here runnable.

exceptions.pydef apply_discount(price, pct):
    if not 0 <= pct <= 100: raise ValueError("pct must be between 0 and 100")
    return price * (1 - pct/100)

def assert_raises(exc, fn, *a):
    try:
        fn(*a)
    except exc as e:
        return str(e)
    raise AssertionError("expected an exception, none raised")

msg = assert_raises(ValueError, apply_discount, 100, 150)
print("raised as expected:", msg)
# pytest form:  with pytest.raises(ValueError, match="between 0 and 100"): apply_discount(100,150)

raised as expected: pct must be between 0 and 100

4 · Testing a class (state) advanced

A plain function is easy to test because it has no memory. Give it the same inputs and it gives you the same output, every time — nothing sticks. A class is a different animal. An object remembers: a shopping cart accumulates items, a bank account carries a balance, a connection holds a session. The behaviour you care about isn't "what does one method return" but "is the object's state still correct after a whole sequence of operations." That shift — from testing a snapshot to testing a story — is why stateful testing gets its own section.

Think of it like testing a vending machine rather than a calculator. A calculator you probe one sum at a time. A vending machine you have to drive through a scenario: insert a coin (balance goes up), insert another (it accumulates), press a button (balance goes down and a snack drops), then press again with no money (it should refuse and leave the balance untouched). Each step depends on the state left by the last one, and the bug you're hunting — a coin lost, a balance that goes negative — only shows up in the sequence, never in a single call.

So the recipe is: arrange a fresh object, act by making a series of calls that mutate it, then assert on the accumulated state. Two disciplines make this reliable. First, verify the invariant — the property that must hold no matter what, like "a bank balance never goes negative" or "the cart's total quantity equals the sum of what was added." Invariants are the real contract; individual return values are just evidence. Second — and this is the one people botch — each test must start from a clean object. If two tests share a mutated instance, one can pass or fail depending on which ran first, and you've built a flaky suite. In unittest the setUp method runs before every test and is the idiomatic place to mint a fresh instance; in pytest a fixture does the same job. Creating a brand-new object (as the lab does with Cart() for the empty-case check) is the same instinct in miniature.

The classic mistake is asserting only the final number and never checking that a rejected operation left state unchanged — e.g. that an over-limit withdrawal both raises and leaves the balance exactly where it was. A guard that raises but has already corrupted the state is worse than no guard at all, and only a state-after-failure assertion will catch it.

test_class.pyclass Cart:
    def __init__(self): self.items = []
    def add(self, item, qty=1): self.items.append((item, qty))
    def total_qty(self): return sum(q for _, q in self.items)

cart = Cart()
cart.add("book"); cart.add("pen", 3)
assert cart.total_qty() == 4
assert len(cart.items) == 2
assert Cart().total_qty() == 0
print("class behavior verified")

class behavior verified

5 · Professional — the FIRST principles professional

Watch what happens to a test suite that isn't cared for. It starts fast and trusted. Over a year it grows: a few tests hit the real network, one reads the system clock, a couple leave files lying around that the next test trips over. Now the suite takes eight minutes and fails "randomly" once in every ten runs. So the team does the rational-but-fatal thing — they stop trusting it. Failures get re-run until they go green. And the day a failure is real, nobody notices, because a red suite has become background noise. FIRST is the checklist that stops a suite from decaying into that.

FIRST is a mnemonic — Fast, Isolated, Repeatable, Self-validating, Timely — and each letter is really a defense against one specific way suites rot. Think of them as the five habits of a suite people actually run:

• Fast — a unit test should finish in milliseconds. Speed isn't vanity; it's what lets you run the suite on every save. The moment tests take minutes, you run them less, and untested changes slip through. (Slow usually means it's talking to a real database or network — that's an integration test, covered in TQ5, not a unit test.)
• Isolated — a test shares no state with any other and doesn't care what order things run in. It must pass alone and alongside the whole suite. The tell-tale bug is "passes on my machine, fails in CI" caused by leftover global state or a shared file.
• Repeatable — same result every run, on any machine, at any time. This is where the clock, random numbers, timezones, and network calls betray you. The cure is to inject those inputs (pass in the hour instead of calling datetime.now()) or mock them (TQ3), so the test is deterministic.
• Self-validating — the test decides pass or fail by itself, with assertions. If a human has to read the output and judge it "looks right," it isn't a test, it's a demo — and nobody re-checks it under deadline.
• Timely — written close to the code, ideally before it (TDD, TQ4). Tests deferred to "after the release" become the untested legacy that everyone is scared to change.

The principle worth internalising above the rest is Repeatable, because its violation is the most corrosive. A flaky test — one that passes and fails on identical code — is genuinely worse than no test: it trains the whole team to ignore red, which is the one signal testing exists to give. If you take one habit from this section, make it "never let a test depend on time, randomness, or the network without controlling it."

6 · Tech-lead — enforce test quality tech-lead

There's a failure mode that only bites once you're the one reviewing others' code. A pull request arrives with tests, the coverage number ticks up, the CI is green — and every one of those tests is worthless. One asserts nothing. Another asserts True. A third sleeps for two seconds "to let things settle." They all pass, so they all give the team a warm feeling of safety that is completely unearned. A missing test is an honest gap you can see; a bad test is a lie that hides in plain sight. Catching those is the tech-lead's job, and it's the theme of this section.

The instinct of a junior reviewer is to check "are there tests?" The instinct you're building here is to check "do these tests actually test anything?" Think of it like a food-safety inspector who doesn't just confirm the kitchen has a fire alarm, but confirms the alarm has a battery in it. A test with no assertion is an alarm with no battery — bolted to the wall, inspected, approved, and utterly silent when the fire comes.

Because these smells are mechanical, you don't have to rely on tired human eyes to catch them — you can automate the check and run it in CI, so the obvious offenders bounce before a human even looks. The runnable lab below is a miniature linter that flags the common test smells: no assertion at all (proves nothing), assert True (always passes, meaningless), time.sleep (slow and flaky — mock time instead, per TQ3), and too many assertions in one test (a sign it's really several tests fused together and will be painful to diagnose when it fails). A production-grade version would parse the code into an AST — an abstract syntax tree, Python's structured representation of the source via the ast module — rather than scan raw text, so it can reliably tell a real self.assertEqual(...) or pytest.raises from the word "assert" appearing in a comment. Exercise 6 in the ladder builds exactly that AST version.

The mistake to guard against is treating a coverage percentage as proof of quality. Coverage tells you which lines ran during the tests, not whether anything was checked — an assertion-less test can execute a whole module and report 100% coverage while proving nothing at all. Make test quality an explicit review criterion, back it with an automated smell-check, and you close the gap between "green" and "actually safe."

A lead catches bad tests in review, not just missing ones. Here's a lint that flags common test smells — the kind of check you'd add to CI.

test_lint.pyimport re

def lint_test(src: str):
    smells = []
    if "assert " not in src:
        smells.append("no assertion — test proves nothing")
    if re.search(r"assert True\b", src):
        smells.append("asserts True — meaningless")
    if "time.sleep" in src:
        smells.append("sleeps — slow/flaky; mock time instead")
    if src.count("assert") > 8:
        smells.append("many asserts — likely testing too much at once")
    return smells

bad = """def test_thing():
    do_work()
    time.sleep(2)
    assert True"""
print("smells:", lint_test(bad))
good = """def test_add():
    assert add(2, 3) == 5"""
print("smells:", lint_test(good) or "none — clean")

smells: ['no assertion — test proves nothing', 'asserts True — meaningless', 'sleeps — slow/flaky; mock time instead']
smells: none — clean

import unittest

def apply_discount(price, pct):
    if not 0 <= pct <= 100:
        raise ValueError("pct must be 0-100")
    return round(price * (1 - pct / 100), 2)

class TestDiscount(unittest.TestCase):
    def test_ten_percent_off(self):
        price, pct = 100.0, 10          # Arrange
        result = apply_discount(price, pct)   # Act
        self.assertEqual(result, 90.0)  # Assert

if __name__ == "__main__":
    unittest.main(verbosity=2)          # OK

import unittest
def apply_discount(price, pct):
    if not 0 <= pct <= 100: raise ValueError("pct must be 0-100")
    return round(price * (1 - pct / 100), 2)

class TestEdges(unittest.TestCase):
    def test_zero_percent(self):   self.assertEqual(apply_discount(50, 0), 50.0)
    def test_full_discount(self):  self.assertEqual(apply_discount(50, 100), 0.0)
    def test_rounding(self):       self.assertEqual(apply_discount(9.99, 10), 8.99)

if __name__ == "__main__":
    unittest.main(verbosity=2)     # 3 tests OK

import unittest
def apply_discount(price, pct):
    if not 0 <= pct <= 100: raise ValueError("pct must be 0-100")
    return round(price * (1 - pct / 100), 2)

class TestErrors(unittest.TestCase):
    def test_negative_pct(self):
        with self.assertRaises(ValueError):
            apply_discount(100, -5)
    def test_over_100(self):
        with self.assertRaises(ValueError) as ctx:
            apply_discount(100, 150)
        self.assertIn("0-100", str(ctx.exception))

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

import unittest

class BankAccount:
    def __init__(self): self.balance = 0
    def deposit(self, amt):
        if amt <= 0: raise ValueError("amount must be positive")
        self.balance += amt
    def withdraw(self, amt):
        if amt > self.balance: raise ValueError("insufficient funds")
        self.balance -= amt

class TestAccount(unittest.TestCase):
    def setUp(self): self.acct = BankAccount()   # fresh per test
    def test_deposit_then_withdraw(self):
        self.acct.deposit(100); self.acct.withdraw(30)
        self.assertEqual(self.acct.balance, 70)
    def test_overdraw_blocked(self):
        self.acct.deposit(50)
        with self.assertRaises(ValueError):
            self.acct.withdraw(80)
        self.assertEqual(self.acct.balance, 50)   # unchanged after failure

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

import unittest

# BAD: not Repeatable (depends on wall clock), not Isolated (module state)
_cache = {}
def greet_bad():
    import datetime
    h = datetime.datetime.now().hour
    return "Good morning" if h < 12 else "Good afternoon"

# GOOD: inject the input -> Fast, Isolated, Repeatable, Self-validating
def greet(hour):
    return "Good morning" if hour < 12 else "Good afternoon"

class TestGreet(unittest.TestCase):
    def test_morning(self):   self.assertEqual(greet(9), "Good morning")
    def test_afternoon(self): self.assertEqual(greet(15), "Good afternoon")

if __name__ == "__main__":
    unittest.main(verbosity=2)     # deterministic, 2 tests OK

import ast, textwrap

SRC = textwrap.dedent('''
    def test_real():
        assert add(2, 2) == 4
    def test_empty():
        add(2, 2)          # calls but never asserts -> useless
''')

def find_assertionless(src):
    tree = ast.parse(src)
    bad = []
    for node in tree.body:
        if isinstance(node, ast.FunctionDef) and node.name.startswith("test_"):
            has_assert = any(isinstance(n, ast.Assert) for n in ast.walk(node))
            # also count self.assert*/pytest.raises calls in real projects
            if not has_assert:
                bad.append(node.name)
    return bad

print(find_assertionless(SRC))   # ['test_empty']

Knowledge check check yourself