/approval-tests

Java ApprovalTests

Installation

Look up latest version at https://mvnrepository.com/artifact/com.approvaltests/approvaltests

Maven

<dependency>
    <groupId>com.approvaltests</groupId>
    <artifactId>approvaltests</artifactId>
    <version>VERSION</version>
    <scope>test</scope>
</dependency>

Gradle

testImplementation 'com.approvaltests:approvaltests:VERSION'

Quick Start

import org.approvaltests.Approvals;
import org.junit.jupiter.api.Test;

class ReportTest {
    @Test
    void generatesReport() {
        String result = generateReport();
        Approvals.verify(result);
    }
}

First run: Test fails, .received file created. Review it, approve it (copy to .approved), rerun.

Common Imports

import org.approvaltests.Approvals;
import org.approvaltests.JsonApprovals;
import org.approvaltests.combinations.CombinationApprovals;
import org.approvaltests.core.Options;
import org.approvaltests.scrubbers.DateScrubber;

Core Patterns

Approvals.verify() - Basic verification

Approvals.verify(result);
Approvals.verify(object.toString());

JsonApprovals.verifyAsJson() - Objects as formatted JSON

JsonApprovals.verifyAsJson(user);

Approvals.verifyAll() - Collections with labels

Approvals.verifyAll("Users", users, u -> u.getName() + ": " + u.getEmail());

Scrubbing

Options options = new Options()
    .withScrubber(DateScrubber.getScrubberFor("00:00:00"));
Approvals.verify(result, options);

Combinations

CombinationApprovals.verifyAllCombinations(
    (size, color) -> createProduct(size, color),
    new String[]{"S", "M", "L"},
    new String[]{"red", "blue"}
);

Java-Specific Notes

@UseReporter annotation sets reporter at class level:

@UseReporter(Junit5Reporter.class)
public class MyTest { }

JUnit 5 recommended. Use Junit5Reporter.

Java 8+ required for formatter lambdas.

Git Setup

*.received.*

Commit all .approved.* files.

Quick Decision Guide

• Objects → JsonApprovals.verifyAsJson(obj)
• Arrays/lists (structured) → JsonApprovals.verifyAsJson(items)
• Arrays/lists (labeled) → Approvals.verifyAll("Items", items, formatter)
• Non-deterministic data → scrubbers, add before first run (scrubbers.md)
• Multiple scenarios per test → NamerFactory.withParameters() (advanced.md)
• Input combinations → CombinationApprovals.verifyAllCombinations() (or verifyBestCoveringPairs for huge sets) (api.md)
• State progressions → StoryBoard (api.md)
• Console output → ConsoleOutput (logging.md)
• Short inline expectations → Options().inline(expected) (inline.md)

Reference Files

• api.md - verifyXml/Html, CombinationApprovals, StoryBoard, Verifiable interface, database results
• scrubbers.md - DateScrubber formats, GuidScrubber, RegExScrubber, combining scrubbers
• reporters.md - IDE/diff tool reporters, FirstWorkingReporter, custom reporters
• setup.md - JUnit 4/5 setup, dynamic tests, Kotlin support
• inline.md - Text blocks for inline approvals, InlineOptions modes
• logging.md - ConsoleOutput for System.out/err verification
• advanced.md - NamerFactory, PackageSettings, OS/machine-specific tests, common mistakes