beginner30 minby DevFox

Your First Automated Test

Write, run and read a real automated test: arrange, act, assert; what a good failure message looks like; and why a test that never fails is not a test.

Testing
Automation

Every automated test you will ever read — in any language, in any framework, written by anybody — is the same three lines wearing different clothes. Put the world into a known state. Do one thing. Check what came out.

That is the whole idea, and this lesson is you writing one. There is code here and you do not need to be a programmer to follow it: a test is one of the simplest useful programs there is.

By the end you will have written, run and read a real test, you will know the three-part shape every test has, and you will know why a test that has never failed is not yet a test.

What a test actually is

Strip away the tooling and a test is a small program that sets up a situation, performs one action, and compares the result with what was expected. If they differ, it reports a failure.

No magic. The framework's entire contribution is finding your tests, running them, and printing something readable when one fails.

Arrange
Put the world into the state this test needs. An account, a file, a value.
Act
Do the one thing being tested. One thing — if there are two, it is two tests.
Assert
Compare what happened with what should have happened.

The three parts, in every test, in every language

Some people say given / when / then instead, which is the same division you met in acceptance criteria. Every test you read for the rest of your career has these three parts, labelled or not.

Your first test

We will test the discount rule from the boundary-values lesson. Here is the function under test, in discounts.py:

python

def discount_percent(order_total: float) -> int:
    """Discount for an order total, in whole percent."""
    if order_total >= 100:
        return 20
    if order_total >= 20:
        return 10
    return 0

And the test, in test_discounts.py:

python

from discounts import discount_percent


def test_no_discount_below_twenty_pounds():
    # Arrange
    order_total = 19.99

    # Act
    result = discount_percent(order_total)

    # Assert
    assert result == 0

Install the runner and run it:

That single dot is your test passing. Two conventions did the work of configuration: the file is named test_*.py and the function is named test_*, which is how pytest found it without being told.

Making it fail on purpose

A passing test tells you very little on its own. Break it deliberately — change the expected value to 5 — and run again:

Read that output, because reading failures is most of the skill. It names the test, shows the line that failed, and shows both values: 0 == 5 is false, and it tells you which side was which.

Change it back. And take the habit from this: whenever you write a test, make it fail once, by breaking the expectation or the code. A test you have never seen fail might be asserting nothing at all — which was the regression-test mistake from earlier in this course, and it is the single most common way an automated suite provides false comfort.

The boundaries, cheaply

Now the payoff from the boundary lesson. Every value you identified, checked in milliseconds:

Seven boundary cases in two hundredths of a second, on every commit, forever. Compare that with checking them by hand through a browser — and note that the two "exactly on" cases are the ones that catch an off-by-one, and they cost nothing to include.

When the same check repeats with different values, most frameworks let you write it once:

Seven tests, one function, and each row still fails independently with its own values shown.

A test that reads badly

Bad — four checks, one name, and a failure that says nothing:

Good — one behaviour per test, named for what it claims:

The bad version has two specific problems. It stops at the first failure, so if the £20 boundary is wrong you never learn whether £100 is — one bug hides the next. And it produces test_discounts failed, which tells a reader nothing; they have to open the file to find out which rule broke.

A test name is documentation that cannot go out of date, because it runs. test_ten_percent_starts_exactly_at_twenty_pounds states a business rule, and if that name appears in a failure list, everyone in the room knows what is broken without reading any code.

Assertions worth knowing

A handful of shapes covers nearly everything:

That last one deserves attention. Testing that invalid input is rejected is as important as testing that valid input works — it is the "what happens when it fails" question from the requirements lesson, in code. And note it also asks a real question of the code above: what should discount_percent(-10) do? The function as written returns 0 silently, and whether that is right is a requirements gap the test just found.

A test with setup

Real tests usually need something to exist first. When several share the same arrangement, a fixture provides it:

Two things make fixtures safe. Each test gets a fresh one — the second test's addition cannot affect the first — which is the structural answer to the shared-mutable-data problem from the last lesson. And the fixture's name in the test's arguments says what the test needs, so it is readable without scrolling.

Running them usefully

--lf — last failed — is the one that changes your working rhythm. Fix something, re-run only what was broken, get an answer in a second.

The final step is out of your hands and worth asking for: the suite runs on every change, in the pipeline, and a failure blocks the merge. A suite that only runs when someone remembers is a suite that is red for three days before anybody notices.

Cheat sheet

Where to go next

You can write a test. The next lesson widens the definition of "working" past correctness: usability, accessibility, compatibility, performance and security — the requirements nobody writes down, and the cheapest first check for each.

Before that, write three tests against something real: a function you have, or one you write in five minutes. Put a boundary value in each, and break one on purpose to see it fail. That last part is the habit worth forming today.