doctest — The Fastest Feature-Rich C++ Testing Framework

Introduction

doctest is a C++ testing framework that prioritizes compile speed above all else. Its single header adds near-zero overhead to translation units, making it practical to write tests next to production code. Despite the lightweight footprint, doctest offers subcases, parameterized tests, and assertion macros comparable to heavier frameworks.

What doctest Does

• Provides CHECK, REQUIRE, and WARN assertion macros with expression decomposition
• Supports subcases that branch execution paths within a single test case
• Registers tests at file scope without requiring a central test registry
• Compiles significantly faster than Catch2 and GoogleTest in large codebases
• Outputs results in console, JUnit XML, and custom reporter formats

Architecture Overview

doctest is distributed as a single header file. Test cases register via static-init constructors into a global linked list. The runner iterates the list, re-entering each test function once per subcase path to explore all branches. Assertion macros use expression decomposition templates that capture both sides of a comparison for detailed failure messages while keeping the fast path as a single comparison instruction. The header guards implementation behind a DOCTEST_CONFIG_IMPLEMENT macro so it compiles to nothing in non-test translation units.

Self-Hosting & Configuration

• Copy doctest.h into your project or install via vcpkg, Conan, or CMake FetchContent
• Define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN in exactly one source file
• Use --test-case and --subcase filters to run specific tests
• Set DOCTEST_CONFIG_DISABLE in production builds to strip all test code at compile time
• Integrate with CTest using doctest_discover_tests() from the CMake helper

Key Features

• Near-zero compile-time cost makes it viable for tests alongside production code
• Subcases replace fixtures by splitting a test into independent execution paths
• Tests can live in production source files and be stripped in release builds
• Expression decomposition shows both sides of failed comparisons in diagnostics
• Supports templated test cases for testing generic code across types

Comparison with Similar Tools

• Catch2 — richer feature set with generators and BDD sections; doctest compiles significantly faster
• GoogleTest — broader ecosystem with Google Mock; doctest has simpler integration and lower overhead
• Boost.Test — part of the Boost universe; doctest is standalone and header-only
• lest — minimal single-header framework; doctest adds subcases, parameterized tests, and reporters
• Unity — C-only testing for embedded; doctest targets C++ with modern features

FAQ

Q: Can I use doctest alongside production code? A: Yes. Include the header in source files and define DOCTEST_CONFIG_DISABLE for release builds to eliminate all test code.

Q: How does doctest compare to Catch2 in compile time? A: Benchmarks show doctest compiles 40-80% faster than Catch2 v3 depending on the number of assertions per file.

Q: Does doctest support mocking? A: Not built-in. Pair it with trompeloeil, FakeIt, or any standalone C++ mocking library.

Q: Can I write BDD-style tests? A: Use SCENARIO, GIVEN, WHEN, THEN macros that map to test cases and subcases.

Sources

• https://github.com/doctest/doctest
• https://github.com/doctest/doctest/blob/master/doc/markdown/readme.md