Approval testing

Approval testing

Some outputs resist hand-written assertions: a rendered invoice, a generated SQL query, a serialized object graph, an ASCII report. Spelling out every field in assertEquals is brittle to write and unreadable afterward. Approval testing inverts the flow: the code prints its result, a human reads it once and approves it, and the framework guards that approved value from then on.

Method

1. Emit output in a stable, diffable format. Serialize to sorted JSON, pretty-printed text, or a canonical string. Unstable key order or trailing whitespace turns every run into a false diff, so normalize before you write.
2. Split into received and approved files. The run writes invoice.received.txt; the test compares it to invoice.approved.txt. A missing or mismatched approved file fails the test. Tools like ApprovalTests, Verify, syrupy, or insta manage this pair for you.
3. Review the received file like a pull request. Read it line by line and decide whether every value is correct. This review is the actual assertion; skimming it defeats the method. Wrong output you approve is wrong output you have now locked in.
4. Approve by promoting received to approved. Rename or run the approve command, then commit the approved file. It now lives in version control as the reviewed specification of the output.
5. Wire a readable diff reporter. Configure the framework to open a diff viewer on mismatch so the change is obvious at a glance. A wall of "line 417 differs" trains people to re-approve blindly.
6. Scrub nondeterminism before comparison. Replace timestamps, GUIDs, temp paths, and random ids with fixed sentinel values. Anything that changes run to run must be masked, or the approval never stabilizes.
7. Review approved-file changes in code review. A diff to an .approved file in a pull request is a behavior change. Treat an unexplained one as a red flag, the same as a suspicious source edit.

Litmus tests

• When output changes, does the diff show a human exactly what moved and let them accept or reject it in seconds?
• Is every run's received file byte-identical given the same input, with all volatile values masked?
• Would a reviewer notice an incorrect value slipping into an approved file during code review?

Boundaries

Approval testing shines when output is large and recognition is easy; for a rule expressible in one line, a plain assertion is clearer and defer to unit-test-design. For screenshots specifically, use visual-regression-testing, which handles image thresholds this text-oriented method cannot.