Namers

The Purpose of Namers

Approvals::verify(text);

could be written as:

REQUIRE(text == (loadContentsFromFile("FileName.TestName.approved.txt"));

Part of Approval Tests’ “Convention over Configuration” is to remove this by automatically creating meaningful file names, and therefore it could be written as:

REQUIRE(text == (loadContentsFromFile(namer.getApprovedFile()));

“If you always have to do something, you should never have to do something.”

Since all of your REQUIREs would look like this, we can simplify it with the above Approvals::verify(text); - and this is enabled by the ApprovalNamers.

The Parts of Namers

The conventional layout for files saved with Approvals::verify() and related functions is:

path_to_test_file/FileName.TestName.approved.txt
path_to_test_file/FileName.TestName.received.txt

The Approval Namer is responsible for creating these two names.

The interface for this is ApprovalNamer.

Converting Test Names to Valid FileNames

Some C++ test frameworks allow test names to contain characters that are not valid in file or directory names on every operating system.

Therefore, by default, ApprovalTests will convert any non-valid filename character to an _ (underscore). This can mean "test <" and "test >" would produce colliding test__.approved.txt.

This behavior is customizable, here’s an example:

TEST_CASE("Sanitizer <3 fileNames")
{
    {
        auto disposer =
            ApprovalTests::Approvals::useFileNameSanitizer([](std::string incoming) {
                return ApprovalTests::StringUtils::replaceAll(
                    incoming, " <3 ", "_loves_");
            });

(See snippet source)

Registering a Custom Namer

Locally

If you want to use a specific namer for a specific test, the easiest way is via Options:

auto namer = ApprovalTests::TemplatedCustomNamer::create(
    "{TestSourceDirectory}/{ApprovalsSubdirectory}/CustomName.{ApprovedOrReceived}.{FileExtension}");
ApprovalTests::Approvals::verify("Hello", ApprovalTests::Options().withNamer(namer));

(See snippet source)

Globally

If you ever want to create a custom namer, that’s used in multiple places, Approval Tests has a mechanism to change which namer it uses by default. Please note that you need to create a function that creates new namers.

auto default_namer_disposer = ApprovalTests::Approvals::useAsDefaultNamer(
    []() { return std::make_shared<FakeNamer>(); });

(See snippet source)

Hint: Many namer classes have a useAsDefaultNamer() convenience method to do this for you.

Alternative Namers

TemplatedCustomNamer

The easiest way to create a custom namer is to use a TemplatedCustomNamer.

As well as giving great flexibility, this introduces the ability to run Approval Tests on machines that do not have the source code, such as when doing cross-compilation

Here is an example:

ApprovalTests::TemplatedCustomNamer namer(
    "/my/source/directory/{ApprovedOrReceived}/"
    "{TestFileName}.{TestCaseName}.{FileExtension}");

(See snippet source)

Note: The character / will be converted to \ on Windows machines, at run-time.

Supported tags

auto testSourceDirectory = "{TestSourceDirectory}";
auto relativeTestSourceDirectory = "{RelativeTestSourceDirectory}";
auto approvalsSubdirectory = "{ApprovalsSubdirectory}";
auto testFileName = "{TestFileName}";
auto testCaseName = "{TestCaseName}";
auto approvedOrReceived = "{ApprovedOrReceived}";
auto fileExtension = "{FileExtension}";

(See snippet source)

Here is some output showing examples with these tags expanded:

For template: {RelativeTestSourceDirectory}/{ApprovalsSubdirectory}/{TestFileName}.{TestCaseName}.{ApprovedOrReceived}.{FileExtension}

Result: namers/approval_tests/TemplatedCustomNamerTests.Demo_all_namer_templates.approved.txt

With breakdown:
RelativeTestSourceDirectory = namers/
ApprovalsSubdirectory       = approval_tests/
TestFileName                = TemplatedCustomNamerTests
TestCaseName                = Demo_all_namer_templates
ApprovedOrReceived          = approved
FileExtension               = txt

Also available:
{TestSourceDirectory} = <full path to sources>/ApprovalTests.cpp/tests/DocTest_Tests/namers/

(See snippet source)

Examples

If you would like to see an example of this running for scenarios where the execution is in a separate environment from the compilation, check out our out_of_source example.

SeparateApprovedAndReceivedDirectoriesNamer

The pattern used by this class for file names is:

auto path = "{TestSourceDirectory}/{ApprovalsSubdirectory}/{ApprovedOrReceived}/{TestFileName}.{TestCaseName}.{FileExtension}";

(See snippet source)

Which results in these file names:

./approved/{TestFileName}.{TestCaseName}.{FileExtension}
./received/{TestFileName}.{TestCaseName}.{FileExtension}

This layout enables you to use Beyond Compare 4 (or any other directory comparison tool) to do a folder/directory comparison, in order to compare pairs of files in the approved/ and received/ directories, and approve one or more files by copying them (without renaming) from received/ to approved/.

The approved/ and received/ directories are created automatically.

To register this as your default namer, use:

auto default_namer_disposer =
    ApprovalTests::SeparateApprovedAndReceivedDirectoriesNamer::useAsDefaultNamer();

(See snippet source)

When using this namer, you will want to add the following line to your .gitignore file:

**/received/

Approving multiple files from one test

See MultipleOutputFilesPerTest.