Reporters.md

Reporters

Contents

• Supported Diff Tools
  • Mac
  • Linux
  • Windows
• Cross-platform
• Registering a default reporter
• Front Loaded Reporters
  • Blocking Reporters
• Miscellaneous Helper Reporters
  • Auto-approving
• Related Pages

Supported Diff Tools

The DiffReporter class goes through a chain of possible reporters to find the first option installed on your system. Currently the search goes in this order:

Mac

new AraxisMergeReporter(),
new BeyondCompareReporter(),
new DiffMergeReporter(),
new KaleidoscopeReporter(),
new P4MergeReporter(),
new SublimeMergeReporter(),
new KDiff3Reporter(),
new TkDiffReporter(),
new VisualStudioCodeReporter(),
new CLionDiffReporter()

^{snippet source | anchor}

Linux

new BeyondCompareReporter(),
new MeldReporter(),
new SublimeMergeReporter(),
new KDiff3Reporter()

^{snippet source | anchor}

Windows

new TortoiseDiffReporter(), // Note that this uses Tortoise SVN Diff
new TortoiseGitDiffReporter(),
new BeyondCompareReporter(),
new WinMergeReporter(),
new AraxisMergeReporter(),
new CodeCompareReporter(),
new SublimeMergeReporter(),
new KDiff3Reporter(),
new VisualStudioCodeReporter(),

^{snippet source | anchor}

Cross-platform

These are all based on the diff tool being in the PATH.

new VisualStudioCodeReporter(),

^{snippet source | anchor}

Registering a default reporter

At present, the default Reporter is the DiffReporter. Whenever you call Approvals, you have the chance to pass in your own Reporter. However, if you would like to change what the default reporter is when you don't pass in a specific Reporter, you can do this at a global or per-test level, by adding the line:

// main.cpp:
#include <memory>
auto defaultReporterDisposer = ApprovalTests::Approvals::useAsDefaultReporter(
    std::make_shared<ApprovalTests::DiffReporter>());

^{snippet source | anchor}

The return value is "Disposable", meaning it will restore the original reporter when the object destructs. Because of this, if you do not store the result in a variable, it will immediately undo itself by the end of the line.

Front Loaded Reporters

By default, Approval tests will not launch any reporters on supported CI machines. To do this, we use front loaded reporters...

Front loaded reporters allow you to block all normal reporting behaviour. This is useful in situations like running on a CI Machine, where you wouldn't want a reporter to open.

For more information, see Build Machines and Continuous Integration servers.

Here is an example of not launching any reporters if you are on a machine with a particular name, by using BlockingReporter.

// main.cpp
auto frontLoadedReportDisposer = ApprovalTests::Approvals::useAsFrontLoadedReporter(
    ApprovalTests::BlockingReporter::onMachineNamed("MyCIMachineName"));

^{snippet source | anchor}

Once you have added that, even calling approvals with a specific Reporter will not launch it on the CI system (but will for all other systems). For example:

using namespace ApprovalTests;
Approvals::verify("text to be verified", Options(Windows::AraxisMergeReporter()));

^{snippet source | anchor}

Blocking Reporters

Blocking reporters are a simple class, designed for use with FrontLoadedReporters, to prevent launching of reporters in certain environments.

// main.cpp
auto frontLoadedReportDisposer = ApprovalTests::Approvals::useAsFrontLoadedReporter(
    ApprovalTests::BlockingReporter::onMachineNamed("MyCIMachineName"));

^{snippet source | anchor}

Miscellaneous Helper Reporters

While most reporters open some sort of external program, for the purpose of understanding how the tests went wrong, and verifying the correct answer, there are some reporters that are helpful for specific situations.

Auto-approving

There are three reporters that can help with the approving of single or multiple tests.

• AutoApproveIfMissingReporter: if there is no approved file already, the received file will automatically be copied over the approved one. Otherwise, it does nothing. One possible cause for confusion here is if you ran the test previously with a standard reporter, that will have created an almost-empty approved file, which will then block this from working.
• ClipboardReporter: this puts the command-line to moved the approve file on to your computer's clipboard. You then review this, and paste it in to a terminal window. This only works with one test at a time.
• AutoApproveReporter: be careful, this will overwrite every existing ".approved" file, with no confirmation. This is best used when you are expecting large numbers of files that are already version-controlled to be updated, and you would rather review the changes in your version control system.

Related Pages

• How to Use A Custom Reporter
• How to Select a Reporter with an Environment Variable
• How to Submit a New Reporter to ApprovalTests

---

Back to User Guide