AppCode 2023.1 Help


Catch (Catch2) is a header-only testing framework for C++.

AppCode supports Catch versions 1.7.2 and later.

Adding Catch to your project

  1. Download the latest version of the catch.hpp file and copy it to your project tree.

  2. Include the header in your test files:

    #include "catch.hpp"
  3. In only one source file, precede the #include with either #define CATCH_CONFIG_MAIN or CATCH_CONFIG_RUNNER (use the latter if you want to supply your own main()).

Catch run/debug configuration

  1. To create a Catch configuration, go to Run | Edit Configurations, click App general add and select Catch from the list of templates.

  2. Catch run/debug configuration

    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 the Tags/Test option to run a test for the particular tags or all the tags. Select the Pattern option to run all the tests for a particular pattern.

    • Specify tags in the Tags fields. This field is available only when the Tags/Test option is selected.

    • Select the desired test from the Test list. This option is available only when one or more tags have been provided.

    • Specify the pattern name in the Pattern field. This field is available only when the Pattern option is selected.

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

  3. Save the configuration, and it's ready for running App actions execute or debugging App actions start debugger.

Running tests

In AppCode, 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 App run configurations test state green2 or failure App run configurations test state red2.

When you run a test/suite/fixture using gutter icons, AppCode creates a temporary Catch configuration, which is greyed out in the configurations list. To save a temporary configuration, select it in the Edit Configurations dialog and press App actions menu saveall:

Saving temporary test configuration

Exploring results

When you run tests, AppCode shows the results and the process in the built-in test runner window. 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 App run configurations test state red2 tests, export App toolbar decorator export or open previous results saved automatically App vcs history, sort the tests alphabetically App object browser sorted to easily find a particular test, or sort them by duration App run configurations sortby duration to understand which test ran longer than others.

Test runner
Last modified: 02 March 2023