doctest for C++: The Complete Guide with Examples

1. What Is doctest and Why Use It?

doctest is a lightweight, self-documenting unit testing framework for C++. Its standout feature is minimal compilation time combined with ease of use. Unlike heavyweight frameworks like Google Test or Boost.Test, doctest is a header-only library you can include with a single line: #include <doctest/doctest.h>. This makes it an ideal choice for projects where build speed and zero external dependencies are critical.

Why use doctest? In modern C++ development, testing isn't a luxury—it's a necessity. doctest lets you write tests right alongside your function implementations, improving code readability and maintainability. You can embed tests directly in header files, and they'll be automatically excluded from the final build when compiling without the -DDOCTEST_CONFIG_DISABLE flag. This gives you a unique advantage: tests live with your code without affecting release performance.

doctest supports all modern C++ standards (C++11 and later), runs on all major platforms (Windows, Linux, macOS), and integrates seamlessly with CI systems. It provides a rich set of macros for assertions, test grouping, exception handling, and report generation. Thanks to its lightweight nature, doctest is widely used in embedded development, game engines, and other projects where every kilobyte and millisecond of compilation time matters.

2. Installation

doctest is a header-only library, so installation is as simple as copying the header file into your project. The easiest methods are using the vcpkg or Conan package managers, or downloading the file manually.

Option 1: Install via vcpkg (Recommended)

# Install vcpkg if you haven't already:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # Linux/macOS
# or .\bootstrap-vcpkg.bat (Windows)

# Install doctest:
./vcpkg install doctest

# Connect to your project via CMake:
# find_package(doctest CONFIG REQUIRED)
# target_link_libraries(your_target PRIVATE doctest::doctest)

Option 2: Install via Conan

# Add to your conanfile.txt:
[requires]
doctest/2.4.11

[generators]
cmake

# Install:
conan install . --build=missing

Option 3: Manual Installation (Just Copy the File)

# Download the latest version from GitHub:
wget https://raw.githubusercontent.com/doctest/doctest/master/doctest/doctest.h

# Place the file in your project's include folder
# Then in your code, simply use:
# #include "doctest.h"

After installation, make sure your compiler can find the header file. Any modern version of GCC, Clang, or MSVC will work for compiling tests.

3. Quick Start — Minimal Working Example

Create a file called test_example.cpp with the following content:

#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include "doctest.h"

int factorial(int n) {
    if (n <= 1) return 1;
    return n * factorial(n - 1);
}

TEST_CASE("testing the factorial function") {
    CHECK(factorial(0) == 1);
    CHECK(factorial(1) == 1);
    CHECK(factorial(5) == 120);
    CHECK(factorial(10) == 3628800);
}

Compile and run:

g++ -std=c++11 test_example.cpp -o test_example
./test_example

You'll see the following output:

===========================================================================
[doctest] test cases:    1 |    1 passed |    0 failed |    0 skipped
[doctest] assertions:    4 |    4 passed |    0 failed |
[doctest]