In Arrange-Act-Assert, does one logical assertion per test mean one assert call?

## What the guideline actually says "One assertion per test" is shorthand, and taken literally it is wrong. The guideline is one logical assertion — one outcome, one claim about behaviour — per test. That single claim is often expressed by several assertion statements, because one outcome can have several facets. Checking that a newly created playlist has the requested name, the requesting owner and zero tracks is three statements about one outcome: the playlist was created as asked. Splitting that into three tests triples the arrange phase and buys nothing, because the three can only fail together for the same reason. What the guideline forbids is a test that makes several *unrelated* claims, and above all a test that acts more than once. The moment a test contains act, assert, act, assert, its name can no longer describe it, and when the first assertion fails, everything after it never runs — so you learn about one defect where the test could have told you about three. ## Why the rule is about diagnosis, not counting The purpose of the structure is that a red test names a cause. Two properties give you that: 1. **One act.** If exactly one behaviour was exercised, a failure implicates that behaviour and its arrange phase, and nothing else. 2. **Assertions that describe one outcome.** If they all follow from a single claim, whichever one fires first tells you the same story. Counting assertion statements is a proxy for these, and a bad one. A test with a single assertion comparing two large structures can be less diagnostic than four narrow assertions, because the failure message is a wall of diff instead of a sentence. Conversely a test with one assertion that follows three separate acts is squarely a violation despite the count. ## The first-failure problem, and what to do about it Assertions normally stop the test at the first failure. That is usually what you want — the later assertions are describing the same broken outcome and their messages would be noise — but it hurts in one specific case: a set of independent checks over the same result where you would genuinely like to see all of them, such as validating several fields of one returned record. Two standard answers exist: - **Assert on the whole value at once.** Compare the returned record to an expected record built in arrange, so one comparison covers every field and the failure message shows every difference. This is usually the better answer when the fields belong together. - **Use a soft or grouped assertion facility**, where several checks are collected and reported together at the end of the block. Most assertion libraries offer one. It is a reporting tool, not a licence to make unrelated claims: the checks inside the group must still describe one outcome. ## The cost of over-splitting Taken to an extreme, one-assertion-per-test produces suites where every test repeats an expensive arrange phase. On a suite that already takes 27 minutes, splitting a well-focused three-assertion test into three tests that each rebuild the same fixture is a straight multiplication of the slowest phase for zero diagnostic gain. It also makes the suite less readable: three test names that differ by one word each are harder to scan than one name that states the outcome. The honest formulation is a question rather than a count: **if this test goes red, will its name and its first failing assertion tell me what broke?** If yes, the test is focused however many assertion statements it has. If no — because the reader cannot tell which of two behaviours failed — split it along the act, not along the assertions. ## How this shows up in review Useful review prompts, in order of value: - Does the test have exactly one act? If not, split it there. - Does the test name state an outcome? A name that has to use "and" is usually describing two. - Would each assertion, on failing, produce a message that identifies the problem without a debugger? Assertions with no context in their message are the reason people distrust a red suite. - Are the assertions checking the behaviour's outcome, or re-checking the arrange phase? Verifying the fixture in the assert phase is a sign the arrange phase should carry a precondition check instead. ```pseudocode # one logical assertion, three statements: all describe "the playlist was created as requested" result = playlistService.create(name = "Late Shift", ownerId = 4417) expect(result.name).toEqual("Late Shift") expect(result.ownerId).toEqual(4417) expect(result.trackCount).toEqual(0) ```