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

> doctest is a single-header C++ testing framework designed for minimal compile-time overhead and maximum speed.

## Install

Save as a script file and run:

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

## Quick Use
```cpp
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include "doctest/doctest.h"

TEST_CASE("vectors can be sized and resized") {
    std::vector<int> v(5);
    REQUIRE(v.size() == 5);
    SUBCASE("resizing bigger changes size") {
        v.resize(10);
        CHECK(v.size() == 10);
    }
}
```
```bash
# Header-only: just include and compile
g++ -std=c++17 -o tests tests.cpp && ./tests
```

## 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

---
Source: https://tokrepo.com/en/workflows/4e1320cd-4278-11f1-9bc6-00163e2b0d79
Author: Script Depot