Skip to content

Files

101 lines (75 loc) · 4.83 KB

ConfigureReporters.md

File metadata and controls

101 lines (75 loc) · 4.83 KB

How to Configure a Reporter

Contents

Problem Statement

Reporters are the part of Approval Tests that launch diff tools when things do not match. The can also do other things. On this page we show you three different ways to configure which reporters are used.

Principle of Least Surprise

Because there are a few different ways to configure a reporter in Approval Tests, if you are using multiple methods to configure a reporter (this is very common) you may wonder;

Which configuration will be used?

ApprovalTests uses the method of Principle of Least Surprise. This means the reporter used is the one declared closest to the test. Below are three different options in order, starting with the least surprising.

Method 1: Via Options

All the verify functions have an overload that takes an Options parameter. You can configure the reporter via the Options like such:

Options options = new Options().withReporter(BeyondCompareReporter.INSTANCE);
Approvals.verify(objectUnderTest, options);

snippet source | anchor

Method 2: Class and Method Level Annotations

At both the class and method level you can use the @UseReporter attribute to set 1 or multiple reporters.

Single Reporter

@UseReporter(DiffMergeReporter.class)

snippet source | anchor

Multiple Reporters

@UseReporter({DiffReporter.class, ClipboardReporter.class})

snippet source | anchor

Note: If you use multiple reporters ALL of them will report. Not just the first one.

Method 3: Package Level

You can also assign a default for an entire package (and all sub-packages) by creating a PackageSettings class. Here is an example

public class PackageSettings
{
  public static TkDiffReporter   UseReporter         = TkDiffReporter.INSTANCE;
  public static CountingReporter FrontloadedReporter = new CountingReporter();
}

snippet source | anchor

You can find out more about Package Level settings here

Method 4: Environment Variables

Lastly, it is possible to set the APPROVAL_TESTS_USE_REPORTER environment variable to influence the reporters. Setting a reporter through the environment overrides all other reporters - so use this sparingly and only to change reporter behaviour for individual runs or on individual machines.

The environment variable can take any combination of the following values. Multiple values should be separated by a comma, without whitespace.

snippets: EnvironmentVariableReporterTest.testValidEnvironmentalValues.approved.txt

For example, setting APPROVAL_TESTS_USE_REPORTER=AutoApproveReporter allows you to approve all pending changes at once without modifying the source code and rebuilding the code to temporarily choose a different reporter. Similarly, setting APPROVAL_TESTS_USE_REPORTER=MeldMergeReporter allows you to explicitly choose a reporter you want to use locally, without influencing the default reporter priorities and setup for fellow developers.

See Also: Reporters