ApproveJ

Approval testing is a technique that allows you to compare the output of your code with a known good/previously approved output.

An approval test case will only succeed if the actual received output is equal to the previously approved output.

If the received output is different from the approved output, the test will fail and leave it to a human reviewer to approve the received output or to fix the code.

Approval testing is especially useful when:

Consider testing a method that returns a summary object:

With traditional assertions, you need to check each field individually — and it’s easy to miss one:

With approval testing, the entire object is captured automatically:

The approved file contains every field, making missing checks impossible:

ApproveJ is a Java implementation of approval testing with a builder-based fluent API, several built-in tools, and optional extension points.

To review the code, file issues or suggest changes, please visit the project’s GitHub page.

In order to use ApproveJ you need a JDK 21 or higher.

To use ApproveJ in your own project, you need to add it as a dependency.

If you use IntelliJ IDEA, install the ApproveJ plugin for integrated diff viewing, one-click approval, and navigation between tests and approved files. See IntelliJ Plugin — IDE Integration for details.

If you have anything that returns an arbitrary string, you can simply build an approval like this.

Executing such a test will create two files next to the test code file named like <TestClass>-<testMethod>-received.txt and <TestClass>-<testMethod>-approved.txt.

The received file will always contain a string representation of the object you want to approve at the last execution.

The approved file will be empty at first. You can use a diff tool of your choice to compare the two files and merge values that you want to approve. If the received value equals the content of the approved file, the received file will be deleted automatically.

You can adjust various details of this process:

Of course, you might want to approve more complex objects than just strings.

For example, a simple POJO like this.

By default, ApproveJ will simply call the object’s toString method to turn the object into a string just before approving it.

Will approve the following value:

See Printing — Customize How Values Are Turned into Strings if you need a more sophisticated way of printing.

Optionally, you can assign a specific name for an approval. When you Approve by File the chosen name will be added to the filename to help identify the specific approval. It is also necessary to assign a name if there are multiple approvals per test case, as otherwise later approvals will overwrite earlier ones.

This test generates two sets of files

ApproveJ provides a generic MultiLineStringPrintFormat that will print the object with each of its properties on a new line to make comparing the result easier. In addition to field-backed properties, it discovers getter-only properties via getXxx() and isXxx() methods (the latter only for boolean/Boolean return types, per the JavaBeans convention). Field-backed properties appear first in declaration order, followed by getter-only properties alphabetically.

To use this format for all approvals, configure it as the default:

Alternatively, apply it to a single approval via printedAs:

Now the approved file will look like this

You can provide a custom Function<T, String> to the builder’s printedBy method.

So the content of the approved file will look like this

For more complex cases, you can implement your own PrintFormat.

This will allow you to also override the filenameExtension method. If you use a FileApprover (see Approve by File), it will be used to determine the files' filename extension. This is useful if your Printer creates a certain format (e.g. JSON, XML, YAML, …).

E.g. the following format will print a Person as a YAML string.

The resulting file will look like this

Instead of calling printedAs on every approval, you can set a project-wide default in your approvej.properties:

Any built-in alias (singleLineString, multiLineString, json, yaml) or a fully-qualified class name works here. See Configuration — Global Defaults and Environment Settings for all available configuration sources and options.

All built-in Scrubber implementations are available via the Scrubbers utility class.

By default, built-in scrubbers replace each match with a numbered placeholder like [uuid 1], [datetime 1]. If the same value appears more than once, it gets the same number, so you can still see that two scrubbed values were equal.

You can change this behavior by calling the replacement method on a scrubber to choose a different Replacement function.

The following replacement functions are available via the Replacements utility class:

You can also implement a custom Replacement<String> as a lambda. It receives the matched string and a count (the number of the distinct match) and returns the replacement.

The RegexScrubber already allows for a lot of special custom cases. In case this isn’t enough, you can also provide a custom Scrubber<T>/UnaryOperator<T> implementation to the builder’s scrubbedOf method.

Note that this Scrubber is a Scrubber<Contact> and not a Scrubber<String>. Hence, it is necessary to apply it before the Printer is applied.

If you want to reuse a scrubber across tests, you can implement the Scrubber interface as a standalone class. See Custom Scrubber for a full walkthrough.

The ApprovalBuilder.byValue() method will use an InplaceApprover to approve the received value by comparison with a directly provided previously approved value. That way, the approved value is plainly visible in the test code. However, this might not be practical for large objects. It also does not allow to use a diff tool to compare the result with the previously approved value.

The ApprovalBuilder.byFile() method will use a FileApprover to approve the received value by comparison with a previously approved value stored in a file. It is used in most of the examples above.

If no approved file exists, it will be created as an empty approved file. The received value will be written to another received file.

