# Doctest

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

[Doctest](https://github.com/onqtam/doctest) 是一个具有自注册测试功能的单页眉框架。 如其 [文档](https://github.com/onqtam/doctest/blob/master/README.md)中所述，Doctest 是在 Catch 之后设计的，并共享了 Catch 的部分代码 - 请参阅 [doctest 与 Catch 有何不同](https://github.com/onqtam/doctest/blob/master/doc/markdown/faq.md#how-is-doctest-different-from-catch)。

Doctest [不支持模拟](https://github.com/onqtam/doctest/blob/master/doc/markdown/faq.md#is-mocking-supported)，但您可以将其与第三方模拟库集成，例如 [trompeloeil](https://github.com/rollbear/trompeloeil)、 [googlemock](https://github.com/google/googletest/tree/master/googlemock) 或 [FakeIt](https://github.com/eranpeer/FakeIt)。

## Doctest 基础

如果您不熟悉 Doctest，您可以在下方找到其主要概念的描述：

### 示例测试

使用 Doctest 编写的简单测试如下所示：

```CPLUSPLUS
// provides main(); this line is required in only one .cpp file
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN

#include "doctest.h"

//function to be tested
int fact(int n) {
    return n <= 1 ? n : fact(n - 1) * n;
}

TEST_CASE("testing the factorial function") {
    CHECK(fact(0) == 1); // should fail
    CHECK(fact(1) == 1);
    CHECK(fact(2) == 2);
    CHECK(fact(3) == 6);
    CHECK(fact(10) == 3628800);
}

```

在上面的示例中，  测试阶乘函数  是一个自由格式的测试名称，不需要是唯一的。  `检查`  是 Doctest 的 [断言宏](https://github.com/onqtam/doctest/blob/master/doc/markdown/assertions.md) 之一。

### 测试用例、子测试和套件

Doctest 提供子用例机制，用于创建共享通用设置和清理的嵌套测试（不过，也 [支持](https://github.com/onqtam/doctest/blob/master/doc/markdown/testcases.md#test-fixtures)基于类的固定例程）。

```CPLUSPLUS
TEST_CASE("vectors can be sized and resized") {
    std::vector<int> v(5);

    REQUIRE(v.size() == 5);
    REQUIRE(v.capacity() >= 5);

    SUBCASE("adding to the vector increases its size") {
        v.push_back(1);

        CHECK(v.size() == 6);
        CHECK(v.capacity() >= 6);
    }
    SUBCASE("reserving increases just the capacity") {
        v.reserve(6);

        CHECK(v.size() == 5);
        CHECK(v.capacity() >= 6);
    }
}

```

在上面的代码中，  `TEST_CASE()`  会针对每个  `SUBCASE()`  从头执行。 两个  `要求`  语句保证  `size`  为 5，且  `capacity`  在每个子用例的入口处至少为 5。 如果其中一个  `CHECK()`  失败，这意味着测试失败，但执行会继续。 在每次运行  `TEST_CASE()`  时，Doctest 执行一个子用例并跳过其他子用例。 下一次会执行第二个，依此类推。

类似于 Catch 的部分，子用例可以嵌套以创建检查操作的序列。 每个叶子子用例（内部没有嵌套子用例的子用例）都会执行一次。 父级子用例失败时，会阻止子级子用例运行。

您可以使用  `TEST_SUITE()`  或  `TEST_SUITE_BEGIN()`  /  `TEST_SUITE_END()`  宏将测试用例分组到套件中：

```CPLUSPLUS
TEST_CASE("") {} // not part of any test suite

TEST_SUITE("math") {
    TEST_CASE("") {} // part of the math test suite
    TEST_CASE("") {} // part of the math test suite
}

TEST_SUITE_BEGIN("utils");

TEST_CASE("") {} // part of the utils test suite

TEST_SUITE_END();

TEST_CASE("") {} // not part of any test suite

```

Doctest 还支持 [BDD 风格语法](https://github.com/onqtam/doctest/blob/master/doc/markdown/testcases.md#bdd-style-test-cases)。

## 在 CLion 中使用 Doctest

Procedure: 将 Doctest 添加到您的项目中

1. [下载](https://raw.githubusercontent.com/onqtam/doctest/master/doctest/doctest.h)  `doctest.h`  的最新版本，并将其复制到项目树中。

最低支持的版本为 2.3.0。

2. 在您的测试文件中包含头文件：

```CPLUSPLUS
#include "doctest.h"
```

3. 仅在一个页眉文件中，在  `#include`  前加上  `#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN` 。

如果需要提供自己的  `main` ，请参阅 [这些说明](https://github.com/onqtam/doctest/blob/master/doc/markdown/main.md)。

Procedure: 运行/调试自动创建的 Doctest 配置

CLion 会检测项目中的 Doctest 测试，并为其创建运行/调试配置。

1. 您可以立即使用此配置运行或调试项目中的所有 Doctest 测试：

![自动创建的 Doctest 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_autocreated_config.png)

Procedure: 添加新的 Doctest 运行/调试配置

1. 转到   运行 | 编辑配置  。

2. 点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 并从模板列表中选择   Doctest  。

![添加 Doctest 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_config_templateslist.png)

3. ![Doctest 配置设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_config_overview.png)

* 在 名称 字段中设置配置名称。 此名称将显示在可用运行/调试配置的列表中。

* 套件/测试: 选择此选项以运行特定测试或套件。 在 套件 字段中指定套件名称。 开始输入时，自动补全将建议可用的套件： ![套件名称的自动补全](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_config_suite_completion.png) 在 测试 字段中选择所需的测试。 将此字段留空以运行整个套件。 ![从套件中选择测试](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_config_testselection.png) 测试: 选择此选项以指定单个测试或定义一组测试： * `[#*filename.cpp]` 运行 `filename.cpp` 中的所有测试， * `[suite_name]` 运行具有相应名称的套件， * `[suite_name][test_name]` 或 `[suite_name][test_name][subtest_name]` 运行给定套件中的特定测试， * 使用 `[]` ( `[][]` ) 引用匿名套件，但请确保添加测试名称。 可以在以逗号分隔的列表中指定多个模式，例如: ![Doctest 配置的模式](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_config_pattern.png) 或者，您可以将 套件 和 测试 字段留空，并通过 程序参数 提供 Doctest 的 [命令行标志](https://github.com/onqtam/doctest/blob/master/doc/markdown/commandline.md)。

* 在 目标 字段中，从列表中选择所需的目标。

> **Note:**
> 与其编辑单个配置，不如修改   Doctest   模板本身。 在这种情况下，您指定的设置将作为默认值应用于所有此类型的新配置。

4. 点击   Apply   以保存配置。

5. 在切换器中选择新创建的配置并运行 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.run.svg) 或调试 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.debug.svg)。

![运行/调试 Doctest 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_config_switcher.png)

Procedure: 运行测试

* 在 CLion 中运行或调试测试的最快方法是使用边栏图标：

![测试的侧边栏图标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_gutter.png)

边栏图标还会显示测试结果（如果已可用）：成功 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.gutter.runSuccess.svg) 或失败 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.gutter.runError.svg)。

> **Tip:**
> 有关更多信息，请参阅 [运行、调试、终止测试](performing-tests.html)。

* 使用装订区域图标运行测试/套件/固定例程时，CLion 会创建一个 [临时](run-debug-configuration.html) Doctest 配置，该配置在配置列表中显示为灰色。 要保存临时配置，请在  `编辑配置`  对话框中选择它并点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.save.svg)：

![保存临时测试配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_savetmpconfig.png)

Procedure: 查看测试结果

当您运行测试时，CLion 会在内置的 [测试运行窗口](viewing-and-exploring-test-results.html) 中显示结果和过程。 测试树显示所有测试，并逐一执行。 测试运行器窗口包括：

* 进度条 ，显示到目前为止已执行测试的百分比，

* 树视图 ，显示所有正在运行的测试及其状态和持续时间，

* 测试的输出流，

* 工具栏 ，提供重新运行失败的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.restartFailedTests.svg) 测试、导入/导出或打开自动保存的先前结果 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.history.svg) 的选项，按字母顺序排序测试以便轻松找到特定测试，或按持续时间排序 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.runConfigurations.sortbyDuration.svg) 以了解哪些测试运行时间比其他测试更长。

![测试运行窗口](https://resources.jetbrains.com/help/img/idea/2026.3/cl_doctest_testrunner.png)

## See also

### 快速开始

[单元测试教程](unit-testing-tutorial.html) [快速 CMake 教程](quick-cmake-tutorial.html)

### 流程

[Run/Debug/Terminate Tests](performing-tests.html) [Explore Test Results](viewing-and-exploring-test-results.html)

