Using Approval Tests With Google Tests

Introduction

The Google Test test framework works well with Approval Tests.

This section describes the various ways of using Approval Tests with Google Test.

Notes pre-v.10.8.0:

Earlier versions of Approval Tests had issues with Ninja. Read more at Troubleshooting Misconfigured Build.

Getting Started With Google Test

Starter Project

We haven’t yet provided a Starter Project for using Approval Tests with Google Tests.

This is partly based on the assumption that anyone already using Google Tests will have their own project set up, and anyone else would probably use Catch2 instead.

If it would be helpful for us to such a Starter Project, please let us know, via the contact details in Contributing to ApprovalTests.cpp.

New Project

Create a file main.cpp and add just the following two lines:

// main.cpp:
#define APPROVALS_GOOGLETEST // This tells Approval Tests to provide a main() - only do this in one cpp file
#include "ApprovalTests.hpp"

(See snippet source)

Existing Project - no main()

Google Test has a gtest_main library that provides a main() function, and then runs all your tests.

If your existing Google Test application uses the gtest_main library, Approval Tests will not be able to obtain the names to use output files. You will then see the help message shown in Troubleshooting.

To fix this, please add a new main.cpp, as shown in the previous section.

Existing Project - with your main()

If you have an existing Google Test-based test program that provides its own main(), you won’t be able to use the approach above.

Instead, you should make the following additions to your own source file that contains main().

// main.cpp:

// 1. Add these two lines to your main:
#define APPROVALS_GOOGLETEST_EXISTING_MAIN
#include "ApprovalTests.hpp"

int main(int argc, char** argv)
{
    ::testing::InitGoogleTest(&argc, argv);

    // 2. Add this line to your main:
    ApprovalTests::initializeApprovalTestsForGoogleTests();

    return RUN_ALL_TESTS();
}

(See snippet source)

Customizing Google Tests Approval File Names

Most testing frameworks have two pieces of naming information: SourceFileName and TestName.

Google Tests has an additional piece of information: TestCaseName.

TEST(TestCaseName, TestName)

(See snippet source)

With Google Tests, this will result in Approvals creating output files beginning with:

SourceFileName.TestCaseName.TestName

Very often, the SourceFileName and the TestCaseName are redundant, meaning that what you would like is:

SourceFileName.TestName

By default, Approval Tests will do this if TestCaseName is completely contained within SourceFileName, meaning it is a sub-string.

Customizing

If this is not enough, Approvals allows for customization, in two ways.

Note: to be able to add these pieces of code outside of a function, you need to hold on to the result as a variable. This variable is not used, it is only there to allow the method to execute.

Note: using these customizations inside a Google TEST or TEST_F, is too late for that test: they won’t take effect until the next executed test.

Note: this customization is permanent: it affects all tests run later in the current program run.

Note: this customization is cannot be reversed.

Custom Suffixes

For example, if you are Google test fixtures, you might have a lot of class names of the format TestClassNameFixture. You can tell Approval Tests that these are the same by adding the following to your main:

// main.cpp
auto customization =
    ApprovalTests::GoogleConfiguration::addIgnorableTestCaseNameSuffix("Fixture");

(See snippet source)

Custom Anything

If you have something more unique, you can write a function that will match if the test case name and the source file names should be considered equal.

For example, let’s say you want a special tag IgnoreThis to indicate a that a TestCaseName should be ignored, when determining the names of output files.

So:

TEST(TestCaseName_IgnoreThis, TestName)

(See snippet source)

Would produce an output file beginning with:

auto outputFileBaseName = "GoogleFixtureNamerCustomizationTests.TestName";

(See snippet source)

You could achieve this by registering a function pointer like this:

// main.cpp
bool dropTestCaseNamesWithIgnoreThis(const std::string& /*testFileNameWithExtension*/,
                                     const std::string& testCaseName)
{
    return ApprovalTests::StringUtils::contains(testCaseName, "IgnoreThis");
}

auto ignoreNames = ApprovalTests::GoogleConfiguration::addTestCaseNameRedundancyCheck(
    dropTestCaseNamesWithIgnoreThis);

(See snippet source)

Or by using a lambda like this:

// main.cpp
auto ignoreNamesLambda =
    ApprovalTests::GoogleConfiguration::addTestCaseNameRedundancyCheck(
        [](const std::string& /*testFileNameWithExtension*/,
           const std::string& testCaseName) {
            return ApprovalTests::StringUtils::contains(testCaseName, "IgnoreThis");
        });

(See snippet source)

Code to copy for your first Google Test Approvals test

Here is sample code to create your main() function, to set up Approval Tests’ Google Test integration.

We called this file googletest_starter_main.cpp:

#define APPROVALS_GOOGLETEST
#include "ApprovalTests.hpp"

// This puts "received" and "approved" files in approval_tests/ sub-directory,
// keeping the test source directory tidy:
auto directoryDisposer =
    ApprovalTests::Approvals::useApprovalsSubdirectory("approval_tests");

(See snippet source)

Here is sample code to create your first test. We called this file googletest_starter_test.cpp:

#include "gtest/gtest.h"
#include "ApprovalTests.hpp"

TEST(GoogleTestStarter, Sample)
{
    // TODO Replace 42 with the value or object whose contents you are verifying.
    // For help, see:
    // https://approvaltestscpp.readthedocs.io/en/latest/generated_docs/ToString.html
    ApprovalTests::Approvals::verify(42);
}

(See snippet source)

And finally, here is sample code to put in your CMakeLists.txt file:

set(EXE_NAME googletest_starter)
set(CMAKE_CXX_STANDARD 11)
add_executable(${EXE_NAME}
        googletest_starter_main.cpp
        googletest_starter_test.cpp
        )
target_link_libraries(${EXE_NAME} ApprovalTests::ApprovalTests gtest gtest_main)

add_test(NAME ${EXE_NAME} COMMAND ${EXE_NAME})

(See snippet source)