Structuring a unit test: arrange, act, assert

Goal

Write tests whose failure message tells the reader what scenario broke and what the expected behaviour was, without opening the test body.

Prerequisites

A test runner (pytest or unittest) and code whose units can be constructed without global state.

Steps

1. Name the test after the scenario and the expected outcome: test_stale_if_match_is_rejected_with_412.
2. Arrange: build exactly the state the scenario needs. Prefer explicit fixtures or builders over large shared setup; pytest fixtures declare what each test uses.
3. Act: call one function or endpoint once.
4. Assert: check the observable outcome and, where relevant, that nothing else changed. Use one logical assertion per test; several assert statements about the same outcome are fine.
5. Keep test data minimal and meaningful; magic numbers get a name.
6. Make the test deterministic: fixed clocks, seeded randomness, no network.

Expected result

A failing test names the scenario in its title and the mismatch in its message; a reader can fix the code without reverse-engineering the test.

Limits and test basis

The pattern applies to unit and most integration tests; exploratory or property-based tests follow different shapes. Over-isolated units can pass while the composition fails, so the structure complements, not replaces, higher-level tests.