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 method printWith(Printer) to customize that. By default, the value's toString method will be called.

E.g. approve(result).printWith(objectPrinter()).byFile(); prints the given object using the given ObjectPrinter.

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(Function) 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 originalValue)	Creates a new builder for the given value.
void	by(Function<String,ApprovalResult> approver)	Approves the receivedValue by the given approver.
void	byFile()	Approves the receivedValue by a FileApprover, using a nextToTest PathProviderBuilder, and the used Printer's filenameExtension.
void	byFile(String approvedPath)	Approves the receivedValue by a FileApprover with an PathProviderBuilder.approvedPath(Path) with the given path to the approved file.
void	byFile(Path approvedPath)	Approves the receivedValue by a FileApprover with an PathProviderBuilder.approvedPath(Path) with the given Path to the approved file.
void	byFile(PathProvider pathProvider)	Approves the receivedValue by a FileApprover with the given PathProvider.
void	byFile(PathProviderBuilder pathProviderBuilder)	Approves the receivedValue by a FileApprover with the given PathProviderBuilder.
void	byValue(String previouslyApproved)	Approves the value by an InplaceApprover with the given previouslyApproved value.
ApprovalBuilder<T>	named(String name)	Sets a name for the current approval.
ApprovalBuilder<String>	print()	Uses the default Printer to convert the receivedValue to a String.
ApprovalBuilder<String>	printWith(Function<T,String> printer)	Uses the given Function to convert the receivedValue to a String.
ApprovalBuilder<String>	printWith(Printer<T> printer)	Uses the given Printer to convert the receivedValue to a String.
ApprovalBuilder<T>	reviewWith(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>	reviewWith(FileReviewer reviewer)	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 receivedValue.

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 originalValue)

Creates a new builder for the given value.

Type Parameters:

T - the type of the value to approve

Parameters:

originalValue - 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:

this

printWith

public ApprovalBuilder<String> printWith(Function<T,String> printer)

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

Parameters:

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

Returns:

a new ApprovalBuilder with the printed value

printWith

public ApprovalBuilder<String> printWith(Printer<T> printer)

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

Parameters:

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

Returns:

a new ApprovalBuilder with the printed value

print

public ApprovalBuilder<String> print()

Uses the default Printer to convert the receivedValue to a String.

Returns:

a new ApprovalBuilder with the printed value

See Also:

• Configuration.defaultPrinter()
• printWith(Printer)

scrubbedOf

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

Applies the given scrubber to the current receivedValue.

Parameters:

scrubber - the UnaryOperator or Scrubber

Returns:

this

reviewWith

public ApprovalBuilder<T> reviewWith(FileReviewer reviewer)

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

Parameters:

reviewer - the FileReviewer to be used

Returns:

this

See Also:

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

reviewWith

public ApprovalBuilder<T> reviewWith(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:

this

See Also:

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

by

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

Approves the receivedValue by the given approver.

If necessary the receivedValue is printed using the Configuration.defaultPrinter().

Parameters:

approver - a Function or an Approver implementation

Throws:

ApprovalError - if the approval fails

byValue

public void byValue(String previouslyApproved)

Approves the value by an InplaceApprover with the given previouslyApproved value.

Parameters:

previouslyApproved - the approved value

byFile

public void byFile(PathProvider pathProvider)

Approves the receivedValue by a FileApprover with 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(PathProviderBuilder pathProviderBuilder)

Approves the receivedValue by a FileApprover with the given PathProviderBuilder.

Parameters:

pathProviderBuilder - 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 FileApprover, using a nextToTest PathProviderBuilder, and the used Printer's filenameExtension.

Throws:

ApprovalError - if the approval fails

byFile

public void byFile(Path approvedPath)

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

Note: the Printer'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 FileApprover with an PathProviderBuilder.approvedPath(Path) with the given path to the approved file.

Note: the Printer's filenameExtension is ignored.

Parameters:

approvedPath - the path to the approved file

Throws:

ApprovalError - if the approval fails