<a id="top"></a> # ApprovalTests for C++ **ApprovalTests.cpp** is a C++ implementation of Approval Tests. Also known as Golden Master Tests or Snapshot Testing, Approval Tests are an alternative to asserts. They are great for testing objects with lots of fields, or lists of objects. **Note:** This User Guide is [**also available on Read the Docs**](https://approvaltestscpp.readthedocs.io/en/latest/), with easier navigation, search and a [PDF download](https://approvaltestscpp.readthedocs.io/_/downloads/en/latest/pdf/). ---- <!-- NOTE: This list needs to be updated by hand if new sections are added --> *Contents: [Getting Started](#getting-started) | [Test Frameworks](#test-frameworks) | [Writing Tests](#writing-tests) | [Customising Behaviour](#customising-behaviour) | [Common Challenges](#common-challenges) | [How-to Guides](#how-to-guides) | [Build Systems](#build-systems) | [Extras](#extras) | [Troubleshooting](#troubleshooting) | [Developing ApprovalTests.cpp](#developing-approvaltestscpp) | [C++ Reference](#c-reference)* ---- ## Getting Started If you are new to Approval Tests, or to this C++ library, start here: - **Concepts**: [Overview](/doc/Overview.md#top) | [ApprovalTesting (the concept)](/doc/ApprovalTestingConcept.md#top) | [The Path to Approval Testing](/doc/PathToApprovalTesting.md#top) | [Approval Testing Concepts](https://github.com/approvals/ApprovalTests.Documentation/blob/main/explanations/approval_testing.md#top) | [Place to modify output](https://github.com/approvals/ApprovalTests.Documentation/blob/main/explanations/creating_output.md#top) | [What are Approvals](https://github.com/approvals/ApprovalTests.Documentation/blob/main/explanations/what_are_approvals.md#top) | [Benifits of Different Reporters](https://github.com/approvals/ApprovalTests.Documentation/blob/main/explanations/benefits_of_different_reporters.md#top) - **Start coding**: [Tutorial](/doc/Tutorial.md#top) | [Setup Options](/doc/Setup.md#top) | [Choosing a test framework](/doc/GettingStarted.md#top) | [Approving Results](/doc/ApprovingResults.md#top) ## Test Frameworks Approval Tests uses a test framework, in order to find out the names of tests and of source files. The test framework will also report errors for any failed Approval Tests. - **Using Approval Tests with**: [Boost.Test](/doc/UsingBoostTest.md#top) | [Catch2](/doc/UsingCatch.md#top) | [CppUTest](/doc/UsingCppUTest.md#top) | [doctest](/doc/UsingDoctest.md#top) | [Google Tests](/doc/UsingGoogleTests.md#top) | [\[Boost\].ut](/doc/UsingUT.md#top) - **Extending test framework support**: [Supporting a new test framework](/doc/SupportingNewTestFramework.md#top) ## Writing Tests Now that you are set up to run Approval Tests, this section describes how to test various types of complex objects, and how to do so effectively. - **How to Test**: [Single Objects](/doc/TestingSingleObjects.md#top) | [Containers](/doc/TestingContainers.md#top) | [Combinations of containers](/doc/TestingCombinations.md#top) | [Testing Exceptions](/doc/TestingExceptions.md#top) - **Good Practice**: [String conversions](/doc/ToString.md#top) | [Tips for Designing Strings](/doc/explanations/TipsForDesigningStrings.md#top) ## Customising Behaviour - **Principles**: [Options](/doc/Options.md#top) | [Disposable Objects](/doc/DisposableObjects.md#top) - **Customisation points**: [Reporters](/doc/Reporters.md#top) | [Comparators](/doc/CustomComparators.md#top) | [Writers](/doc/Writers.md#top) | [Namers](/doc/Namers.md#top) | [Scrubbers](/doc/explanations/Scrubbers.md#top) | [Configuring Approval Tests](/doc/Configuration.md#top) - **Summary**: [All Customizations of Approval Tests](/doc/AllCustomizations.md#top) ## Common Challenges - **Challenges**: [Multiple output files per test](/doc/MultipleOutputFilesPerTest.md#top) ## How-to Guides - **Writing Tests**: - [How to Test the Contents of a Container](/doc/how_tos/TestContainerContents.md#top) - [How to Test a Variety of Values for One Input](/doc/how_tos/TestAVarietyOfValues.md#top) - [How to Scrub Non-Deterministic Output](/doc/how_tos/ScrubNonDeterministicOutput.md#top) - [How to Use the Fmt Library To Print Objects](/doc/how_tos/UseTheFmtLibraryToPrintObjects.md#top) - **Reporters**: - [How to Use A Custom Reporter](/doc/how_tos/UseACustomReporter.md#top) - [How to Select a Reporter with an Environment Variable](/doc/how_tos/SelectReporterWithEnvironmentVariable.md#top) - [How to Submit a New Reporter to ApprovalTests](/doc/how_tos/SubmitANewReporterToApprovalTests.md#top) - **Others**: - [How to Toggle Enabling or Disabling of Deprecated Code](/doc/how_tos/ToggleDeprecatedCode.md#top) ## Build Systems - **Integrations**: [CMake](/doc/CMakeIntegration.md#top) | [Conan](/doc/ConanIntegration.md#top) | [Vcpkg](/doc/VcpkgIntegration.md#top) - **Installation**: [Installation Via CMake](/doc/how_tos/InstallApprovalTestsUsingCMake.md#top) - **Your builds**: [Build Machines and CI servers](/doc/BuildMachinesAndCI.md#top) ## Extras - **Various**: [Features](/doc/Features.md#top) | [Why We Are Converting To Options](/doc/explanations/WhyWeAreConvertingToOptions.md#top) | [FAQs](/doc/FAQ.md#top) | [Glossary](/doc/Glossary.md#top) | [Utilities](/doc/Utilities.md#top) | [Videos](/doc/Videos.md#top) ## Troubleshooting - **Topics**: [Troubleshooting](/doc/Troubleshooting.md#top) | [Misconfigured Builds](/doc/TroubleshootingMisconfiguredBuild.md#top) | [Misconfigured main()](/doc/TroubleshootingMisconfiguredMain.md#top) ## Developing ApprovalTests.cpp - **Topics**: [Contributing to ApprovalTests.cpp](/doc/Contributing.md#top) | [Coding Patterns](/doc/CodingPatterns.md#top) | [Maintaining the Docs](/doc/MaintainingDocumentation.md#top) | [Building the Docs](/doc/BuildingDocumentation.md#top) ## C++ Reference This section contains a growing list of "Read the Docs" pages documenting the ApprovalTests.cpp API. It may be useful to see what methods, and overloads, are available. It is very short on descriptive text, as we focus our efforts on the documentation above. <!-- NOTE: This list needs to be updated by hand if new pages are added --> - **Fundamentals**: [Approving Objects](https://approvaltestscpp.readthedocs.io/en/latest/api/approving.html) | [Core Classes](https://approvaltestscpp.readthedocs.io/en/latest/api/core.html) | [Scrubber Functions](https://approvaltestscpp.readthedocs.io/en/latest/api/scrubbers.html)