# Unit testing tutorial

This tutorial gives an overview of the unit testing approach and discusses four testing frameworks supported by CLion: Google Test, Boost.Test, Catch2, and Doctest.

The [Unit Testing in CLion](#clion-integrations) part will guide you through the process of including the frameworks into your project and describe CLion testing features.

## The basics of unit testing

Unit testing aims to check individual units of your source code separately. A unit here is the smallest part of code that can be tested in isolation, for example, a free function or a class method.

Unit testing helps:

1.

Modularize your code

As code's testability depends on its design, unit tests facilitate breaking it into specialized easy-to-test pieces.

2. Avoid regressions

When you have a suite of unit tests, you can run it iteratively to ensure that everything [keeps working correctly](https://en.wikipedia.org/wiki/Regression_testing) every time you add new functionality or introduce changes.

3.

Document your code

Running, debugging, or even just reading tests can give a lot of information about how the original code works, so you can use them as implicit documentation.

A single unit test is a method that checks some specific functionality and has clear pass/fail criteria. The generalized structure of a single test looks like this:

```PLAINTEXT
Test (TestGroupName, TestName)   {
    1 - setup block
    2 - running the under-test functionality
    3 - checking the results (assertions block)
}
```

Good practices for unit testing include:

* Creating tests for all publicly exposed functions, including class constructors and operators.

* Covering all code paths and checking both trivial and edge cases, including those with incorrect input data (refer to [negative testing](https://en.wikipedia.org/wiki/Negative_testing)).

* Assuring that each test works independently and does't prevent other tests from execution.

* Organizing tests in a way that the order in which you run them doesn't affect the results.

It's useful to group test cases when they are logically connected or use the same data. Suites combine tests with common functionality (for example, when performing different cases for the same function). Fixture classes help organize shared resources for multiple tests. They are used to set up and clean up the environment for each test within a group and thus avoid code duplication.

Unit testing is often combined with [mocking](https://en.wikipedia.org/wiki/Mock_object). Mock objects are lightweight implementations of test targets, used when the under-test functionality contains complex dependencies and it is difficult to construct a viable test case using real-world objects.

### Frameworks

Manual unit testing involves a lot of routines: writing stub test code, implementing `main()`, printing output messages, and so on. Unit testing frameworks not only help automate these operations, but also let you benefit from the following:

* Manageable assertion behavior With a framework, you can specify whether or not a failure of a single check should cancel the whole test execution: along with the regular `ASSERT`, frameworks provide `EXPECT/CHECK` macros that don't interrupt your test program on failure.

* Various checkers Checkers are macros for comparing the expected and the actual result. Checkers provided by testing frameworks often have configurable severity (warning, regular expectation, or a requirement). Also, they can include tolerances for floating point comparisons and even pre-implemented exception handlers that check raising of an exception under certain conditions.

* Tests organization With frameworks, it's easy to create and run subsets of tests grouped by common functionality (suites) or shared data (fixtures). Also, modern frameworks automatically register new tests, so you don't need to do that manually.

* Customizable messages Frameworks take care of the tests output: they can show verbose descriptive outputs, as well as user-defined messages or only briefed pass/fail results (the latter is especially handy for regression testing).

* XML reports Most of the testing frameworks provide exporting results in XML format. This is useful when you need to further pass the results to a continuous integration system such as [TeamCity](https://www.jetbrains.com/teamcity/) or [Jenkins](https://jenkins.io/).

## Unit testing in CLion

CLion's integration with Google Test, Boost.Test, Catch2, and Doctest includes

* full code insight for framework libraries,

* dedicated run/debug configurations,

* gutter icons to run or debug tests/suites/fixtures and check their status,

* a specialized test runner,

* and code generation for tests and fixture classes (available for Google Tests).

> **Tip:**
> For [CMake](quick-cmake-tutorial.html) projects, CLion also supports [CTest](ctest-support.html).

### Setting up a testing framework for your project

In this chapter, we will discuss how to add the Google Test, Boost.Test, Catch2, and Doctest framework to a project in CLion and how to write a simple set of tests.

As an example, we will use the DateConverter project that you can clone from [github repo](https://github.com/MarinaKalashina/DateConverter). This program calculates the absolute value of a date given in the Gregorian calendar format and converts it into a Julian calendar date. Initially, the project doesn't include any tests - we will add them step by step.  To see the difference between the frameworks, we will use all four to perform the same tests.

You can find the final version of the project in the [DateConverter_withTests](https://github.com/MarinaKalashina/DateConverter_withTests) repository. Here is how the project structure will be transformed:

![sample project with and without tests](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTturorial_sampleproject_transform.png)

For each framework, we will do the following:

1. Add the framework to the DateConverter project.

2. Create two test files, `AbsoluteDateTest.cpp` and `ConverterTests.cpp`. These files will be named similarly for each framework, and they will contain test code written using the syntax of a particular framework.

Now let's open the cloned DateConverter project and follow the instructions given in the tabs below:

Google Test:

Procedure: Include the Google Test framework

1. Create a folder for Google Tests under the DateConverter project root. Inside it, create another folder for the framework's files. In our example, it's `Google_tests` and `Google_tests/lib` folders respectfully.

2. Download Google Test from the official [repository](https://github.com/google/googletest). Extract the contents of the googletest-main folder into `Google_tests/lib`.

3. Add a `CMakeLists.txt` file to the Google_tests folder (right-click it in the project tree and select `New | CMakeLists.txt`). Add the following lines:

```CMAKE
project(Google_tests)
add_subdirectory(lib)
include_directories(${gtest_SOURCE_DIR}/include ${gtest_SOURCE_DIR})
```

4. In the root `CMakeLists.txt` script, add the `add_subdirectory(Google_tests)` line at the end and reload the project.

Procedure: Add Google tests

1. Click `Google_tests` folder in the project tree and select `New | C/C++ Source File`, call it AbsoluteDateTest.cpp.

CLion prompts to add this file to an existing target. We don't need to do that, since we are going to create a new target for this file on the next step.

Repeat this step for ConverterTests.cpp.

2. With two source files added, we can create a test target for them and link it with the `DateConverter_lib` library.

Add the following lines to `Google_tests/CMakeLists.txt`:

```CMAKE
# adding the Google_Tests_run target
add_executable(Google_Tests_run ConverterTests.cpp AbsoluteDateTest.cpp)

# linking Google_Tests_run with DateConverter_lib which will be tested
target_link_libraries(Google_Tests_run DateConverter_lib)

target_link_libraries(Google_Tests_run gtest gtest_main)
```

3. Copy the Google Test version of our checks from [AbsoluteDateTest.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Google_tests/AbsoluteDateTest.cpp) and [ConverterTests.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Google_tests/ConverterTests.cpp) to your `AbsoluteDateTest.cpp` and `ConverterTests.cpp` files.

Now the tests are ready to [run](#run-from-gutter). For example, let's click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.testState.run_run.svg) in the left gutter next to the `DateConverterFixture` declaration in `ConverterTests.cpp` and choose Run.... We will get the following results:

![Google tests results](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_simpletestGoogle.png)

Boost.Test:

Procedure: Include the Boost.Test framework

1. Install and build Boost Testing Framework following these [instructions](https://www.boost.org/doc/libs/1_71_0/libs/test/doc/html/boost_test/adv_scenarios/build_utf.html) (further in the tests we will use the [shared library usage variant](https://www.boost.org/doc/libs/1_71_0/libs/test/doc/html/boost_test/usage_variants.html#boost_test.usage_variants.shared_lib) to link the framework).

2. Create a folder for Boost tests under the DateConverter project root. In our example, it's called `Boost_tests`.

3. Add a `CMakeLists.txt` file to the Boost_tests folder (right-click it in the project tree and select `New | CMakeLists.txt`). Add the following lines:

```CMAKE
set (Boost_USE_STATIC_LIBS OFF)
find_package (Boost REQUIRED COMPONENTS unit_test_framework)
include_directories (${Boost_INCLUDE_DIRS})
```

4. In the root `CMakeLists.txt` script, add the `add_subdirectory(Boost_tests)` line at the end and reload the project.

Procedure: Add Boost tests

1. Click `Boost_tests` in the project tree and select `New | C/C++ Source File`, call it AbsoluteDateTest.cpp.

CLion will prompt to add this file to an existing target. We don't need to do that, since we are going to create a new target for this file on the next step.

Repeat this step for ConverterTests.cpp.

2. With two source files added, we can create a test target for them and link it with the `DateConverter_lib` library. Add the following lines to `Boost_tests/CMakeLists.txt`:

```CMAKE
add_executable (Boost_Tests_run ConverterTests.cpp AbsoluteDateTest.cpp)
target_link_libraries (Boost_Tests_run ${Boost_LIBRARIES})
target_link_libraries (Boost_Tests_run DateConverter_lib)
```

Reload the project.

3. Copy the Boost.Test version of our checks from [AbsoluteDateTest.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Boost_tests/AbsoluteDateTest.cpp) and [ConverterTests.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Boost_tests/ConverterTests.cpp) to the corresponding source files in your project.

Now the tests are ready to [run](#run-from-gutter). For example, let's click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.testState.run_run.svg) in the left gutter next to `BOOST_AUTO_TEST_SUITE(AbsoluteDateCheckSuite)` in `AbsoluteDateTest.cpp` and choose Run.... We will get the following results:

![Boost tests results](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_simpletestBoost.png)

Catch2:

Procedure: Include the Catch2 framework

1. Install Catch2 on system following the [official instruction](https://github.com/catchorg/Catch2/blob/devel/docs/cmake-integration.md#installing-catch2-from-git-repository).

2. Create a folder for Catch2 tests under the DateConverter project root. In our example, it's called `Catch_tests`.

3. Create a `CMakeLists.txt` file in the Catch_tests folder (right-click the folder in the project tree and select `New | CMakeLists.txt`).

We will fill this file step by step. For now, add one command at the top:

```CMAKE
find_package(Catch2 3 REQUIRED)
```

4. In the root `CMakeLists.txt`, add the following command in the end and reload the project:

```
add_subdirectory(Catch_tests)
```

Procedure: Add Catch2 test targets

1. Click `Catch_tests` in the project tree and select `New | C/C++ Source File`, call it AbsoluteDateTest.cpp.

2. Click Add new target:

![Add new tagret for Catch tests](https://resources.jetbrains.com/help/img/idea/2026.2/CMakeLists.txt`.

![Settings for the Catch tests target](https://resources.jetbrains.com/help/img/idea/2026.2/cl_catch_addnewtarget_fields.png)

Click Add.

4. The Catch_tests_run tagret will appear in the list. Make sure to clear all the other checkboxes:

![Adding a file to the newly created target](https://resources.jetbrains.com/help/img/idea/2026.2/CMakeLists.txt`:

```CMAKE
add_executable(Catch_tests_run AbsoluteDateTest.cpp)
```

6. Create another file in the same location and call it ConverterTests.cpp. Add it to the `Catch_tests_run` target:

![Adding another source file to the tests target](https://resources.jetbrains.com/help/img/idea/2026.2/cl_catch_anothersourcefile.png)

7. Now we have two source files linked to the tests target:

![Source files and tests target](https://resources.jetbrains.com/help/img/idea/2026.2/CMakeLists.txt` script and add the following lines after the `add_executable` command:

```CMAKE
target_link_libraries(Catch_tests_run PRIVATE DateConverter_lib)
target_link_libraries(Catch_tests_run PRIVATE Catch2::Catch2WithMain)

include(Catch)
catch_discover_tests(Catch_tests_run)
```

9. Reload the project.

Procedure: Add testing code and run tests

1. Copy the code from [AbsoluteDateTest.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Catch_tests/AbsoluteDateTest.cpp) and [ConverterTests.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Catch_tests/ConverterTests.cpp) to the corresponding source files.

Notice that tests are preceded with

```
#include <catch2/catch_test_macros.hpp>
```

2. Now the tests are ready to run.

The quickest way to run tests is by clicking ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.gutter.run.svg) in the gutter next to a `TEST_CASE`:

![Running from using the gutter menu](https://resources.jetbrains.com/help/img/idea/2026.2/cl_catch_runfromgutter.png)

CLion will show the results in the [Test Runner](viewing-and-exploring-test-results.html) tool window:

![Catch tests results](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_simpletestCatch.png)

Doctest:

Procedure: Include the Doctest framework

1. Create a folder for Doctest tests under the DateConverter project root. In our example, it's called `Doctest_tests`.

2. Download the [doctest.h](https://raw.githubusercontent.com/onqtam/doctest/master/doctest/doctest.h) header and place it in the `Doctest_tests` folder.

Procedure: Add Doctest tests

1. Click `Doctest_tests` in the project tree and select `New | C/C++ Source File`, call it AbsoluteDateTest.cpp.

CLion will prompt to add this file to an existing target. We don't need to do that, since we are going to create a new target for this file on the next step.

Repeat this step for ConverterTests.cpp.

2. Add a `CMakeLists.txt` file to the Doctest_tests folder (right-click the folder in the project tree and select `New | CMakeLists.txt`). Add the following lines:

```CMAKE
add_executable(Doctest_tests_run ConverterTests.cpp AbsoluteDateTest.cpp)
target_link_libraries(Doctest_tests_run DateConverter_lib)
```

3. In the root `CMakeLists.txt`, add `add_subdirectory(Doctest_tests)` in the end and reload the project.

4. Copy the Doctest version of our checks from [AbsoluteDateTest.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Doctest_tests/AbsoluteDateTest.cpp) and [ConverterTests.cpp](https://github.com/MarinaKalashina/DateConverter_withTests/blob/master/Doctest_tests/ConverterTests.cpp) to the corresponding source files in your project.

Now the tests are ready to [run](#run-from-gutter). For example, lets' click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.execute.svg) in the left gutter next to `TEST_CASE("Check various dates")` in `ConverterTests.cpp` and choose Run.... We will get the following results:

![Doctest tests results](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_simpletestDoctest.png)

### Run/Debug configurations for tests

Test frameworks provide the `main()` entry for test programs, so it is possible to run them as regular applications in CLion. However, we recommend using the dedicated run/debug configurations for [Google Test](creating-google-test-run-debug-configuration-for-test.html#gtest-config), [Boost.Test](boost-test-support.html#boost-config), [Catch2](catch-tests-support.html#catch-configs), and [Doctest](doctest-support.html#doctest-config). These configurations include test-related settings and let you benefit from the built-in test runner (which is unavailable if you run the tests as regular applications).

Procedure: Create a run/debug configuration for tests

* Go to Run | Edit Configurations, click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.add.svg) and select one of the framework-specific templates:

![Run/debug configuration templates for testing frameworks](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_configs.png)

> **Note:**
> CLion atomatically creates Google Test configurations for Cmake targets linked with gtest or gmock, as well as Doctest configurations for the detected Doctest targets.

Procedure: Set up your configuration

* Depending on the framework, specify test pattern, suite, or tags (for Catch2). Auto-completion is available in the fields to help you quickly fill them up:

![Auto-completion in configuration fields](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_config_completion.png)

* You can use wildcards when specifying test patterns. For example, set the following pattern to run only the `PlusOneDiff` and `PlusFour_Leap` tests from the sample project:

![Using wildcards in test patterns](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_configs_pattern.png)

* In other fields of the configuration settings, you can set environment variables or command line options. For example, in the Program arguments field you can set `-s` for Catch2 tests to force passing tests to show the full output, or `--gtest_repeat` to run a Google test multiple times:

![Test flags in program arguments](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_configs_flags.png)

The output will look as follows:

```CONSOLE
Repeating all tests (iteration 1) ...
Repeating all tests (iteration 2) ...
Repeating all tests (iteration 3) ...
```

> **Note:**
> Instead of editing each configuration separately, you can modify the template itself: settings will be used by default in new configurations based on that template.

### Gutter icons for tests

In CLion, there are [several ways](performing-tests.html) 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](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_guttericons.png)

Gutter icons also show test results (when already available): success ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.testState.green2.svg) or failure ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.testState.red2.svg).

When you run a test/suite/fixture using gutter icons, CLion creates [temporary Run/Debug configurations](run-debug-configuration.html) of the corresponding type. You can see these configurations greyed out in the list. To save a temporary configuration, select it in the `Edit Configurations` dialog and press ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.save.svg):

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

### Test runner

When you run a test configuration, the results (and the process) are shown in the test runner window that 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.runConfigurations.testState.red2.svg) tests, export ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.export.svg) or open previous results saved automatically ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.vcs.history.svg), sort the tests alphabetically ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.objectBrowser.sorted.svg) 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.

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

> **Tip:**
> You can also execute tests before commit. Set the Run Tests checkbox in the [Commit tool window](commit-and-push-changes.html) and select the configuration to run:
>
> ![Option to run tests before commit](https://resources.jetbrains.com/help/img/idea/2026.2/cl_tests_beforecommit.png)

### Other features

#### Quick Documentation for test macros

To help you explore the macros provided by testing frameworks, [Quick Documentation pop-up](viewing-inline-documentation.html) (`Ctrl+Q` (Windows), `F1` (macOS), `⌃ J` (IntelliJ IDEA Classic (macOS)), `⌘ I` (macOS System Shortcuts), `Ctrl+Q` (XWin), `Ctrl+Q` (GNOME), `Ctrl+Q` (KDE), `Ctrl+Q` (Emacs), `Ctrl+Q` (Sublime Text), `Ctrl+Q` (Sublime Text (macOS)), `⌘ ⌃ ⇧ /` (Xcode), `Ctrl+K, I` (Visual Studio), `⌘ K, I` (Visual Studio (macOS)), `Ctrl+Q` (ReSharper), `⌃ Q` (ReSharper (macOS)), `Ctrl+Q` (QtCreator), `Ctrl+Q` (QtCreator (macOS)), `Ctrl+Q` (NetBeans), `Alt+Middle-Click` (Eclipse), `⌥ Middle-Click` (Eclipse (macOS))) shows the final macro replacement and formats it properly. It also highlights the strings and keywords used in the result substitution:

![Formatted macro expansion in quick documentation popup](https://resources.jetbrains.com/help/img/idea/2026.2/cl_UTtutorial_quickdoc_googlemacro.png)

#### Show Test List

To reduce the time of initial indexing, CLion uses lazy test detection. It means that tests are excluded from indexing until you open some of the test files or run/debug test configurations. To check which tests are currently detected for your project, call Show Test List from `Help | Find Action`. Note that calling this action doesn't trigger indexing.

## See also

### How tos

[Boost.Test](boost-test-support.html) [Catch](catch-tests-support.html) [CTest](ctest-support.html) [Doctest](doctest-support.html) [Google Test](creating-google-test-run-debug-configuration-for-test.html)

### External Links

[Blog post: Fuzz Testing in CLion](https://blog.jetbrains.com/clion/2025/08/fuzz-testing-in-clion/)