ApprovalTests.java.StarterProject

A starter project for ApprovalTests with JUnit 5 and Maven. Works on Mac, Linux, and Windows.

What is ApprovalTests?

ApprovalTests is a testing library that replaces fragile hand-written assertions with a "snapshot" style workflow:

1. Run a test — it captures the output to a .received file
2. Review the output and approve it by renaming the file to .approved
3. Future test runs compare against the approved file — if they match, the test passes

This makes it easy to test complex objects, large outputs, and anything that's hard to assert field-by-field.

Quick Start

git clone https://github.com/approvals/ApprovalTests.java.StarterProject.git
cd ApprovalTests.java.StarterProject
./build_and_test    # Mac/Linux
build_and_test.cmd  # Windows

Project Structure

src/
  main/java/org/samples/
    Person.java               # Example domain object
  test/java/org/samples/
    SampleTests.java          # Four example tests (start here)
    PackageSettings.java      # Configure the diff reporter for this package
    *.approved.txt / .json    # Approved snapshot files checked into git

The Sample Tests

SampleTests.java contains four tests:

testNormalJunit — a plain JUnit assertion to confirm your setup works.

testWithApprovalTests — the simplest approval test:

Approvals.verify("Hello World");

The approved output lives in SampleTests.testWithApprovalTests.approved.txt.

testJson — approves a Java object serialized as JSON (requires Gson, already included in pom.xml):

Person hero = new Person("jayne", "cobb", true, 38);
JsonApprovals.verifyAsJson(hero);

The approved output lives in SampleTests.testJson.approved.json.

testInline — stores the approved output directly in the test source file using a Java text block:

var expected = """
  {
    "firstName": "jayne",
    "lastName": "cobb",
    "isMale": true,
    "age": 38
  }
  """;
Person hero = new Person("jayne", "cobb", true, 38);
JsonApprovals.verifyAsJson(hero, new Options().inline(expected));

The approved output is embedded in the test itself — no separate .approved file needed. When the output changes, ApprovalTests updates the text block in place, so you review and commit the diff like any other code change. This is convenient for small outputs you want visible alongside the test logic.

Approving Output

When a test fails because the received output doesn't match the approved file, you have two options:

• Use your diff tool — PackageSettings.java configures DiffReporter, which opens your diff tool automatically on failure so you can review and accept the change.
• Approve from the command line — run .approval_tests_temp/approve_all.sh (Mac/Linux) to approve all pending received files at once.

Approved files (.approved.*) are committed to git. Received files (.received.*) are not.

Configuring Your Diff Tool

PackageSettings.java sets the reporter for all tests under org.samples:

public ApprovalFailureReporter UseReporter = DiffReporter.INSTANCE;

DiffReporter auto-detects common diff tools. You can also specify one explicitly:

OS	Suggested tool
Mac	DiffMerge
Windows	WinMerge
Linux	Meld

Dependencies (pom.xml)

Dependency	Purpose
com.approvaltests:approvaltests	ApprovalTests library
org.junit.jupiter:junit-jupiter	JUnit 5
com.google.code.gson:gson	JSON serialization for JsonApprovals

Next Steps

• Delete or modify the sample tests and start writing your own
• Read the ApprovalTests.java User Guide
• Explore reporters, combinational approvals, and other features in the user guide