If there are approved files with the correct base name, but a different filename extension, these will be automatically deleted. The most recently modified one is renamed with the correct filename extension, if no file of that name exists yet.

If the approved file exists, it will be compared with the received value. If they are equal, the test will pass. Any existing received file will be deleted automatically in that case.

If the files are not equal, the test will fail. The received value will be persisted in a received file. Any existing received value will be overwritten by this.

You can use a diff tool of your choice to compare the two files and merge values that you want to approve.

If you call approve() without a concluding terminal method (by(), byFile(), or byValue()), the test will silently pass without any approval actually happening. To catch this mistake, you can annotate your test class with @ApprovalTest.

This registers a JUnit Jupiter extension that checks after each test method whether all approve() calls were concluded. If any were not, the test fails with a DanglingApprovalError.

The extension is safe to use with parallel test execution.

Some reviewers are blocking. They trigger the diff/merge tool and wait for you to close it again. This gives you the opportunity to merge the content of the two files before the test finishes, so the test does not fail due to your given approval.

Other implementations are non-blocking. These simply display the differences between the two files, but will fail the test immediately. So, after you merged the files or fixed the code, you need to run the test again.

The most common way to set up reviewing is to configure a review script in your approvej.properties. Since each developer on a team may prefer a different diff tool, the best place for this is the user-level configuration file:

The script can contain the following placeholders:

Here are configuration examples for common diff tools:

You can also set this per project in src/test/resources/approvej.properties or via an environment variable (see Configuration — Global Defaults and Environment Settings).

In rare cases you may want to use a different reviewer for a specific test. You can do so by calling the reviewedBy method on the ApprovalBuilder.

If you have a lot of approvals that need to be updated, you might want to just accept all the updates automatically. In that case, you can use the automatic FileReviewer. It simply writes the received value into the approved file without checking them at all.

You can also set this globally via configuration:

ApproveJ provides JSON support via Jackson in two modules:

Both modules provide the same functionality with identical APIs. Choose the one matching your project’s Jackson version.

Since Jackson is a provided dependency, you need to add it explicitly.

ApproveJ provides YAML support via Jackson in two modules:

Both modules provide the same functionality with identical APIs. Choose the one matching your project’s Jackson version.

Since Jackson is a provided dependency, you need to add it explicitly.

Unlike the JSON and YAML extensions, which provide print formats for specific data formats, the HTTP extension addresses a different concern: integration risk.

When your application calls an external HTTP API, a code change can silently alter the requests you send — a different path, a missing header, a changed body format. These issues often go unnoticed until they break in production. The HTTP extension lets you write simple contract tests that approve the exact HTTP requests your code sends. If a request changes, the approval test fails and shows you exactly what changed.

While ApproveJ ships with a range of built-in scrubbers, print formats, and file reviewers, you can create your own. A custom scrubber lets you strip domain-specific dynamic data (e.g. email addresses, internal IDs) that the built-in scrubbers do not cover. Custom print formats and file reviewers go a step further: by implementing the provider SPI, they integrate seamlessly with ApproveJ’s configuration system and can be set as global defaults via approvej.properties.

An approved file is considered a leftover when its originating test method no longer exists in the compiled test classes.

A typical cleanup workflow:

After running your tests, some may have failed because the received value differs from the approved value. Instead of reviewing each failure individually, you can open all unapproved files in the configured default file reviewer at once.

This scans the inventory for approved files that have a corresponding received file and opens each pair in the file reviewer.

If you are confident that all received files are correct, you can approve them all at once. This moves every received file to its corresponding approved file, replacing the previous content.

The build plugin tasks rely on an inventory file that ApproveJ maintains automatically. Every time a test calls byFile(), ApproveJ records the approved file path and the originating test method. At the end of the test run, all entries are merged into a project-level inventory file:

The file uses Java Properties format. Each entry maps a relative file path to the test reference that created it:

The inventory is updated incrementally. Only entries for test methods that ran in the current execution are refreshed. Entries for tests that did not run are preserved.

Install the plugin from the JetBrains Marketplace:

When a test produces a .received file, the plugin shows a banner at the top of the file with actions:

Similarly, when an approved file has a pending received file, its banner offers a Compare with Received action.

These actions are also available from the context menu on .received files in the project tree.

The plugin provides bidirectional navigation between test code and approved files:

The plugin warns you when an approve() call is missing its terminal method (like byFile() or byValue()). Without a terminal method, the approval is never actually executed — the test silently passes without checking anything.

The inspection offers quick fixes to add a terminal method:

Configuration values are resolved in the following order (highest to lowest priority):

This hierarchy allows you to:

See the cheat sheet for a complete list of all supported properties.

Configuration is resolved in priority order: environment variables > project properties (src/test/resources/approvej.properties) > user home properties (~/.config/approvej/approvej.properties) > defaults.