Testing and debugging

Make a day20 folder for today’s files, open it in your editor, and run each script from its terminal, as on earlier days. In 20.3 you will install pytest, a testing tool, into a virtual environment, so create one in day20 now if you like (Day 13: python -m venv .venv, then activate it).

Yesterday’s type checker could tell you that a function returns an int. It could not tell you whether it returns the right int. Today you learn to prove that: you will write small programs that check your other programs, every time you change them, in a second. And when a check fails, you will learn to find the cause on purpose, by looking at what the program is really doing, instead of by guessing.

A museum charges 5 dollars for children under 12, 7 for visitors aged 65 or over, and 10 for everyone else. On Day 9 you would have checked a function like this by printing each result next to the answer you expect:

def ticket_price(age: int) -> int:
    """Return the ticket price in dollars for a visitor of this age."""
    if age < 12:
        return 5
    if age > 65:
        return 7
    return 10


print(ticket_price(8), "expected 5")
print(ticket_price(11), "expected 5")
print(ticket_price(12), "expected 10")
print(ticket_price(40), "expected 10")
print(ticket_price(65), "expected 7")
print(ticket_price(80), "expected 7")

5 expected 5
5 expected 5
10 expected 10
10 expected 10
10 expected 7
7 expected 7

One line is wrong: a 65-year-old pays 10, not 7, because line 5 says age > 65 where the rule says “65 or over”. Did you spot it straight away? With six lines you probably did. Now imagine sixty, or a program with twenty functions, checked again after every change. On Day 12 you tested the to-do manager by typing a sixteen-row session by hand. Each time you change the program, a change can break something that used to work, and you would have to type the whole session again, and read every line, to know.

That is the job of an automated test: code that runs your code with inputs whose correct answers you already know, compares what comes back with those answers, and reports only the ones that do not match. Each input with its expected answer is a test case. A computer never gets bored, never skims, and runs a hundred test cases in less time than it takes you to read one. Because tests cost nothing to rerun, you can run them after every change. A bug that breaks something that used to work is called a regression, and catching regressions the moment they happen is the biggest reason programmers write tests.

Not every check makes a good test case. A good one has these qualities:

The print checks needed a person to compare two numbers. Python can do the comparing itself, with the assert statement:

assert condition
assert condition, message

• assert is a keyword. The condition is any expression that is true or false, usually a comparison such as ticket_price(65) == 7.
• If the condition is true, nothing happens and the program carries on. A passing check is silent.
• If it is false, Python raises an AssertionError, the exception for “a check failed”. Like any uncaught exception (Day 15), it stops the program with a traceback.
• The optional message, after a comma, becomes the exception’s message. Use it to say what went wrong.

>>> assert 2 + 2 == 4
>>> assert 2 + 2 == 5
Traceback (most recent call last):
  ...
AssertionError
>>> price = 10
>>> assert price == 7, f"expected 7, got {price}"
Traceback (most recent call last):
  ...
AssertionError: expected 7, got 10

The first assert passes, so the REPL shows nothing. The second fails, and the traceback ends in a bare AssertionError. The third adds a message, built with an f-string, which says exactly what was expected and what came back.

def ticket_price(age: int) -> int:
    """Return the ticket price in dollars for a visitor of this age."""
    if age < 12:
        return 5
    if age > 65:
        return 7
    return 10


assert ticket_price(8) == 5
assert ticket_price(11) == 5
assert ticket_price(12) == 10
assert ticket_price(40) == 10
assert ticket_price(65) == 7
assert ticket_price(80) == 7
print("All ticket checks passed")

Traceback (most recent call last):
  File ".../day20/ticket_asserts.py", line 14, in <module>
    assert ticket_price(65) == 7
           ^^^^^^^^^^^^^^^^^^^^^
AssertionError

def ticket_price(age: int) -> int:
    """Return the ticket price in dollars for a visitor of this age."""
    if age < 12:
        return 5
    if age >= 65:
        return 7
    return 10


assert ticket_price(8) == 5
assert ticket_price(11) == 5
assert ticket_price(12) == 10
assert ticket_price(40) == 10
assert ticket_price(65) == 7
assert ticket_price(80) == 7
print("All ticket checks passed")

All ticket checks passed

