In this section:

Overview

C/C+test can send the results of tests executed with CppUnit and CppUtest to DTP server, as well as associate tests with code coverage. To integrate CppUnit or CppUtest with C/C++test, you need to install a results listener and a coverage annotator into the existing CppUnit or CppUtest infrastructure.

The typical integration includes both the results listener and the coverage annotator, which give you complete information about tests results and coverage. You may choose to install only the results listener for lightweight tests or for comparing results with and without coverage.

Installing C/C++test into Test Setups

This section describes CppUnit and CppUtest setups with both the results listener and the coverage annotator. If you choose to install the results listener only, skip all the lines which mention the coverage annotator.

Installing C/C++test into CppUnit Setup

Include a dedicated header file in the source file that contains the CppUnit main function:

#include "cpptest/extensions/cppunit/results_listener.h"
#include "cpptest/extensions/cppunit/coverage_annotator.h"

Install the results listener. The installation details will depend on the TestRunner class of the CppUnit framework you use to execute unit tests.
For simple setups, your modified main function may resemble the following:

     /* required header files */

     int main()
     {
         CPPUNIT_NS::Test *suite = CPPUNIT_NS::TestFactoryRegistry::getRegistry().makeTest();
         CPPUNIT_NS::TextUi::TestRunner runner;
         runner.addTest( suite );

         CppTest_CppUnitResultsListener cpptestResListener;
         CppTest_CppUnitCoverageAnnotator cpptestCovAnnotator;

         runner.eventManager().addListener( &cpptestResListener );
         runner.eventManager().addListener( &cpptestCovAnnotator );

         runner.setOutputter( new CPPUNIT_NS::CompilerOutputter( &runner.result(), std::cout));
         bool wasSucessful = runner.run();
         return wasSucessful ? 0 : 1;

Depending on the class that was used, installation of the modifications may differ. The examples below show installation for two classes of the CppUnit framework.
Installation for the CppUnit::TestRunner class:

     CppUnit::TestResult controller;
     CppTest_CppUnitResultsListener cpptestResListener;
     CppTest_CppUnitCoverageAnnotator cpptestCovAnnotator;
     controller.addListener( &cpptestResListener );      
     controller.addListener( &cpptestCovAnnotator );      

     CppUnit::TestRunner runner;
     runner.addTest(CppUnit::TestFactoryRegistry::getRegistry().makeTest() );   
     runner.run( controller, testPath );

Installation for the CppUnit::TextTestRunner class:

 CppUnit::TextTestRunner runner;
     CppTest_CppUnitResultsListener cpptestResListener;
     CppTest_CppUnitCoverageAnnotator cpptestCovAnnotator;
     runner.eventManager().addListener(&cpptestResListener);
     runner.eventManager().addListener(&cpptestCovAnnotator);

Modify your build system configuration to specify the results_listener.h header file location with the -I option:
```
-I<C++test Installation Directory>/runtime/include 
```

Installing C/C++test into CppUtest Setup

Include a dedicated header file in the source file that contains the CppUtest main function.

#include "cpptest/extensions/cpputest/results_listener.h"
#include "cpptest/extensions/cpputest/coverage_annotator.h"
#include "cpptest/extensions/cpputest/test_runner.h"

Install the results listener. The installation requires registration of the coverage annotator and the results listener into the TestRegistry class. It also requires use of a C++test supplied TestRunner.
For simple setups, your modified main function may resemble the following:

 /* required header files */
int main()
{
    // Register C++Test cpputest plugins
    TestRegistry* registry = TestRegistry::getCurrentRegistry();
    TestPlugin* coverageAnnotator = new CppTest_CppUtestCoverageAnnotator();
    registry->installPlugin(coverageAnnotator);
    TestPlugin* resultsListener = new CppTest_CppUtestResultsListener();
    registry->installPlugin(resultsListener);
    // run the tests
    int result = CppTest_CppUtestTestRunner::RunAllTests(ac, av);
    delete coverageAnnotator;
    delete resultsListener;
    return result;

Modify your build system configuration to specify the results_listener.h header file location with the -I option:
```
-I<C++test Installation Directory>/runtime/include
```

Reporting CppUnit and CppUtest Test Results

The results listener can record unit test execution results and store the data in a file. By default, execution results are stored in the cpptest_results.utlog file in the current working directory. You can change the default file location by providing the path as an argument to the CppTest_CppUnitResultsListener (CppUnit) or CppTest_CppUtestResultsListener (CppUtest) constructor:

For CppUnit

CppTest_CppUnitResultsListener cpptestResListener("c:/myworkspace/cpptest_results.utlog");

For CppUtest

CppTest_CppUtestResultsListener cpptestResListener("c:/myworkspace/cpptest_results.utlog");

Alternatively, you can use the following definition to specify the location during the test harness build process:

-DCPPTEST_UT_LOG_FILE=\"c:/home/my_workspace/cpptest_results.utlog\"

If you choose to change the default file location, it is important to retain the .utlog file extension.

Once the test executable with the results listener is built, you can execute the scheduled unit tests. In standard setups, the cpptest_results.utlog file generated during test execution will be placed into the directory that contains the executable. If you modified the file path, the file will be created in the specified location.

Unit test execution results can be published to DTP server or a local report can be generated with the following command line:

cpptestcli -config "builtin://Unit Testing" -input <result_filename>.utlog -publish -report local_report

See Reviewing Results for details on configuring and publishing reports.

Unit test execution results are typically combined with code coverage results.

Associating Tests with Code Coverage

You can automatically annotate code coverage results with test start/stop information (see Annotating Results with Test Start and Stop Information). This allows you to selectively analyze code coverage generated by a specific test or a collection of tests. Associating tests with code coverage requires the installation of both the coverage results annotator and the results listener, along with C/C++test.

The coverage annotator adds special markers into the code coverage results stream. These markers delimit coverage results for each test case. The coverage annotator adds the markers to the coverage results file, which is managed by C/C++test. The annotator does not require any input parameters.

Once the test executable with the results listener is installed, you can execute the scheduled unit tests. In standard setups, the cpptest_results.clog file and the cpptest_results.utlog file generated during test execution will be placed into the current working directory.

Run the following command to generate a local report and enable the selective analysis of code coverage on DTP server:

cpptestcli -config "builtin://Unit Testing" -input cpptest_results.utlog -input cpptest_results.clog -publish -report local_report

Page tree

Integrating with CppUnit and CppUtest