AppCode 2023.1 Help


Boost unit testing framework (Boost.Test) is a part of the Boost library. It is a fully-functional and scalable framework, with wide range of assertion macros, XML output, and other features. Boost.Test itself lacks mocking functionality, but it can be combined with stand-alone mocking frameworks such as gmock.

Adding Boost.Test to your project

You can choose between three usage variants for the framework: header-only, static library, or shared library. When picking the most suitable option, keep in mind that Boost.Test used as header-only might require significant compilation time.

Further on, we will focus on the shared library variant.

  1. Install the Boost library on your Mac. You can quickly install the latest version of the library using the Homebrew package manager: brew install boost. Homebrew will install and build the libraries. You can run brew info boost to check the version and the path to the libraries. By default, the header files will be available under usr/local/include, and library files — under usr/local/lib.

  2. Open the project settings Ctrl+Alt+Shift+S, select the test target, and add the usr/local/include to the Header Search Path field and usr/local/lib to the Library Search Path field:

    Set the Boost paths in Build Settings
  3. Open the project in Xcode (File | Open Project in Xcode), select it in the Project Navigator, choose the test target, and go to the Build Phases tab. Add the library file (libboost_unit_test_framework.dylib) to the Link Binary with Libraries section:

    Add Boost library file
  4. In your source files with tests, add the following lines:

    #define BOOST_TEST_DYN_LINK #define BOOST_TEST_MODULE Tests // the name of the test target #include <boost/test/unit_test.hpp>

Boost.Test run/debug configuration

Although Boost.Test provides the main() entry for your test program, and you can run it as a regular application, we recommend using the dedicated Boost.Test run/debug configuration. It includes test-related settings and let you benefit from the built-in test runner, which is unavailable if you run tests as regular programs.

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

  2. Specify the test or suite to be included in the configuration, or provide a pattern for filtering test names. Auto-completion is available in the fields to help you quickly fill them up:

    completion in configuration fields

    Set wildcards to specify test patterns, for example:

    pattern for tests

  3. In other fields of the configuration settings, you can set environment variables and command-line arguments.

    With Boost.Test version 1.62 or earlier, in case you get the Test framework quit unexpectedly message, set the following string in Program arguments:

    --log_format=HRF --log_level=all

  4. Save the configuration, and it's ready for RunApp actions execute or DebugApp 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 Boost.Test 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. 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: 11 January 2023