This topic describes how to generate the Coverage summary report, which describes how much of your program has been tested by Insure++ and how often each block of code was executed. In this section:

Introduction

You can view the coverage report from the GUI or command line on Windows. You must enable Insure++ to analyze coverage information before Insure++ can output coverage information to the GUI or command line.

Enabling Coverage

Open Insure++ and choose Window > Control Panel.
Enable the Coverage option in the Summarize section.
Enable the Generate coverage map data option.
(Optional) The Counting coverage option if you want to include a field that shows how many times each block of code was executed in each run. Enabling this option may affect performance.
(Optional) Enable the Log coverage data option if you want to merge the coverage data across successive runs of the same program.
Click Save.

Generating the Coverage Summary Report

Run the instrumented application after enabling coverage to begin collecting coverage data (see Windows Usage).
Close the application after running your scenario. The Coverage summary report will appear in the session directory.
Click on the report for a visualization of the coverage.
Click Open to view the full report.

Viewing the Coverage Summary Report

You can perform the following actions after generating the report:

Click Open in the overview screen to access the report.
By default, coverage is grouped by location and sorted by name, but you can choose display options from the Summarize and Sort menus to present the coverage information in different ways.
You can drill down to a function to view the coverage for the source file. The arrow in the code view panel indicates the beginning of the function.

Command Line Usage

Use the insure command instead of your normal compiler to process your application. Insure++ builds a temporary file that contains your original source code instrumented for coverage analysis. The file is passed to your normal compiler. When your application runs, it creates a database containing information about which blocks were executed.

Insure++ tracks code coverage information in a file called tca.log. This file is located in the same directory that your executable was built.

Run the tca command and specify the tca.log file to review coverage information from the command line:

tca <TCA_OPTIONS> <PATH_TO_FILE>/tca.log

Code must be included when the application runs to be considered for coverage. If code is linked to an executable that is never executed, for example, then it is ignored by Insure++.

You can run the tca command by itself to print the command line help, which describes the available TCA options.

Example

We'll use the string sorting example program (strsort.c) to demonstrate how to analyze code coverage on the command line. See Examples for Windows Systems for additional information about the examples shipped with Insure++.

Make a copy of the examples directory and navigate to the c directory.

Create a .psrc file in the directory and add the following settings (see Configuration Options (psrc) for additional information):

insure++.coverage_log_file tca.log
insure++.summarize coverage
insure++.coverage_map_data on
insure++.coverage_map_file tca.map

Compile the strsort.c file using the insure command and your usual options, e.g.:
insure /Zi strsort.c
Run the program using the following syntax:

strsort.exe -<d or a> <STR1> <STR2> <STR3>

The -d flag sorts the specified strings into descending order, while the -a flag sorts into ascending order.
Insure++ creates a tca.log file to capture code coverage. The file will be updated each time you run the program.
Generate the coverage report by running the following command:
tca tca.log
You will see the following output:
COVERAGE SUMMARY ================ 26 blocks untested 13 blocks tested 33% covered

You can specify additional arguments to create specific views of the coverage information. The following example sorts the data by function, e.g.:tca -df tca.log

COVERAGE SUMMARY - by function
================

   blocks   blocks   %cov =      functions
 untested   tested   %tested
 -------------------------------------------------

       1        0        0%      __local_stdio_printf_options [corecrt_stdio_config.h, line 90-93]
       1        0        0%      __local_stdio_scanf_options [corecrt_stdio_config.h, line 100-103]
       1        0        0%      _wcstok              [corecrt_wstring.h, line 243-245]
       0        5      100%      bubble_sort          [strsort.c, line 10-24]
       1        8       88%      main                 [strsort.c, line 29-46]
      11        0        0%      memcpy_s             [corecrt_memcpy_s.h, line 45-64]
       9        0        0%      memmove_s            [corecrt_memcpy_s.h, line 73-85]
       1        0        0%      strnlen_s            [string.h, line 371-373]
       1        0        0%      wcsnlen_s            [corecrt_wstring.h, line 165-167]

Use the tca command with no options or file to print the available options.

Next Steps

See Viewing Results on Windows for additional information about understanding results.

See Working with Insure++ Reports for additional information about understanding and customizing Insure++ reports.