Skip to content

UsingDoctest.md

Latest commit

 

History

History
168 lines (123 loc) · 6.76 KB

UsingDoctest.md

File metadata and controls

168 lines (123 loc) · 6.76 KB
Raw

Using Approval Tests With doctest

Contents

Introduction

The doctest test framework works well with Approval Tests.

Notes pre-v.10.8.0:

Earlier versions of Approval Tests had issues with Ninja. Read more at Troubleshooting Misconfigured Build.

Doctest is similar to Catch, but claims to give faster compilation times.

Requirements

Approval Tests for doctest requires that a file called the following is found:

#include <doctest/doctest.h>

snippet source | anchor

Approval Tests needs doctest version 2.3.4 or above.

Getting Started With doctest

New Project

Create a file main.cpp and add just the following two lines:

// main.cpp:
#define APPROVALS_DOCTEST // This tells Approval Tests to provide a main() - only do this in one cpp file
#include "ApprovalTests.hpp"

snippet source | anchor

Existing Project - with your main()

If you have supplied your own main() for doctest, you will need to teach it how to supply test names to Approval Tests.

You should make the following additions to your own source file that contains main().

// Add these two lines to the top of your main.cpp file:
#define APPROVALS_DOCTEST_EXISTING_MAIN
#include "ApprovalTests.hpp"

snippet source | anchor

Multiple dynamically loaded libraries

Approval Tests supports doctest tests spread across several shared libraries (DLLs, .so or .dylib files) that a single test runner loads at run time.

The runner owns doctest's implementation, registry and main(). Build it, and every library, with DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL defined.

In the runner's main.cpp, use the existing-main mode:

#define APPROVALS_DOCTEST_EXISTING_MAIN
#include <ApprovalTests.hpp>

In exactly one source file of each library, add the following before including Approval Tests. It emits Approval Tests' definitions and registers the library's listener:

#define DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL
#define APPROVALS_DOCTEST_EXTERNAL_MAIN
#define APPROVALS_DOCTEST_EXTERNAL_MAIN_IMPLEMENTATION
#define APPROVALS_DOCTEST_LISTENER_NAME "TestModuleOne"
#include <ApprovalTests.hpp>
  • APPROVALS_DOCTEST_EXTERNAL_MAIN enables the integration without defining doctest's implementation or main().
  • APPROVALS_DOCTEST_EXTERNAL_MAIN_IMPLEMENTATION emits the Approval Tests definitions and listener. Use it once per library.
  • APPROVALS_DOCTEST_LISTENER_NAME sets the listener name. It defaults to "approvals", so give each library a different name, otherwise the registrations collide.

Other test source files in the library define only APPROVALS_DOCTEST_EXTERNAL_MAIN.

Load every library before running doctest, and keep them loaded until the doctest context is destroyed.

A complete working example, including the CMake setup for Windows, macOS and Linux, is in examples/doctest_multiple_shared_libraries. It is tested with both the checked-in sources and a generated single header.

Code to copy for your first doctest Approvals test

Here is sample code to create your main() function, to set up Approval Tests' doctest integration.

We called this file doctest_starter_main.cpp:

#define APPROVALS_DOCTEST
#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");

snippet source | anchor

Here is sample code to create your first test. We called this file doctest_starter_test.cpp:

#include "doctest/doctest.h"
#include "ApprovalTests.hpp"

TEST_CASE("doctest_starter 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);
}

snippet source | anchor

And finally, here is sample code to put in your CMakeLists.txt file:

set(EXE_NAME doctest_starter)
set(CMAKE_CXX_STANDARD 11)
add_executable(${EXE_NAME}
        doctest_starter_main.cpp
        doctest_starter_test.cpp
        )
target_link_libraries(${EXE_NAME} ApprovalTests::ApprovalTests doctest::doctest)

add_test(NAME ${EXE_NAME} COMMAND ${EXE_NAME})

snippet source | anchor

Back to User Guide