Supporting a new test framework
Introduction
ApprovalTests.cpp is designed to work with multiple C++ test frameworks.
If your test framework is not already supported, this section offers help to add that support.
Test Framework Requirements
ApprovalTests.cpp can be made to work with any test framework that supplies the following:
The current test’s name
The current test’s full source file path (with correct case of filename)
Ability to report unexpected exceptions as test failures, including reporting the text in
exception.what()
, and ideally also the exception type.Ability to return a non-zero exit status from the test program if there were any unexpected exceptions.
Steps to add support
Provide some code to add to the test’s
main()
function, to listen out for the running of test casesGive that code a
TestName
instance, that will store information about the test being executedAs each test case starts, update the
TestName
instance with details of the source file name, and test case nameAdd a call to
ApprovalTests::FrameworkIntegrations::setTestPassedNotification()
so that the test framework is aware that a check has been executedIdeally, provide a mechanism (such as a macro) that makes it easy for users to use this code in their own tests
Examples
This is perhaps best understood by reviewing the implementations for frameworks that are already supported - see /ApprovalTests/integrations/.
Adding new framework to documentation
Add a new file about the customisation, such as UsingCatch.md
Record the new framework support in:
The
getMisconfiguredMainHelp()
help message in HelpMessages.cppREADME.md - see the links to supported test frameworks in the “Requirements” section
GettingStarted.md - see “Choosing a testing framework”
Setup.md - see the bullet list starting “Set up your
main()
”Other documentation links: see Definition of Done
Update Package Managers
Optionally, if the new library is supported by Conan, then update the ApprovalTests.cpp conan-center-index to add support for the new integration.