Options

Introduction

There are many things you might want to tweak with Approval Tests. Options is the entry-point for many of the changes. It is on all verify() methods, as an optional parameter.

Note: If you are interested in why we moved from “optional Reporter arguments” to “optional Options arguments”, see Why We Are Converting To Options.

Fluent Interface

Options utilizes a fluent interface, allowing you to chain together commands. Each returned object is a new copy.

ApprovalTests::Options()
    .withReporter(ApprovalTests::QuietReporter())
    .withScrubber(ApprovalTests::Scrubbers::scrubGuid)
    .fileOptions().withFileExtension(".json")

(See snippet source)

Reporters

Reporters launch diff tools upon failure. There are two ways to set a Reporter.

Pass in a Reporter object to the Options constructor, for example:

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

(See snippet source)

Call .withReporter() on an existing Options object, for example:

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

(See snippet source)

Scrubbers

Scrubbers clean output to help remove inconsistent pieces of text, such as dates. There are two ways to set a Scrubber.

Pass in a function pointer to the Options constructor, for example:

using namespace ApprovalTests;
Approvals::verifyAll("IDs", v, Options(Scrubbers::scrubGuid));

(See snippet source)

Call .withScrubber() with a function pointer, for example:

using namespace ApprovalTests;
Approvals::verifyAll("IDs", v, Options().withScrubber(Scrubbers::scrubGuid));

(See snippet source)

File Options

The Options::FileOptions class exists to customise the .approved and .received files in various ways.

For now, it just controls the file extension.

File Extensions

If you want to change the file extension of both the approved and received files, use withFileExtension().

using namespace ApprovalTests;

Approvals::verify("text to be verified",
                  Options().fileOptions().withFileExtension(".xyz"));

(See snippet source)

Note: withFileExtension() returns an Options object, so it’s possible to keep appending more with...() calls.

Defaults

The default constructor for Options does:

no scrubbing
uses file extension .txt
uses whatever is currently set as the default reporter.

Adding to Existing Options object

Because of the fluent options, you can modify a specific option from an existing Options object, while retaining all other settings, and not changing the original object.

verifyWithQuietReporter(std::string text, const Options& o)
{
    Approvals::verify(text, o.withReporter(QuietReporter());
}