UsingUT.md

Using Approval Tests With [Boost].UT

Contents

• Getting Started With [Boost].UT
  • Important Note: Issue 87
  • Requirements
  • Usage examples

Getting Started With [Boost].UT

Important Note: Issue 87

• As of 2020-01-15, there is a known serious issue with using this test framework with Approval Tests, in that the test framework does not currently report any Approval Test test failures via the exit status of the test program.
• This means that any CI builds or ctest runs will look like they succeeded, whereas they may in fact not have done.
• For details and progress, please see issue 87: Boost.UT tests spuriously pass, by returning 0 exit status even after failure.

---

The [Boost].UT test framework works well with Approval Tests.

[Boost].UT is a single header/single module, macro-free μ(micro)/Unit Testing Framework that requires C++17 / C++20

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.

Requirements

Approval Tests for [Boost].UT requires that a file called the following is found:

#include <boost/ut.hpp>

^{snippet source | anchor}

It also requires:

• A C++ compiler that supports the C++ 20 std::source_location. See C++ compiler support.
• A build that enables C++20 - for example, with: set(CMAKE_CXX_STANDARD 20)
• A [Boost].UT version that is compatible with the version of ApprovalTests.cpp being used. See the version we test against: third_party/ut/include/boost/ut.hpp

Usage examples

Add the following two lines to your source code:

#define APPROVALS_UT
#include "ApprovalTests.hpp"

^{snippet source | anchor}

Below is an example of a call to an approval test inside a [Boost].UT test:

"ItCanVerifyAFile"_test = []() {
    Approvals::verify(
        "Approval Tests can verify text via the golden master method");
};

^{snippet source | anchor}

In the following example, two instances of ApprovalTests are called inside the same test. We need to use sections with different names, to prevent Approval Tests from using the same output file for both tests:

"ItCanUseMultipleVerify"_test = []() {
    {
        // Here we simulate test sections, so that Approval Tests uses different
        // output file names for the different verify() calls.
        auto section = NamerFactory::appendToOutputFilename("section 1");
        Approvals::verify(
            "Approval Tests can verify text via the golden master method");
    }
    {
        auto section = NamerFactory::appendToOutputFilename("section 2");
        Approvals::verify("Approval Tests can verify different text via "
                          "the golden master method");
    }
};

^{snippet source | anchor}

---

Back to User Guide