ConfigureReporters.md

How to Configure a Reporter

Contents

• Problem Statement
• Principle of Least Surprise
  • Method 1: Via Options
  • Method 2: Class and Method Level Annotations
    • Single Reporter
  • Method 3: Package Level
  • Method 4: Environment Variables

Problem Statement

Reporters are the part of Approval Tests that launch diff tools when things do not match. 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(ReportWithBeyondCompare.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(ReportWithDiffMerge.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 ReportWithTkDiffMac UseReporter         = ReportWithTkDiffMac.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.

AraxisMergeReporter
AutoApproveReporter
AutoApproveWhenEmptyReporter
BeyondCompareReporter
ClipboardReporter
CodeCompareReporter
DelayedClipboardReporter
DiffMergeReporter
DiffReporter
FileCaptureReporter
ImageReporter
ImageWebReporter
IntelliJReporter
JunitReporter
KDiff3Reporter
KaleidoscopeDiffReporter
MeldMergeReporter
P4MergeReporter
PitReporter
QuietReporter
TestNgReporter
TextWebReporter
TkDiffReporter
TortoiseDiffReporter
VisualStudioCodeReporter
WinMergeReporter
WindowsDiffReporter

^{snippet source | anchor}

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