# Doctest

[Doctest](https://github.com/onqtam/doctest) is a single-header framework with self-registering tests. As stated in its [documentation](https://github.com/onqtam/doctest/blob/master/README.md), Doctest was designed after Catch and shares some parts of the Catch's code - refer to [How is doctest different from Catch](https://github.com/onqtam/doctest/blob/master/doc/markdown/faq.md#how-is-doctest-different-from-catch).

Doctest [doesn't support mocking](https://github.com/onqtam/doctest/blob/master/doc/markdown/faq.md#is-mocking-supported) but you can integrate it with third-party mocking libraries such as [trompeloeil](https://github.com/rollbear/trompeloeil), [googlemock](https://github.com/google/googletest/tree/master/googlemock), or [FakeIt](https://github.com/eranpeer/FakeIt).

## Doctest basics

If you are not familiar with Doctest, you can find a description of its main concepts below:

### Sample test

A simple test written with Doctest looks like this:

```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);
}
```

In the example above, testing the factorial function is a free-form test name, which doesn't have to be unique. `CHECK` is one of the Doctest's [assertion macros](https://github.com/onqtam/doctest/blob/master/doc/markdown/assertions.md).

### Test cases, subtests, and suites

Doctest provides the mechanism of subcases for creating nested tests with shared common setup and teardown (however, class-based fixtures are also [supported](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);
    }
}
```

In the code above, `TEST_CASE()` is executed from the start for each `SUBCASE()`. Two `REQUIRE` statements guarantee that `size` is 5 and `capacity` is at least 5 at the entry of each subcase. If one of the `CHECK()`-s fails, this means the test has failed, but the execution continues. On each run of a `TEST_CASE()`, Doctest executes one subcase and skips the others. Next time, the second one is executed, and so on.

Similarly to Catch's sections, subcases can be nested to create sequences of checking operations. Each leaf subcase (a subcase with no nested subcases inside) is executed once. When a parent subcase fails, it prevents child subcases from running.

You can group test cases into suites using the `TEST_SUITE()` or `TEST_SUITE_BEGIN()` / `TEST_SUITE_END()` macros:

```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 also supports the [BDD-style syntax](https://github.com/onqtam/doctest/blob/master/doc/markdown/testcases.md#bdd-style-test-cases).

## Working with Doctest in CLion

Procedure: Add Doctest to your project

1. [Download](https://raw.githubusercontent.com/onqtam/doctest/master/doctest/doctest.h) the latest version of `doctest.h` and copy it into your project tree.

The minimum supported version is 2.3.0.

2. Include the header in your test files:

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

3. In only one header file, precede `#include` with `#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN`.

See [these instructions](https://github.com/onqtam/doctest/blob/master/doc/markdown/main.md) if you need to supply your own `main`.

Procedure: Run/debug the automatically created Doctest configuration

CLion detects the Doctest tests in your project and creates a run/debug configuration for them.

1. You can use this configuration right away to run or debug all the Doctest tests in your project:

![The automatically created Doctest configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_autocreated_config.png)

Procedure: Add a new Doctest run/debug configuration

1. Go to Run | Edit Configurations.

2. Click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) and select Doctest from the list of templates.

![Adding a Doctest configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_config_templateslist.png)

3. ![Doctest configuration settings](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_config_overview.png)

* Set the configuration name in the Name field. This name will be shown in the list of the available run/debug configurations.

* Suite/Test: Select this option to run a particular test or suite. In the Suite field, specify the suite name. Start typing, and auto-completion will suggest the available suits: ![Auto-completion for suite names](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_config_suite_completion.png) In the Test field, select the desired test. Leave this field to run the entire suite. ![Selecting a test from a suite](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_config_testselection.png) Test: Select this option to specify a single test or define a set of tests: * `[#*filename.cpp]` to run all tests in `filename.cpp`, * `[suite_name]` to run a suite with the corresponding name, * `[suite_name][test_name]` or `[suite_name][test_name][subtest_name]` to run a particular test from a given suite, * use `[]`(`[][]`) to refer to an anonymous suite, but make sure to add a test name. You can specify several patterns in a comma-separated list, for example: ![Pattern for a Doctest configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_config_pattern.png) Alternatively, you can leave the Suite and Test fields empty, and provide the Doctest's [command line flags](https://github.com/onqtam/doctest/blob/master/doc/markdown/commandline.md) via Program arguments instead.

* In the Target field, select the desired target from the list.

> **Note:**
> Instead of editing a single configuration, you can modify the Doctest template itself. In this case, the settings you specify will apply as defaults to all new configurations of this type.

4. Click Apply to save the configuration.

5. Select the newly created configuration in the switcher and run ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.run.run.svg) or debug ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.run.debug.svg) it.

![Run/dubug a Doctest configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_config_switcher.png)

Procedure: Run tests

* The quickest way to run or debug test in CLion is by using the gutter icons:

![Gutter icons for tests](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_gutter.png)

Gutter icons also show test results (when already available): success ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.gutter.runSuccess.svg) or failure ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.gutter.runError.svg).

> **Tip:**
> Refer to [Run, debug, terminate tests](performing-tests.html) for more information.

* When you run a test/suite/fixture using gutter icons, CLion creates a [temporary](run-debug-configuration.html) Doctest configuration, which is greyed out in the list of configurations. To save a temporary configuration, select it in the `Edit Configurations` dialog and click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.save.svg):

![Saving a temporary test configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_savetmpconfig.png)

Procedure: Explore test results

When you run tests, CLion shows the results and the process in the built-in [test runner window](viewing-and-exploring-test-results.html). The test tree shows all the tests while they are being executed one by one. The test runner window includes:

* progress bar with the percentage of tests executed so far,

* tree view of all the running tests with their status and duration,

* tests' output stream,

* toolbar with the options to rerun failed ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.run.restartFailedTests.svg) tests, import/export or open previous results saved automatically ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.history.svg), sort the tests alphabetically to easily find a particular test, or sort them by duration ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.sortbyDuration.svg) to understand which test ran longer than others.

![The Test runner window](https://resources.jetbrains.com/help/img/idea/2026.2/cl_doctest_testrunner.png)

## See also

### Getting Started

[Unit testing tutorial](unit-testing-tutorial.html) [Quick CMake tutorial](quick-cmake-tutorial.html)

### Procedures

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