In this section:

Introduction

You can annotate code coverage results with test start/stop information to understand how a particular test scenario affects code execution. Test start notification conveys information about the test name, which can be used when processing test data and generating reports.

Test Start/Stop annotations functionality is available as an API and can be extended to many different scenarios. For example, you can associate code coverage results with unit tests or associate code coverage results with manual test scenarios performed during system testing.

Using the Test Start/Stop API

The API includes the following functions:

• void CDECL_CALL CppTest_TestStart(const char* testName) - sends the notification to the results stream about the beginning of a test with a specified name
• void CDECL_CALL CppTest_TestStop(void) - sends the notification to the results stream about the end of the previously started test. 

Include a dedicated header file in the source file that will invoke the API functions: 

#include "cpptest/cpptest.h"

Use the -I option to specify the cpptest.h header file location when compiling the source file: 

-I <Installation Directory>/runtime/include

Specify a valid string as an argument to the CppTest_TestStart function. Null pointers or invalid strings will cause undefined behavior.

Common Applications of the Test Start/Stop Scenarios

The following scenarios illustrate the usage of the test start/stop notification API.

Annotating coverage results with unit test case names

In this scenario, unit test case names are used as an argument specified to CppTest_TestStart function invocation. For some of popular C/C++ unit testing frameworks, dedicated connectors are provided to automate this task. For additional information about unit testing framework connectors, see Unit Testing.
To use a unit testing framework that does not have a dedicated connector, you can invoke start/stop API functions at the beginning and end of the test case:

#include "cpptest/cpptest.h"

TEST(TimerTest, smokeTest) {
  const char * tcName = testCaseName();
  CppTest_TestStart(tcName);
  int res = init_timer();
  ASSERT_TRUE(res != 0);
  CppTest_TestStop();
}

Annotating coverage results with manual test scenario names for system testing sessions

There are a few ways to achieve this goal:

• Calls to test start/stop API can be added directly to the tested source. They can be activated with dedicated macros in the debug or test builds of the tested application. The method for providing the name of the test scenario to the API function call depends on the type of application. In some cases, you can add a special option to the menu of the tested application that is only visible in the debug build or the command line. This would enable you to specify the name of the performed test scenario and send the notification to results stream once the name is entered.
• The names of the test cases can be also read from the environmental variable set before starting tested application.
• Use a special module implemented as a separate thread that is started in parallel to the threads of tested application. The module could, for example, listen on the TCP/IP socket and react when test start/stop command is send from an external tool.