assert is for checking your own code: in tests, and for facts that must be true if the program is correct. It is not for checking what a user typed or what a file contains. Python has a switch, python -O program.py (“optimize”), that skips every assert statement, so a check written with assert can silently disappear. For bad input, raise an exception yourself, as BankAccount does with raise ValueError(...) (Day 15).

def ticket_price(age: int) -> int:
    """Return the ticket price in dollars for a visitor of this age."""
    if age < 12:
        return 5
    if age > 65:
        return 7
    return 10


assert (ticket_price(65) == 7, "seniors pay 7")
print("All ticket checks passed")

All ticket checks passed

def discount(price: float) -> float:
    """Return the price after 10% off orders of 100 or more."""
    if price > 100:
        return price * 0.9
    return price


print("Checking")
assert discount(50) == 50
assert discount(200) == 180
print("Halfway")
assert discount(100) == 90, f"discount(100) gave {discount(100)}"
print("Done")

Checking
Halfway
Traceback (most recent call last):
  ...
AssertionError: discount(100) gave 100

print(is_teen(12), "expected False")
print(is_teen(13), "expected True")
print(is_teen(19), "expected True")

assert is_teen(12) is False, f"is_teen(12) gave {is_teen(12)}"
assert is_teen(13) is True, f"is_teen(13) gave {is_teen(13)}"
assert is_teen(19) is True, f"is_teen(19) gave {is_teen(19)}"

A file full of assert lines has two problems. It stops at the first failure, so one broken check hides every check after it. And the checks sit next to the code they test, so every run of the program also runs the tests. Programmers fix both by putting the tests in a separate file, each one in its own function, and letting a tool run them.

That tool is usually pytest, the most widely used testing tool for Python. It is a third-party package, so install it into your project’s virtual environment with pip (Day 13):

python -m pip install pytest

pytest finds your tests by their names. This is called test discovery:

• It looks in the current folder, and the folders inside it, for files named test_*.py (or *_test.py), such as test_tickets.py.
• In each such file, it runs every function whose name starts with test, such as test_senior_price. A function like that is a test function: it takes no arguments, sets up what it needs, and checks the result with plain assert.

"""Ticket prices for the town museum."""


def ticket_price(age: int) -> int:
    """Return the ticket price in dollars for a visitor of this age.

    Children under 12 pay 5, visitors aged 65 or over pay 7, and
    everyone else pays 10.
    """
    if age < 12:
        return 5
    if age >= 65:
        return 7
    return 10

from tickets import ticket_price


def test_child_price() -> None:
    assert ticket_price(8) == 5


def test_adult_price() -> None:
    assert ticket_price(40) == 10


def test_senior_price() -> None:
    assert ticket_price(65) == 7


def test_child_boundary() -> None:
    assert ticket_price(11) == 5
    assert ticket_price(12) == 10


if __name__ == "__main__":
    test_child_price()
    test_adult_price()
    test_senior_price()
    test_child_boundary()
    print("All tests passed")

All tests passed

To run the tests, open a terminal in the folder holding both files and type:

python -m pytest

(Typing just pytest also works while the environment is active.) Here is what pytest prints. This is sample output: the exact layout, timings, and the header lines naming your system and versions, which are left out here, vary.

============================= test session starts ==============================
collected 4 items

test_tickets.py ....                                                     [100%]

============================== 4 passed in 0.01s ===============================

collected 4 items says it found four test functions. Each dot is one test that passed, and the last line sums up. Add -v (“verbose”), as in python -m pytest -v, to see one line per test, with its name and PASSED. python -m pytest test_tickets.py runs just one file.

Now put the bug back (age > 65 in tickets.py) and run pytest again (sample output):

============================= test session starts ==============================
collected 4 items

test_tickets.py ..F.                                                     [100%]

=================================== FAILURES ===================================
______________________________ test_senior_price _______________________________

    def test_senior_price() -> None:
>       assert ticket_price(65) == 7
E       assert 10 == 7
E        +  where 10 = ticket_price(65)

test_tickets.py:13: AssertionError
=========================== short test summary info ============================
FAILED test_tickets.py::test_senior_price - assert 10 == 7
========================= 1 failed, 3 passed in 0.03s ==========================

Read it from the bottom up, like a traceback:

