Package org.approvej

Class ApprovalBuilder<T>

java.lang.Object

org.approvej.ApprovalBuilder<T>

Type Parameters:

T - the type of the value to approve

@NullMarked
public class ApprovalBuilder<T>
extends Object

A builder to configure an approval for a given value.

E.g. approve(result).byFile(); will approve the result with the content of a file next to the test.

Printing

Before approval, the value needs to be printed (turned into a String). You can use the methods printedAs(PrintFormat) or printedBy(Function) to customize that. By default, the value's toString method will be called.

E.g. approve(result).printAs(multiLineString()).byFile(); prints the given object using the given MultiLineStringPrintFormat.

Scrubbing

The value can also be scrubbed of dynamic data (like timestamps or ID's).

E.g. approve(result).scrubbedOf(uuids()).byFile(); will replace all UUID's in the result before approval.

Approving

The builder is concluded by specifying an approver to approve the value by (byFile() and byValue(String)).

E.g. approve(result).byFile(); approves the result with the content of a file next to the test, while approve(result).byValue(approved); approves the result with the given approved value.

Method Summary

Modifier and Type	Method	Description
static <T> ApprovalBuilder<T>	approve(T value)	Creates a new builder for the given value.
void	by(Function<String,ApprovalResult> approver)	Approves the value by the given approver.
void	byFile()	Approves the receivedValue by a file, using a nextToTest PathProvider, and the used PrintFormat's filenameExtension.
void	byFile(String approvedPath)	Approves the receivedValue by a Approver with an PathProviders.approvedPath(Path) with the given path String to the approved file.
void	byFile(Path approvedPath)	Approves the receivedValue by a file with an PathProviders.approvedPath(Path) with the given Path to the approved file.
void	byFile(PathProvider pathProvider)	Approves the receivedValue by a file defined by the given PathProvider.
void	byValue(String previouslyApproved)	Approves the value by the given previouslyApproved value.
ApprovalBuilder<T>	named(String name)	Sets a name for the current approval.
ApprovalBuilder<String>	printed()	Uses the default PrintFormat to convert the value to a String.
ApprovalBuilder<String>	printedAs(PrintFormat<? super T> printFormat)	Uses the given Printer to convert the value to a String.
ApprovalBuilder<String>	printedBy(Function<? super T,String> printer)	Uses the given Function to convert the value to a String.
ApprovalBuilder<T>	reviewedBy(String script)	Creates a FileReviewerScript from the given script String to trigger if the received value is not equal to the previously approved.
ApprovalBuilder<T>	reviewedBy(FileReviewer fileReviewer)	Sets the given FileReviewer to trigger if the received value is not equal to the previously approved.
ApprovalBuilder<T>	scrubbedOf(UnaryOperator<T> scrubber)	Applies the given scrubber to the current value.

Methods inherited from class java.lang.Object

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

Method Details

approve

public static <T> ApprovalBuilder<T> approve(T value)

Creates a new builder for the given value.

Type Parameters:

T - the type of the value to approve

Parameters:

value - the value to approve

Returns:

a new ApprovalBuilder for the given value

named

public ApprovalBuilder<T> named(String name)

Sets a name for the current approval. Generally this should be used when there are multiple values in one test case are being approved byFile() as the second approval would otherwise simply overwrite the first one.

Parameters:

name - the name for the current approval

Returns:

a copy of this with the given name

printedBy

public ApprovalBuilder<String> printedBy(Function<? super T,String> printer)

Uses the given Function to convert the value to a String.

Parameters:

printer - the Function used to convert the value to a String

Returns:

a copy of this with the printed value

printedAs

public ApprovalBuilder<String> printedAs(PrintFormat<? super T> printFormat)

Uses the given Printer to convert the value to a String.

Parameters:

printFormat - the printer used to convert the value to a String

Returns:

a copy of this with the printed value

printed

public ApprovalBuilder<String> printed()

Uses the default PrintFormat to convert the value to a String.

Returns:

a copy of this with the printed value

See Also:

• Configuration.defaultPrintFormat()
• printedAs(PrintFormat)

scrubbedOf

public ApprovalBuilder<T> scrubbedOf(UnaryOperator<T> scrubber)

Applies the given scrubber to the current value.

Parameters:

scrubber - the UnaryOperator or Scrubber

Returns:

a copy of this with the scrubbed value

reviewedBy

public ApprovalBuilder<T> reviewedBy(FileReviewer fileReviewer)

Sets the given FileReviewer to trigger if the received value is not equal to the previously approved.

Parameters:

fileReviewer - the FileReviewer to be used

Returns:

a copy of this with the given fileReviewer

See Also:

• Configuration.defaultFileReviewer()
• FileReviewerScript.script()

reviewedBy

public ApprovalBuilder<T> reviewedBy(String script)

Creates a FileReviewerScript from the given script String to trigger if the received value is not equal to the previously approved.

Parameters:

script - the script String to be used as a FileReviewerScript

Returns:

a copy of this with the given script as fileReviewer

See Also:

• Configuration.defaultFileReviewer()
• FileReviewerScript.script()

by

public void by(Function<String,ApprovalResult> approver)

Approves the value by the given approver.

If necessary the value is printed using the Configuration.defaultPrintFormat().

Parameters:

approver - a Function or an Approver implementation

Throws:

ApprovalError - if the approval fails

byValue

public void byValue(String previouslyApproved)

Approves the value by the given previouslyApproved value.

Parameters:

previouslyApproved - the approved value

byFile

public void byFile(PathProvider pathProvider)

Approves the receivedValue by a file defined by the given PathProvider.

Parameters:

pathProvider - the provider for the paths of the approved and received files

Throws:

ApprovalError - if the approval fails

byFile

public void byFile()

Approves the receivedValue by a file, using a nextToTest PathProvider, and the used PrintFormat's filenameExtension.

Throws:

ApprovalError - if the approval fails

byFile

public void byFile(Path approvedPath)

Approves the receivedValue by a file with an PathProviders.approvedPath(Path) with the given Path to the approved file.

Note: the PrintFormat's filenameExtension is ignored.

Parameters:

approvedPath - the Path to the approved file

Throws:

ApprovalError - if the approval fails

byFile

public void byFile(String approvedPath)

Approves the receivedValue by a Approver with an PathProviders.approvedPath(Path) with the given path String to the approved file.

Note: the PrintFormat's filenameExtension is ignored.

Parameters:

approvedPath - the path to the approved file

Throws:

ApprovalError - if the approval fails