CLion 2020.2 Help

Doctest support

Doctest is a single-header framework with self-registering tests.

Adding Doctest to your project

  1. Download the latest version of doctest.h and copy it into your project tree.

  2. Include the header in your test files:

    #include "doctest.h"

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

Doctest run/debug configuration

  1. Open the Run | Edit Configurations dialog. Under the Doctest node, you will see the configurations created automatically for the detected targets.

    Automatically created Doctest configurations
  2. To create a new Doctest configuration, click icons.general.add.svg and select Dcotest from the list of templates.

  3. Specify the configuration settings:

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

    • 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

      In the Test field, select the desired test. Leave this field to run the entire suite.

      Selecting a test from a suite

      Select the Pattern option to 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

      Alternatively, you can leave the Suite/Test and Pattern fields empty, and provide the Doctest's command line flags via Program arguments instead.

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

  4. Save the configuration, and it's ready for Runicons.actions.execute.svg or Debugicons.actions.startDebugger.svg.

Running tests

In CLion, there are several ways to start a run/debug session for tests, one of which is using special gutter icons. These icons help quickly run or debug a single test or a whole suite/fixture:

Gutter icons for tests

Gutter icons also show test results (when already available): success icons.runConfigurations.testState.green2.svg or failure icons.runConfigurations.testState.red2.svg.

When you run a test/suite/scenario using gutter icons, CLion creates a temporary Doctest configuration, which is greyed out in the configurations list. To save a temporary configuration, select it in the Edit Configurations dialog and press icons.actions.menu-saveall.svg.

Exploring results

When you run tests, the results (and the process) are shown in the test runner window. This 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 icons.runConfigurations.testState.red2.svg tests, export icons.toolbarDecorator.export.svg or open previous results saved automatically artwork.studio.icons.profiler.toolbar.clock.svg, sort the tests alphabetically icons.objectBrowser.sorted.svg to easily find a particular test, or sort them by duration icons.runConfigurations.sortbyDuration.svg to understand which test ran longer than others.

Test runner
Last modified: 08 September 2020