How to Submit a New Reporter to ApprovalTests

This guide is for figuring out how to make a more robust custom reporter, that you might want to submit back to us as a Pull Request.

For creating the ability to use a custom reporter that works on your machine, see How to Use A Custom Reporter

Adding a new Mac reporter

By way of an example, for supporting a new Reporter on macOS, the steps are:

Implement the reporter

Edit ApprovalTests/reporters/DiffPrograms.h

  • Add a declaration for the new function to the Mac namespace.

  • If you are adding a tool that is already supported on an existing platform, please try to be consistent with naming.

DiffInfo ARAXIS_MERGE();

(See snippet source)

Edit ApprovalTests/reporters/DiffPrograms.cpp

  • Add a new APPROVAL_TESTS_MACROS_ENTRY value to the Mac namespace, to create the definition for the new function.

APPROVAL_TESTS_MACROS_ENTRY(
    ARAXIS_MERGE,
    DiffInfo("/Applications/Araxis Merge.app/Contents/Utilities/compare",
             Type::TEXT_AND_IMAGE))

(See snippet source)

Edit ApprovalTests/reporters/MacReporters.h

  • Add a declaration for the new reporter.

  • In the most common case, this will be a new implementation of GenericDiffReporter

class AraxisMergeReporter : public GenericDiffReporter
{
public:
    AraxisMergeReporter();
};

(See snippet source)

Edit ApprovalTests/reporters/MacReporters.cpp

  • Add a definition for the new reporter.

  • This will use the APPROVAL_TESTS_MACROS_ENTRY you added in the first step.

AraxisMergeReporter::AraxisMergeReporter()
    : GenericDiffReporter(DiffPrograms::Mac::ARAXIS_MERGE())
{
}

(See snippet source)

  • Scroll to the end of this file, and add an instance of the new reporter class to the MacDiffReporter

    • The reporters are searched in order, so more commonly-used or highly-featured ones should go nearer the start.

    • Paid-for ones should go before free ones.

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

(See snippet source)

Other files to edit

Edit ApprovalTests/reporters/ReporterFactory.cpp

  • Add a new APPROVAL_TESTS_REGISTER_REPORTER line, for your reporter class.

APPROVAL_TESTS_REGISTER_REPORTER(Mac::AraxisMergeReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::BeyondCompareReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::DiffMergeReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::KaleidoscopeReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::P4MergeReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::SublimeMergeReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::KDiff3Reporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::TkDiffReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::VisualStudioCodeReporter);
APPROVAL_TESTS_REGISTER_REPORTER(Mac::CLionDiffReporter);

(See snippet source)

Edit tests/DocTest_Tests/reporters/CommandLineReporterTests.cpp

  • Add an instance of the new Reporter class

// Mac
std::make_shared<Mac::AraxisMergeReporter>(),
std::make_shared<Mac::BeyondCompareReporter>(),
std::make_shared<Mac::DiffMergeReporter>(),
std::make_shared<Mac::KaleidoscopeReporter>(),
std::make_shared<Mac::P4MergeReporter>(),
std::make_shared<Mac::SublimeMergeReporter>(),
std::make_shared<Mac::KDiff3Reporter>(),
std::make_shared<Mac::TkDiffReporter>(),
std::make_shared<Mac::VisualStudioCodeReporter>(),
std::make_shared<Mac::CLionDiffReporter>(),

(See snippet source)

  • Run this test, review and accept the changes.

Adding a new Windows reporter

The steps are the same as above, except that in the second step, you will edit:

Adding a new Linux reporter

The steps are the same as above, except that in the second step, you will edit:

Adding a new Cross Platform reporter

To add a reporter that will run on all 3 platforms, the steps are the same as above, except that in the second step, you will edit: