Doctest

Doctest basics

A simple test written with Doctest looks like this:

// 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.

Doctest provides the mechanism of subcases for creating nested tests with shared common setup and teardown (however, class-based fixtures are also supported).

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:

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.

Working with Doctest in CLion

Add Doctest to your project

Download the latest version of doctest.h and copy it into your project tree.
The minimum supported version is 2.3.0.
Include the header in your test files:
```
#include "doctest.h"
```
In only one header file, precede #include with #define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN.
See these instructions if you need to supply your own main.