UsingGoogleTests.md

Using Approval Tests With Google Tests

Contents

• Getting Started With Google Test
  • Starter Project
  • New Project
  • Existing Project - no main()
  • Existing Project - with your main()
• Customizing Google Tests Approval File Names
  • Customizing
    • Custom Suffixes
    • Custom Anything

Getting Started With Google Test

The Google Test test framework works well with Approval Tests.

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

Note: Approval Tests has some specific build requirements if it is built with the Ninja build generator. If you use Ninja with Approval Tests, special care is needed when setting up builds, to avoid compilation errors or test failures. If you have any problems with this, please see Troubleshooting Misconfigured Build.

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"

^{snippet source | anchor}

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();
}

^{snippet source | anchor}

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)

^{snippet source | anchor}

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 =
    GoogleConfiguration::addIgnorableTestCaseNameSuffix("Fixture");

^{snippet source | anchor}

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)

^{snippet source | anchor}

Would produce an output file beginning with:

auto outputFileBaseName = "GoogleFixtureNamerCustomizationTests.TestName";

^{snippet source | anchor}

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

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

auto ignoreNames = GoogleConfiguration::addTestCaseNameRedundancyCheck(
    dropTestCaseNamesWithIgnoreThis);

^{snippet source | anchor}

Or by using a lambda like this:

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

^{snippet source | anchor}

---

Back to User Guide