Notice the line E assert 10 == 7. A plain assert without a message says only AssertionError, but pytest rewrites your asserts so a failure shows the values on each side. That is why test functions under pytest seldom need messages. And the other three tests all ran: one failure no longer hides the rest.

    def test_free_at_fifty() -> None:
>       assert shipping_cost(50) == 0
E       assert 4.99 == 0
E        +  where 4.99 = shipping_cost(50)

test_shipping.py:9: AssertionError

Which inputs should your tests use? You cannot test every possible input, so choose the ones most likely to reveal a mistake. Day 9 gave the first rule: test each side of every boundary. Here is the fuller list:

The cases other than normal ones are called edge cases: inputs at the edges of what a function handles, where it is most likely to break. Code written with one typical input in mind usually works for that input. Bugs live at the edges.

def largest(numbers: list[int]) -> int:
    """Return the largest number in a list that is not empty."""
    best = 0
    for number in numbers:
        if number > best:
            best = number
    return best


def test_typical() -> None:
    assert largest([3, 9, 4]) == 9


def test_largest_at_either_end() -> None:
    assert largest([9, 3, 4]) == 9
    assert largest([3, 4, 9]) == 9


def test_one_item() -> None:
    assert largest([7]) == 7


def test_all_negative() -> None:
    assert largest([-5, -2, -9]) == -2


test_typical()
test_largest_at_either_end()
test_one_item()
test_all_negative()
print("All tests passed")

Traceback (most recent call last):
  File ".../day20/largest_tests.py", line 30, in <module>
    test_all_negative()
    ~~~~~~~~~~~~~~~~~^^
  File ".../day20/largest_tests.py", line 24, in test_all_negative
    assert largest([-5, -2, -9]) == -2
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError

Each test should check one behavior, and its name should say which, such as test_all_negative. Then the report’s list of failures reads like a list of what is broken. Most tests also follow the same three steps, often called arrange, act, assert: set up the data, call the code being tested, and check the result.

>>> 0.1 + 0.2 == 0.3
False
>>> round(0.1 + 0.2, 2) == 0.3
True

def smallest(numbers: list[int]) -> int:
    """Return the smallest number in a list that is not empty."""
    best = 100
    for number in numbers:
        if number < best:
            best = number
    return best


print(smallest([40, 7, 12]))
print(smallest([7]))
print(smallest([-3, -8]))
print(smallest([150, 120]))

Refusing bad input is part of what a function does. BankAccount (Days 16 and 17) must refuse to withdraw more than its balance by raising ValueError, and a test should prove it does. If a later change lets an 80-dollar withdrawal through from a 50-dollar account, you want a test to fail.

Here is BankAccount again, with type hints and docstrings in Day 19’s style:

"""The BankAccount class from Days 16 and 17, with type hints."""


class BankAccount:
    """An account with an owner and a balance that cannot go negative."""

    def __init__(self, owner: str, balance: float = 0) -> None:
        if balance < 0:
            raise ValueError(f"opening balance cannot be negative, not {balance}")
        self.owner = owner
        self.balance = balance

    def deposit(self, amount: float) -> None:
        """Add amount to the balance.

        Raises:
            ValueError: If amount is 0 or less.
        """
        if amount <= 0:
            raise ValueError(f"deposit must be more than 0, not {amount}")
        self.balance += amount

    def withdraw(self, amount: float) -> None:
        """Take amount out of the balance.

        Raises:
            ValueError: If amount is 0 or less, or more than the balance.
        """
        if amount <= 0:
            raise ValueError(f"withdrawal must be more than 0, not {amount}")
        if amount > self.balance:
            raise ValueError(f"only {self.balance:.2f} available, not {amount:.2f}")
        self.balance -= amount

    def __str__(self) -> str:
        return f"{self.owner}'s account: {self.balance:.2f}"

A test cannot just call account.withdraw(80): when the exception is raised, it would crash the test. The test has to expect the exception: pass if it is raised, and fail if it is not. With only Day 15’s tools, that takes a try statement:

from bank import BankAccount


def test_withdraw_more_than_balance_is_refused() -> None:
    account = BankAccount("Ana", 50)
    try:
        account.withdraw(80)
    except ValueError:
        pass
    else:
        raise AssertionError("withdraw(80) did not raise ValueError")
    assert account.balance == 50


