README.md

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, with easier navigation, search and a PDF download.

---

Contents: Getting Started | Test Frameworks | Writing Tests | Customising Behaviour | Common Challenges | How-to Guides | Build Systems | Extras | Troubleshooting | Developing ApprovalTests.cpp | C++ Reference

---

Getting Started

If you are new to Approval Tests, or to this C++ library, start here:

• Concepts: Overview | ApprovalTesting (the concept) | The Path to Approval Testing
• Start coding: Tutorial | Setup Options | Choosing a test framework | Approving Results

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 | Catch2 | CppUTest | doctest | Google Tests | [Boost].ut
• Extending test framework support: Supporting a new test framework

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 | Containers | Combinations of containers | Testing Exceptions
• Good Practice: String conversions | Tips for Designing Strings

Customising Behaviour

• Principles: Options | Disposable Objects
• Customisation points: Reporters | Comparators | Writers | Namers | Scrubbers | Configuring Approval Tests
• Summary: All Customizations of Approval Tests

Common Challenges

• Challenges: Multiple output files per test

How-to Guides

• Writing Tests:
  • How to Test the Contents of a Container
  • How to Test a Variety of Values for One Input
  • How to Scrub Non-Deterministic Output
  • How to Use the Fmt Library To Print Objects
• Reporters:
  • How to Use A Custom Reporter
  • How to Select a Reporter with an Environment Variable
  • How to Submit a New Reporter to ApprovalTests
• Others:
  • How to Toggle Enabling or Disabling of Deprecated Code

Build Systems

• Integrations: CMake | Conan | Vcpkg
• Your builds: Build Machines and CI servers

Extras

• Various: Features | Why We Are Converting To Options | FAQs | Glossary | Utilities | Videos

Troubleshooting

• Topics: Troubleshooting | Misconfigured Builds | Misconfigured main()

Developing ApprovalTests.cpp

• Topics: Contributing to ApprovalTests.cpp | Coding Patterns | Maintaining the Docs | Building the Docs

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.

• Fundamentals: Approving Objects | Core Classes | Scrubber Functions