<!-- toc -->

Contents

• What can it be used for?
• Documentation
  • Missing Documentation?
• Getting started
  • New Projects
  • Docs
  • Learning
• How to get it
  • Maven
  • Gradle
• Podcasts
• Examples
• Approved File Artifacts
• More Info
  • No Checked Exceptions Philosophy
• LICENSE
• Developer notes<!-- endToc -->

ApprovalTests.Java

Capturing Human Intelligence - ApprovalTests is an open source assertion/verification library to aid unit testing.

It is compatible with JUnit 3, 4 & 5 and TestNG.

Works on JDK 1.8+ (tested on 1.8, 17, 21, 24, 25).<!-- singleLineInclude: JavaVersionTest.testSupportedJavaVersions.approved.txt -->

What can it be used for?

Approval Tests can be used for verifying objects that require more than a simple assert. They also come prepackaged with utilities for some common java scenarios including

• HashMaps & Collections

• Long Strings

• Log Files

• JPanels

• Xml

• Html

• Json

• Getting Legacy Code under tests

  Want to see more? Check out Better Testing with Approvals

Documentation

• ApprovalTests
• ApprovalTests-util

Missing Documentation?

If there is documentation you wish existed, please add a page request to this issue.

Getting started

New Projects

The best way to get started is download and open one of the starter projects:

• Java
  • Maven
  • Gradle
• Kotlin
• Groovy
• Scala

These are standard projects and can be imported into any editor or IDE.
They also all have CI with Github actions.

Docs

You might also want to check out the Getting Started Overview

Learning

A great way to learn Approval Tests if you are new to it is to try out the Koans.

How to get it

It's on Maven Central, search for 'approvaltests'.

Maven

If you're using Maven, add this to your pom file:

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

Gradle

dependencies {
    testImplementation("com.approvaltests:approvaltests:30.1.0")
}

or download the jars from maven central repository

Video Tutorials

You can watch a bunch of short videos on getting started and using ApprovalTests in Java at youtube.

Note: There are a lot of videos about ApprovalTests in .Net They are equally useful for understanding the concepts despite being in a different programming language.

Podcasts

If you prefer auditory learning, you might enjoy the following podcast (Note: Some of these talk about the .net side)

• Cucumber Podcast
• Hanselminutes
• Herding Code

Examples

ApprovalTests eats it own dogfood, so the best examples are in the source code itself.

None the less, Here's a quick look

<!-- snippet: demo -->

<a id='snippet-demo'></a>

public class SampleArrayTest
{
  @Test
  public void testList()
  {
    String[] names = {"Llewellyn", "James", "Dan", "Jason", "Katrina"};
    Arrays.sort(names);
    Approvals.verifyAll("", names);
  }
}

^{<a href='/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.java#L8-L19' title='Snippet source file'>snippet source</a> | <a href='#snippet-demo' title='Start of snippet'>anchor</a>}

<!-- endSnippet -->

Will Produce a File SampleArrayTest.testList.received.txt

<!-- snippet: /approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt -->

<a id='snippet-/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt'></a>

[0] = Dan
[1] = James
[2] = Jason
[3] = Katrina
[4] = Llewellyn

^{<a href='/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt#L1-L5' title='Snippet source file'>snippet source</a> | <a href='#snippet-/approvaltests-tests/src/test/java/org/approvaltests/demos/SampleArrayTest.testList.approved.txt' title='Start of snippet'>anchor</a>}

<!-- endSnippet -->

Simply rename this to SampleTest.testList.approved.txt and the test will now pass.

Approved File Artifacts

The *.approved.* files must be checked into source your source control. This can be an issue with git as it will change the line endings. The suggested fix is to add *.approved.* binary to your .gitattributes

More Info

• ApprovalTests.com

No Checked Exceptions Philosophy

Approval Tests follows the no checked exceptions" philosophy. That is, our API only throws runtime exceptions.

LICENSE

Apache 2.0 License

Questions?

twitter: @LlewellynFalco or #ApprovalTests

Developer notes

The suggested way to contribute to ApprovalTests is to pair with Llewellyn
However, if you are set on forking please read these notes