test_withdraw_more_than_balance_is_refused()
print("Test passed: withdraw(80) was refused, and the balance is still 50")

Test passed: withdraw(80) was refused, and the balance is still 50

If withdraw(80) raises ValueError, the except clause catches it and does nothing (pass), and the test carries on. If it raises nothing, the else clause (Day 15) runs and raises AssertionError itself, which fails the test. Line 12 then checks that the refused withdrawal left the balance alone.

That is a lot of lines for one idea, so pytest provides pytest.raises, used in a with statement (Day 14):

import pytest

from bank import BankAccount


def test_withdraw_more_than_balance_is_refused() -> None:
    account = BankAccount("Ana", 50)
    with pytest.raises(ValueError):
        account.withdraw(80)
    assert account.balance == 50


def test_withdraw_message_says_what_is_available() -> None:
    account = BankAccount("Ana", 50)
    with pytest.raises(ValueError, match="only 50.00 available"):
        account.withdraw(80)

• import pytest comes first, in its own group of third-party imports, then the import of your own module (Day 19’s import order).
• with pytest.raises(ValueError): means “the code in this block must raise a ValueError”. If it does, pytest catches it and the test carries on after the block. If the block finishes without raising, the test fails with Failed: DID NOT RAISE ValueError. If the block raises a different exception, such as TypeError, that exception is not caught, and the test fails with it.
• match="..." also checks the message: the text must appear in the exception’s message. A few characters, such as . and (, have special meanings in match; plain words and numbers work as you would expect.

with pytest.raises(ValueError):
    account.withdraw(80)
    assert account.balance == 50  # never runs

A failing test tells you that something is wrong and which input shows it. Debugging is the work of finding why: locating the line that causes the wrong behavior, called the bug, and fixing it. Beginners often debug by guessing: change a > to >=, run, change it back, try something else. That can take an hour, and even when the output looks right, you do not know why. A systematic approach finds the cause on purpose:

1. Reproduce it. Find an input that shows the bug every time, and write it down as a failing test.
2. Say what should happen. Before looking at the code, work out by hand what each variable should hold at each step.
3. Narrow it down. Look at what the variables really hold, and find the first place where they differ from what you expected. The bug is at or just before that point.
4. Fix the cause, not the symptom. Then run every test, and keep the new one, so this bug can never come back unnoticed.

Step 3 needs a way to see inside a running program. The simplest is the one you already know: print.

def longest_streak(steps: list[int], goal: int) -> int:
    """Return the most days in a row on which steps reached the goal."""
    best = 0
    current = 0
    for count in steps:
        if count >= goal:
            current += 1
        else:
            if current > best:
                best = current
            current = 0
    return best


print(longest_streak([4000, 12000, 11000, 3000], 10000))
print(longest_streak([12000, 4000, 11000, 10500, 13000], 10000))

2
1

def longest_streak(steps: list[int], goal: int) -> int:
    """Return the most days in a row on which steps reached the goal."""
    best = 0
    current = 0
    for count in steps:
        if count >= goal:
            current += 1
        else:
            if current > best:
                best = current
            current = 0
        print(f"{count=} {current=} {best=}")
    return best


print(longest_streak([12000, 4000, 11000, 10500, 13000], 10000))

count=12000 current=1 best=0
count=4000 current=0 best=1
count=11000 current=1 best=1
count=10500 current=2 best=1
count=13000 current=3 best=1
1

def longest_streak(steps: list[int], goal: int) -> int:
    """Return the most days in a row on which steps reached the goal."""
    best = 0
    current = 0
    for count in steps:
        if count >= goal:
            current += 1
        else:
            if current > best:
                best = current
            current = 0
    if current > best:
        best = current
    return best


print(longest_streak([4000, 12000, 11000, 3000], 10000))
print(longest_streak([12000, 4000, 11000, 10500, 13000], 10000))

2
3

Then delete the debugging print. It did its job, and left in, it would clutter the program’s output for every user. (20.9 shows a tool for messages you want to keep.)

def count_long_words(text: str, length: int) -> int:
    """Return how many words in text have at least length letters."""
    count = 0
    for word in text.split():
        if len(word) > length:
            count += 1
        print(f"{word=} {count=}")
    return count


print(count_long_words("tests catch every small bug", 5))

word='tests' count=0
word='catch' count=0
word='every' count=0
word='small' count=0
word='bug' count=0
0

print has limits. You have to decide in advance which values to show, edit the code, run it, read the output, and then edit again to show something else. And every print must be removed afterward. A debugger is a tool that pauses a running program at a line you choose, so you can look at any variable, run the program one line at a time, and watch the values change. Python includes one, called pdb (the Python debugger), which runs in the terminal.

The easiest way to start it is the built-in function breakpoint(). A breakpoint is a place where the program pauses. Put the call on its own line where you want to pause, and run the program as usual:

def longest_streak(steps: list[int], goal: int) -> int:
    """Return the most days in a row on which steps reached the goal."""
    best = 0
    current = 0
    breakpoint()
    for count in steps:
        if count >= goal:
            current += 1
        else:
            if current > best:
                best = current
            current = 0
    return best


print(longest_streak([12000, 4000, 11000, 10500, 13000], 10000))

When Python reaches line 5, it stops and gives you the debugger’s prompt, (Pdb), where you type commands instead of Python code. These are the ones you need:

Running one line at a time like this is called stepping through the code. Here is a session (sample output; the > lines show the file, the line number, and the function, and the -> line is the line about to run, not yet run):

> .../day20/streak_debug.py(5)longest_streak()
-> breakpoint()
(Pdb) n
> .../day20/streak_debug.py(6)longest_streak()
-> for count in steps:
(Pdb) n
> .../day20/streak_debug.py(7)longest_streak()
-> if count >= goal:
(Pdb) p count
12000
(Pdb) n
> .../day20/streak_debug.py(8)longest_streak()
-> current += 1
(Pdb) n
> .../day20/streak_debug.py(6)longest_streak()
-> for count in steps:
(Pdb) p current, best
(1, 0)
(Pdb) b 13
Breakpoint 1 at .../day20/streak_debug.py:13
(Pdb) c
> .../day20/streak_debug.py(13)longest_streak()
-> return best
(Pdb) p count, current, best
(13000, 3, 1)
(Pdb) q
Quitting pdb will kill the process. Quit anyway? [y/n] y

Step by step: n moves to the for line, then into the loop, where p count shows the first day’s 12000. Two more n commands run current += 1 and go back to the for line, and p current, best confirms (1, 0). Rather than step through every day, b 13 sets a breakpoint on return best, and c runs the rest of the loop up to it. There, p count, current, best shows (13000, 3, 1): the loop is over, current is 3, best is 1, and the function is about to return the 1. The same discovery as with print, without changing what the program prints. Older versions of Python may not ask before quitting, and they may first stop on the line after breakpoint() instead of on it.

You can also start the debugger without editing the file: python -m pdb streak.py pauses before the first line, and b longest_streak then c runs to the start of that function.

pdb works anywhere Python runs, which matters on a computer with no editor. When you have one, your editor’s debugger does the same job with buttons and panels, and shows every variable at once instead of one p at a time. Here is how it works in VS Code with the Python extension you installed on Day 1; other editors, such as PyCharm, have the same parts under similar names, and menu labels change a little between versions.

1. Set a breakpoint. Click in the margin just left of a line number. A red dot appears. No code changes, so there is nothing to delete later.
2. Start debugging. Open the Run and Debug view and choose Run and Debug (or press F5), then choose the Python debugger and Python File. The program runs and pauses at the red dot, with the line about to run highlighted.
3. Inspect. The Variables panel lists every local variable and its current value, and updates after each step. Hover over a name in the code to see its value. Add an expression such as current > best to the Watch panel to see it recalculated at every step. The Call Stack panel lists the calls that led here, the same chain a traceback shows.
4. Step. A small toolbar appears:

5. Use a condition when the loop is long. Right-click a red dot and add a condition, such as count < goal. The program then pauses on that line only when the condition is true, so you can skip straight to the case that matters, even in a loop of ten thousand items.

Some programs cannot be paused: a script that runs every night, or a program a friend runs on another computer. The only way to know what happened is for the program to report as it goes. Debugging prints could do that, but they are all or nothing: you delete them, or every user sees them. The standard library’s logging module lets a program write messages that you can keep in the code and switch on or off from one place. Each message is a log message, and each has a log level, which says how important it is:

Every program has two output channels. Standard output (stdout) is where print writes. Standard error (stderr) is a second channel for problems, where tracebacks go. A terminal shows both, mixed together, so you rarely notice the difference. But the > from Day 13 sends only standard output into a file, and errors still appear on the screen, where you will see them. Logging writes to standard error unless you say otherwise. logging.basicConfig() sets up logging, once, at the start of a program; its stream=sys.stdout argument makes messages go to standard output instead, which today’s examples use so the messages appear in the same channel as print. (sys.stdout is standard output, from Day 13’s sys module.)

import logging
import sys

logging.basicConfig(stream=sys.stdout)

print("Starting the backup")
logging.debug("Looking in the photos folder")
logging.info("Copied 120 files")
logging.warning("The disk is 90% full")
logging.error("Could not copy holiday.jpg")
print("Backup finished")

Starting the backup
WARNING:root:The disk is 90% full
ERROR:root:Could not copy holiday.jpg
Backup finished

To see everything, and in a tidier format, pass two more arguments to basicConfig: level= sets the lowest level to show, and format= sets the layout. In the format string, %(levelname)s stands for the level and %(message)s for the message. Here is longest_streak, fixed, with its debugging print replaced by a log message, and a warning for a week with no good days:

import logging
import sys

logging.basicConfig(
    level=logging.DEBUG,
    format="%(levelname)s: %(message)s",
    stream=sys.stdout,
)


def longest_streak(steps: list[int], goal: int) -> int:
    """Return the most days in a row on which steps reached the goal."""
    best = 0
    current = 0
    for count in steps:
        if count >= goal:
            current += 1
        else:
            if current > best:
                best = current
            current = 0
        logging.debug(f"{count=} {current=} {best=}")
    if current > best:
        best = current
    if best == 0:
        logging.warning(f"No day reached the goal of {goal}")
    return best


print(longest_streak([12000, 4000, 11000], 10000))
print(longest_streak([3000, 4000], 10000))

DEBUG: count=12000 current=1 best=0
DEBUG: count=4000 current=0 best=1
DEBUG: count=11000 current=1 best=1
1
DEBUG: count=3000 current=0 best=0
DEBUG: count=4000 current=0 best=0
WARNING: No day reached the goal of 10000
0

Now change line 5 to level=logging.WARNING and run it again:

1
WARNING: No day reached the goal of 10000
0

The debug messages are gone, but line 22 is still in the code, ready for the next time you need it: change one word back to DEBUG. That is the difference from print. Real programs also add the time to each message, with %(asctime)s in the format, and can send messages to a file instead of the screen; the Go further link shows how.

import logging
import sys

logging.basicConfig(stream=sys.stdout)

total = 0
for price in [2.5, 4.0, 1.25]:
    total += price
    logging.debug(f"{price=} {total=}")
logging.info("Loop finished")
print(f"Total: {total:.2f}")

Total: 7.75

import logging
import sys

logging.basicConfig(
    level=logging.INFO,
    format="%(levelname)s: %(message)s",
    stream=sys.stdout,
)

scores = [72, 105, 88]
logging.debug(f"Checking {len(scores)} scores")
for score in scores:
    if score > 100:
        logging.warning(f"Skipping {score}: more than 100")
    else:
        logging.info(f"Score {score} is fine")
print("Checked")

INFO: Score 72 is fine
WARNING: Skipping 105: more than 100
INFO: Score 88 is fine
Checked

A running club stores race times as text, such as "4:05" for 4 minutes 5 seconds. Here is a module that converts them and finds the fastest, written with tests, edge cases, expected exceptions, and logging in mind:

"""Race times written as minutes and seconds, such as "4:05"."""

import logging
import sys


def parse_time(text: str) -> int:
    """Return the number of seconds in a time written as m:ss.

    Raises:
        ValueError: If text is not whole minutes, a colon, and two
            digits of seconds from 00 to 59.
    """
    parts = text.split(":")
    if len(parts) != 2 or len(parts[1]) != 2:
        raise ValueError(f"time must look like 4:05, not {text}")
    minutes = int(parts[0])
    seconds = int(parts[1])
    if minutes < 0:
        raise ValueError(f"minutes cannot be negative, not {minutes}")
    if not 0 <= seconds <= 59:
        raise ValueError(f"seconds must be 00 to 59, not {parts[1]}")
    total = minutes * 60 + seconds
    logging.debug(f"{text} is {total} seconds")
    return total


def fastest(times: list[str]) -> str:
    """Return the fastest time in a list.

    Raises:
        ValueError: If times is empty.
    """
    return min(times, key=parse_time)


if __name__ == "__main__":
    logging.basicConfig(
        level=logging.DEBUG,
        format="%(levelname)s: %(message)s",
        stream=sys.stdout,
    )
    print("Fastest:", fastest(["10:00", "9:59", "12:01"]))
    try:
        parse_time("3:60")
    except ValueError as error:
        print("Refused:", error)

Running the module directly turns on debug logging and tries it out:

DEBUG: 10:00 is 600 seconds
DEBUG: 9:59 is 599 seconds
DEBUG: 12:01 is 721 seconds
Fastest: 9:59
Refused: seconds must be 00 to 59, not 60

And here is its test file, test_race.py, for pytest:

import pytest

from race import fastest, parse_time


def test_parse_typical_time() -> None:
    assert parse_time("4:05") == 245


def test_parse_smallest_and_largest_seconds() -> None:
    assert parse_time("0:00") == 0
    assert parse_time("3:59") == 239


def test_parse_two_digit_minutes() -> None:
    assert parse_time("12:30") == 750


def test_parse_rejects_60_seconds() -> None:
    with pytest.raises(ValueError, match="seconds must be 00 to 59"):
        parse_time("3:60")


def test_parse_rejects_wrong_format() -> None:
    with pytest.raises(ValueError):
        parse_time("4.05")
    with pytest.raises(ValueError):
        parse_time("4:5")


def test_fastest_compares_times_not_text() -> None:
    assert fastest(["10:00", "9:59", "12:01"]) == "9:59"


def test_fastest_of_one_time() -> None:
    assert fastest(["5:00"]) == "5:00"


def test_fastest_of_empty_list_is_refused() -> None:
    with pytest.raises(ValueError):
        fastest([])

python -m pytest in the race folder reports (sample output):

collected 8 items

test_race.py ........                                                    [100%]

============================== 8 passed in 0.02s ===============================

The test names read like a list of the module’s promises. If someone later “simplifies” fastest to min(times), test_fastest_compares_times_not_text fails at once and says exactly which promise broke. When "3:60" is refused, the exception comes from line 22: int("60") is fine, but not 0 <= 60 <= 59 is true. And "4.05" has no colon, so split(":") gives a one-item list, and line 16 raises.

Use this table to go from what you see to its usual cause. Messages from pytest are samples; their wording varies by version.

• An automated test checks your code against test cases whose answers come from the rule, and reruns in seconds, so it catches regressions the moment a change breaks something. assert condition, message raises AssertionError when a check fails; use it for checking code, never for validating input.
• pytest finds files named test_*.py and functions named test_*, runs them all with python -m pytest, and for each failure shows the line and the values on each side of the comparison.
• Choose test cases that reveal mistakes: a normal case, then edge cases such as each side of a boundary, empty or single items, and negative values. Test refusals too: with pytest.raises(ValueError): passes only if its block raises.
• Debug systematically: reproduce the bug with a test, work out what the values should be, find the first place they differ, then fix the cause and rerun every test. print(f"{name=}") shows values quickly.
• A debugger (pdb through breakpoint(), or your editor’s) pauses at a breakpoint so you can inspect variables and step line by line. logging writes messages with levels that you switch on or off in one place with basicConfig.

Do these in your day20 folder, with pytest installed in your virtual environment (20.3). Type each program yourself, run it, and only then open the answer.

"""The is_prime function from Day 9, with type hints."""


def is_prime(n: int) -> bool:
    """Return True if n is a prime number, otherwise False."""
    if n < 2:
        return False
    for divisor in range(2, n):
        if n % divisor == 0:
            return False
    return True

from primes import is_prime


def test_zero_is_not_prime() -> None:
    assert is_prime(0) is False


def test_one_is_not_prime() -> None:
    assert is_prime(1) is False


def test_two_is_prime() -> None:
    assert is_prime(2) is True


def test_small_primes() -> None:
    for n in [3, 5, 7, 11, 13, 97]:
        assert is_prime(n) is True, f"{n} should be prime"


def test_numbers_with_divisors() -> None:
    for n in [4, 9, 15, 25, 49, 91]:
        assert is_prime(n) is False, f"{n} should not be prime"


if __name__ == "__main__":
    test_zero_is_not_prime()
    test_one_is_not_prime()
    test_two_is_prime()
    test_small_primes()
    test_numbers_with_divisors()
    print("All 5 tests passed")

All 5 tests passed

collected 5 items

test_primes.py .....                                                     [100%]

============================== 5 passed in 0.01s ===============================

import pytest

from bank import BankAccount


def test_new_account_starts_empty() -> None:
    account = BankAccount("Ana")
    assert account.balance == 0


def test_deposit_adds_to_balance() -> None:
    account = BankAccount("Ana", 50)
    account.deposit(25.5)
    assert account.balance == 75.5


def test_withdraw_takes_from_balance() -> None:
    account = BankAccount("Ana", 50)
    account.withdraw(30)
    assert account.balance == 20


def test_withdraw_whole_balance() -> None:
    account = BankAccount("Ana", 50)
    account.withdraw(50)
    assert account.balance == 0


def test_withdraw_more_than_balance_is_refused() -> None:
    account = BankAccount("Ana", 50)
    with pytest.raises(ValueError, match="only 50.00 available"):
        account.withdraw(80)
    assert account.balance == 50


def test_deposit_of_zero_is_refused() -> None:
    account = BankAccount("Ana", 50)
    with pytest.raises(ValueError):
        account.deposit(0)


def test_negative_opening_balance_is_refused() -> None:
    with pytest.raises(ValueError, match="cannot be negative"):
        BankAccount("Ben", -10)


def test_str_shows_owner_and_balance() -> None:
    account = BankAccount("Ana", 50)
    assert str(account) == "Ana's account: 50.00"

def class_average(scores: list[int]) -> float:
    """Return the average of scores, which must not be empty."""
    total = 0
    for index in range(1, len(scores)):
        total += scores[index]
    return total / len(scores)


print(class_average([90, 80, 70]))

python -m pdb class_average.py
> .../day20/class_average.py(1)<module>()
-> def class_average(scores: list[int]) -> float:
(Pdb) b class_average
Breakpoint 1 at .../day20/class_average.py:1
(Pdb) c
> .../day20/class_average.py(3)class_average()
-> total = 0
(Pdb) n
> .../day20/class_average.py(4)class_average()
-> for index in range(1, len(scores)):
(Pdb) n
> .../day20/class_average.py(5)class_average()
-> total += scores[index]
(Pdb) p index, scores[index]
(1, 80)

def class_average(scores: list[int]) -> float:
    """Return the average of scores, which must not be empty."""
    total = 0
    for index in range(len(scores)):
        total += scores[index]
    return total / len(scores)


print(class_average([90, 80, 70]))

80.0

def test_withdraw_too_much() -> None:
    account = BankAccount("Ana", 50)
    with pytest.raises(Exception):
        acount.withdraw(80)

def test_withdraw_too_much() -> None:
    account = BankAccount("Ana", 50)
    with pytest.raises(ValueError):
        account.withdraw(80)
    assert account.balance == 50

age = int(input("Age: "))
assert age >= 0, "age cannot be negative"

if age < 0:
    raise ValueError(f"age cannot be negative, not {age}")

The pytest documentation’s Get Started page walks through installing pytest, writing a first test, and testing exceptions, with a little more than today covers. When you want to keep logs with times, or write them to a file, the Logging HOWTO in the Python documentation is the place to go next.

Check each statement. If the answer is “not yet,” reread the linked subsection.

• I can explain why automated tests catch regressions, and what makes a good test case. Reread
• I can write an assert with a message, and explain why assert is not for checking user input. Reread
• I can install pytest, name test files and functions so it finds them, and read its report. Reread
• I can choose normal cases and edge cases that are likely to reveal a bug. Reread
• I can test that code raises an exception with pytest.raises. Reread
• I can find a bug systematically, and use print to inspect values. Reread
• I can pause a program with breakpoint() and use p, n, s, b, c, and q at the (Pdb) prompt. Reread
• I can set breakpoints in my editor, step over, into, and out, and watch variables. Reread
• I can write log messages at different levels and choose which ones appear. Reread