Test Structure

## What the convention is Arrange-Act-Assert (AAA) is a layout convention for the body of a single test. It says a test should read top to bottom in three visually separated phases: build the world the behaviour needs, invoke the behaviour exactly once, then check what came back against what you expected. No runner enforces it and nothing fails if you ignore it. Its entire value is what it does to a human reader six months later, at the moment a test goes red and someone has to decide within seconds whether the product broke or the test did. ### Arrange Everything the behaviour needs before it can run: constructing the object or handle under test, building the input values, seeding whatever store or collaborator the code reads from, configuring stand-ins for dependencies, freezing a clock, and registering cleanup. Arrange answers the question "what world does this behaviour live in?" It is normally the longest phase, and when it grows past a handful of lines the usual remedy is to push construction behind a named builder or factory function so the test still reads as one idea. ### Act One invocation of the behaviour under test, with its result captured in a local variable where the behaviour returns one. The result may be a returned value, a raised error, or an observable state change. The act phase should be one statement, or very close to it. If it is six statements, the first five are almost always arrange in disguise — reaching the state you want is preparation, not the thing you are testing. A test with two genuinely distinct acts is two tests. ### Assert The statements that compare the observed outcome against the expected one. The thing that decides the behaviour is wrong is called the oracle, and in a unit test the oracle is these assertions plus the expected values in them. The assertions should express one logical outcome, so a red test names one cause. ## Why the order matters The three phases correspond to the three questions a person debugging a failure asks in order: what was set up, what was done, what was expected. Keeping them in that order and separating them with a blank line means the failing line number alone tells you which phase broke. Interleaving act and assert destroys that property: when the third assertion fails you no longer know whether the state it inspects came from the act you care about or from the two calls you made in between. ## The same shape under another vocabulary Given-When-Then names the identical three phases in specification vocabulary — Given is arrange, When is act, Then is assert. Teams that write executable specifications and teams that write plain unit tests are using one structure with two vocabularies, which is why a scenario translates mechanically into a test body. The difference is register and audience, not shape. There is also a longer relative: the four-phase test described by Meszaros — setup, exercise, verify, teardown. AAA is that pattern with teardown left implicit, because most modern runners handle cleanup through a registered hook rather than trailing statements a failed assertion would skip. ## What the structure buys you in practice - A failure's line number identifies the phase, so triage starts from a fact rather than a read-through. - A reviewer can see at a glance that a test acts more than once, which is the commonest cause of a test whose name no longer describes what it checks. - Arrange bloat becomes visible instead of being spread through the method, which is what prompts extracting a builder. - Tests in a suite start to look alike, and uniform tests are scannable; a suite of 900 tests that all read in three beats is navigable, one where every test invents its own shape is not. ## Common mistakes - Hiding the act inside an assertion, so the call under test is evaluated as an argument. A raised error then surfaces as an assertion problem rather than as the behaviour it is. - Writing the three phase names as comments and then ignoring them, so the comments drift and lie. Blank lines and a one-line act carry the structure without maintenance. - Putting checks in the arrange phase and calling them setup, without deciding whether a failing one should be reported as a broken test or a failed expectation. - Sharing the arrange phase across the whole file so that reading a test tells you nothing about the state it runs against. ## Worked shape ```pseudocode test "adding a track to a playlist increases its length" # arrange playlist = playlistWith(trackCount = 12) track = trackNamed("Halcyon Drift") # act result = playlistService.add(playlist.id, track.id) # assert expect(result.trackCount).toEqual(13) ``` Three beats, one act, one outcome. If this goes red, the line number alone tells you whether the fixture could not be built, the call blew up, or the behaviour returned something else.