approval-tests

STARTER_CHARACTER = 📸

Approval Tests

Philosophy

"A picture's worth 1000 assertions."

Approval tests verify complex output by comparing against a saved "golden master" file instead of writing individual assertions. You capture the output once, review it, approve it, and future runs compare against that approved snapshot.

You don't need to know the expected output upfront. Run the code, see what it produces, decide if it's correct. Approval is a judgment - you're confirming this is what the code should produce. Whoever writes the code reviews and approves.

Use approval tests when:

• Output is complex - instead of 20 assertions, one approval captures everything
• Characterizing legacy code - snapshot behavior, then refactor safely
• Combinatorial testing - test all input combinations in one approval
• Assertions would be tedious or brittle

Use assertions when:

• Simple values or specific edge cases
• Non-deterministic output that can't be scrubbed

Core Workflow

1. Write test with verify(result)
2. Run test → FAILS (no .approved file yet)
3. Creates: TestName.approved.txt (empty) + TestName.received.txt (actual output)
4. Review .received file - is this correct?
5. YES → rename/copy .received to .approved
6. Run test again → PASSES
7. Commit .approved file to version control

File naming convention:

{TestClass}.{test_method}.approved.txt   ← commit this
{TestClass}.{test_method}.received.txt   ← gitignore this

Critical rules:

• .approved files ARE your test expectations - commit them
• .received files are temporary - add *.received.* to .gitignore
• Never edit .approved files by hand - always generate via test

When a test fails, a diff tool opens showing approved vs received. This is how you review changes. Reporters configure which diff tool to use.

Core API Pattern

All languages follow the same pattern:

verify(result)                    # Basic string/object verification
verify_as_json(object)            # Objects as formatted JSON
verify_all(header, items)         # Collections with labels
verify_all_combinations(fn, inputs)  # All input combinations