doctest C++ 完整指南：轻量级单元测试框架详解

1. 什么是 doctest？为什么需要它？

doctest 是一个轻量级、自文档化的 C++ 单元测试框架。它的最大特点是编译时间极短且使用简单。与 Google Test 或 Boost.Test 等重量级框架不同，doctest 是一个仅头文件（header-only）的库，只需一行 #include <doctest/doctest.h> 即可引入。这使得它成为对构建速度和外部依赖敏感项目的理想选择。

为什么需要 doctest？在现代 C++ 开发中，代码测试不是奢侈品，而是必需品。doctest 允许你在函数实现旁边直接编写测试，这提高了代码的可读性并简化了维护。你可以将测试嵌入到头文件中，在编译时如果不使用 -DDOCTEST_CONFIG_DISABLE 标志，它们会自动从最终构建中排除。这提供了一个独特优势：测试与代码共存，却不会影响发布版本的性能。

doctest 支持所有现代 C++ 标准（C++11 及以上），可在所有主流平台（Windows、Linux、macOS）上运行，并轻松集成到持续集成（CI）系统中。它提供了丰富的宏用于断言检查、测试分组、异常处理和报告生成。凭借其轻量特性，doctest 常用于嵌入式开发、游戏引擎以及其他对每个字节和编译毫秒都精打细算的项目中。

2. 安装指南

doctest 是一个仅头文件的库，因此安装只需将头文件复制到你的项目中。最简单的方法是使用包管理器 vcpkg 或 Conan，也可以手动下载文件。

方式一：通过 vcpkg 安装（推荐）

# 如果尚未安装 vcpkg，请先安装：
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # Linux/macOS
# 或 .\bootstrap-vcpkg.bat (Windows)

# 安装 doctest：
./vcpkg install doctest

# 通过 CMake 连接到项目：
# find_package(doctest CONFIG REQUIRED)
# target_link_libraries(your_target PRIVATE doctest::doctest)

方式二：通过 Conan 安装

# 在 conanfile.txt 中添加：
[requires]
doctest/2.4.11

[generators]
cmake

# 安装：
conan install . --build=missing

方式三：手动安装（直接复制文件）

# 从 GitHub 下载最新版本：
wget https://raw.githubusercontent.com/doctest/doctest/master/doctest/doctest.h

# 将文件放入项目的 include 文件夹
# 然后在代码中直接使用：
# #include "doctest.h"

安装后，请确保编译器能找到头文件。编译测试只需任何现代版本的 GCC、Clang 或 MSVC 即可。

3. 快速上手——最小工作示例

创建一个名为 test_example.cpp 的文件，内容如下：

#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("测试阶乘函数") {
    CHECK(factorial(0) == 1);
    CHECK(factorial(1) == 1);
    CHECK(factorial(5) == 120);
    CHECK(factorial(10) == 3628800);
}

编译并运行：

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

你将看到输出：

===========================================================================
[doctest] 测试用例:    1 |    1 通过 |    0 失败 |    0 跳过
[doctest] 断言:        4 |    4 通过 |    0 失败 |
[doctest]