com.github.writethemfirst.approvals

Class Approvals

java.lang.Object

com.github.writethemfirst.approvals.Approvals

public class Approvals
extends java.lang.Object

# Approvals

Approval Testing is a way of considering Unit Tests without focusing on writing tons of assertions, but by letting the framework generate the references to use in assertions.

Approvals is this framework’s main entry point for validation of data produced by your program, by comparing it to data you already reviewed and approved manually.

Using Approvals for checking your program’s data will actually trigger a comparison between the output it produces, and content stored in a file somewhere in your project’s tests. If that file doesn’t exist, the framework will warn you and propose you to review the data produced by your program to approve (or not) what has been generated. After you reviewed it and selected the proper output, it’ll use the resulting file for future comparisons.

An Approvals object can be constructed with:

• a Class to be linked with the object. It is used in order to automatically compute the path and name of the approved files, used to store the output data of your program.

• a Reporter, to be used if differences are found between your program’s output and the approved file’s content. Some Reporters are provided by the framework, but you can also provide your own.

The basic and main entry point you should have a look at in this Approvals class is the verify(Object) method, allowing to compute a comparison between an output and some content stored in an approved file.

Version:

1.0

Author:

mdaviot / aneveux

See Also:

Reporter

Constructor Summary

Constructors

Constructor and Description
Approvals() Constructs an Approvals object using
Approvals(java.lang.Class<?> clazz) Constructs an Approvals object using the default Reporter (Generic.DEFAULT).
Approvals(java.lang.Class<?> clazz, Reporter reporter) Constructs an Approvals object.
Approvals(Reporter reporter) Constructs an Approvals object using the StackUtils.callerClass(Class).

Method Summary

Modifier and Type	Method and Description
void	verify(java.lang.Object output) Compares the actual output of your program (the function’s argument) and the content of the approved file matching with the test method.
void	verify(java.lang.Object output, java.lang.String methodName) Compares the actual output of your program (the function’s argument) and the content of the approved file matching with the test method.
void	verifyAgainstMasterFolder(java.nio.file.Path actualFolder)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Approvals

public Approvals()

Constructs an Approvals object using

• the default Reporter (Generic.DEFAULT)

• the StackUtils.callerClass(Class).

Approvals

public Approvals(Reporter reporter)

Constructs an Approvals object using the StackUtils.callerClass(Class).

Parameters:

reporter - The Reporter to trigger in case of differences between the output and an approved file’s content.

Approvals

public Approvals(java.lang.Class<?> clazz)

Constructs an Approvals object using the default Reporter (Generic.DEFAULT).

Parameters:

clazz - The calling test class. It is used in order to compute the approved files’ names.

Approvals

public Approvals(java.lang.Class<?> clazz,
                 Reporter reporter)

Constructs an Approvals object.

Parameters:

clazz - The calling test class. It is used in order to compute the approved files’ names.

reporter - The Reporter to trigger in case of differences between the output and an approved file’s content.

Method Detail

verify

public void verify(java.lang.Object output)

Compares the actual output of your program (the function’s argument) and the content of the approved file matching with the test method.

It’ll use a temporary received file to store the output of your program. This file will be erased in case the results are matching. Otherwise, it will be kept for you to review it.

In case of differences found in the output, the Reporter linked to this Approvals instance will be called (Reporter.mismatch(Path, Path)).

Parameters:

output - Any object with a Object.toString() representation containing the output of your program. It will be compared to the associated approved file.

Throws:

java.lang.AssertionError - if the Reporter implementation relies on standard assertions provided by a framework like JUnit

java.lang.RuntimeException - if the Reporter relies on executing an external command which failed

verify

public void verify(java.lang.Object output,
                   java.lang.String methodName)

Compares the actual output of your program (the function’s argument) and the content of the approved file matching with the test method.

It’ll use a temporary received file to store the output of your program. This file will be erased in case the results are matching. Otherwise, it will be kept for you to review it.

In case of differences found in the output, the Reporter linked to this Approvals instance will be called (Reporter.mismatch(Path, Path)).

This method is useful for non Java test frameworks (ScalaTest, KotlinTest …) where methodName cannot be inferred from the stack.

Parameters:

output - Any object with a Object.toString() representation containing the output of your program. It will be compared to the associated approved file.

methodName - specifies the caller method name, which is used to name the approved and received files.

Throws:

java.lang.AssertionError - if the Reporter implementation relies on standard assertions provided by a framework like JUnit

java.lang.RuntimeException - if the Reporter relies on executing an external command which failed

verifyAgainstMasterFolder

public void verifyAgainstMasterFolder(java.nio.file.Path actualFolder)