- Introduction
- Getting Started With Google Test
- Customizing Google Tests Approval File Names
- Code to copy for your first Google Test Approvals test
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.
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.
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"
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.
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();
}
Most testing frameworks have two pieces of naming information: SourceFileName
and TestName
.
Google Tests has an additional piece of information: TestCaseName
.
TEST(TestCaseName, TestName)
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.
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.
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");
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)
Would produce an output file beginning with:
auto outputFileBaseName = "GoogleFixtureNamerCustomizationTests.TestName";
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);
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");
});
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");
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);
}
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})