3

Using Rational PureCoverage

Rational PureCoverage: What it does

During the development process, software changes daily, sometimes hourly. Unfortunately, test suites do not always keep pace. Rational® PureCoverage® is a simple, easily deployed tool that identifies the portions of your code that have not been exercised by testing.

Using PureCoverage, you can:

• Identify the portions of your application that your tests have not exercised
• Accumulate coverage data over multiple runs and multiple builds
• Merge data from different programs sharing common source code
• Work closely with Purify to make sure that Purify finds errors throughout your entire application
• Automatically generate a wide variety of useful reports
• Access the coverage data so you can write your own reports

PureCoverage provides the information you need to identify gaps in testing quickly, saving precious time and effort.

This chapter introduces the basic concepts involved in using PureCoverage. For complete information, see the PureCoverage online help system.

Finding untested areas of Hello World

This chapter shows you how to use PureCoverage to find the untested parts of the hello_world.c program.

Before you begin:

1. If PureCoverage has been installed on your system as a component of Rational PurifyPlus, the Rational directory contains the files purifyplus_setup.csh and purifyplus_setup.sh. Source the file that is appropriate to your shell to license PureCoverage for your use.
2. Create a new working directory. Go to the new directory, and copy the hello_world.c program and related files from the <purecovhome>/example directory:

   % mkdir /usr/home/pat/example
   % cd /usr/home/pat/example
   % cp <purecovhome>/example/hello* .
   

3. Examine the code in hello_world.c.

The version of hello_world.c provided with PureCoverage is slightly more complicated than the usual textbook version.

#include <stdio.h>
void display_hello_world();
void display_message();

main(argc, argv)
int argc;
char** argv;
{
if (argc == 1)
display_hello_world();
else
display_message(argv[1]);
exit(0);
}

void
display_hello_world()
{
   printf("Hello, World\n");
}

void
display_message(s)
   char *s;
{
   printf("%s, World\n", s);
}

Instrumenting a program

1. Compile and link the Hello World program, then run the program to verify that it produces the expected output:
   

2. Instrument the program by adding purecov to the front of the compile/link command line. To have PureCoverage report the maximum amount of detail, use the -g option:

   % purecov cc -g hello_world.c
   

   Note: If you compile your code without the -g option, PureCoverage provides only function-level data. It does not show line-level data.

A message appears, indicating the version of PureCoverage that is instrumenting the program:

PureCoverage 4.4 Solaris 2, Copyright 1994-1999 Rational Software Corp.
All rights reserved.
Instrumenting: hello_world.o Linking

Note: When you compile and link in separate stages, add purecov only to the link line.

Running the instrumented program

Run the instrumented Hello World program:

% a.out

PureCoverage displays the following:

The a.out program produces its normal output, just as if it were not instrumented. When the program completes execution, PureCoverage writes coverage information for the session to the file a.out.pcv. Each time the program runs, PureCoverage updates this file with additional coverage data.

Displaying coverage data

To display the coverage data for the program, use the command:

% purecov -view a.out.pcv &

This displays the PureCoverage Viewer.

In this example, there is only one source directory, so the information displayed for the directory is identical to the Total Coverage information.

Note: The default header for line statistics is ADJUSTED LINES, not just LINES. This is because PureCoverage has an adjustment feature that lets you adjust coverage statistics by excluding specific lines. Under certain circumstances, the adjusted statistics give you a more practical reflection of coverage status than the actual coverage statistics. The ADJS column in this example contains zeroes, indicating that it does not include adjustments.

Expanding the file-level detail

Click next to .../example/ to expand the file-level information for the directory.

You used only one file in the example directory to build a.out. Therefore the FUNCTIONS and ADJUSTED LINES information for the file is the same as for the directory. The number 1 in the Runs column indicates that you ran the instrumented a.out. only once.

Note: When you are examining data collected for multiple executables, or for executables that have been rebuilt with some changed files, the number of runs can be different for each file.

Examining function-level detail

Expand the hello_world.c line to show function-level information.

The Viewer shows coverage information for the functions display_message, main, and display_hello_world.

PureCoverage does not list the printf function or any functions that it calls. The printf function is a part of the system library, libc. By default, PureCoverage excludes collection of data from system libraries.

Examining the annotated source

To see the source code for main annotated with coverage information, click the Annotated Source tool next to main in the Viewer. PureCoverage displays the Annotated Source window.

PureCoverage highlights code that was not used when you ran the program. In this file only two pieces of code were not used:

• The display_message(argv[1]); statement in main
• The entire display_message function

A quick analysis of the code reveals the reason: the program was invoked without arguments.

Improving Hello World's test coverage

To improve the test coverage for Hello World:

1. Without exiting PureCoverage, run the program again, this time with an argument. For example:

   % a.out Goodbye
   

   PureCoverage displays the following:

   ****  PureCoverage instrumented a.out (pid 17331 at Wed Feb 3 10:38:07 1999) PureCoverage 4.4 Solaris 2, Copyright (C) 1994-1999 Rational Software Corp.
   * All rights reserved.
   * For contact information type: "purecov -help"
   * Command-line: a.out Goodbye
   * Options settings: -purecov \
   -purecov-home=/usr/pure/purecov-4.4-solaris2
   * PureCoverage licensed to Rational Software Corp.
   * Coverage counting enabled.
   Goodbye, World
   
   ****  PureCoverage instrumented a.out (pid 17331)  ****
   * Saving coverage data to /usr/home/pat/example/a.out.pcv.
   * To view results type: purecov -view /usr/home/pat/example/a.out.pcv
   

2. PureCoverage displays a dialog confirming that coverage data has changed for this run. Select Reload changed .pcv files and click OK.

Note: This dialog appears only if the PureCoverage Viewer is open when you run the program.

PureCoverage updates the coverage information in the Viewer and the Annotated Source window.

Note: If you still have untested lines, it is possible that your compiler is generating unreachable code.

3. Select File > Exit.

Using report scripts

You can use PureCoverage report scripts to format and process PureCoverage data. The report scripts are located in the <purecovhome>/scripts directory.

Select File > Run script to open the script dialog.

You can also run report scripts from the command line.

Report scripts
pc_annotate   Produces an annotated source text file % pc_annotate [-force-merge][-apply-adjustments=no]\ [-file=<basename>...][-type=<type>][<prog>.pcv...]
pc_below        Reports low coverage % pc_below [-force-merge][-apply-adjustments=no][-percent=<pct>]\ [<prog>.pcv...]
pc_build_diff        Compares PureCoverage data from two builds of an application % pc_build_diff [-apply-adjustments=no][-prefix=XXXX....] old.pcv \ new.pcv
pc_covdiff        Annotates the output of diff for modified source code Note: Cannot run from Viewer % yourdiff <name> | pc_covdiff [-context=<lines>] \ [-format={diff|side-by-side|new-only}][-lines=<boolean>] \ -tabs=<stops>][-width=<width>][-force-merge][-apply-adjustments=no] \ -file=<name> <prog>.pcv...
pc_diff        Lists files for which coverage has changed % pc_diff [-apply-adjustments=no] old.pcv new.pcv
pc_email        Mails a report to the last person who modified insufficiently covered files % pc_email [-force-merge][-apply-adjustments=no][-percent=<pct>] \ [<prog>.pcv...]
pc_select        Identifies the subset of tests required to exercise modified source code % <list of changed files> | pc_select \ [-diff=<rules>][-canonicalize=<rule>]test1.pcv test2.pcv...
pc_ssheet        Produces a summary in spreadsheet format % pc_ssheet [-force-merge][-apply-adjustments=no][<prog>.pcv...]
pc_summary        Produces an overall summary in table format % pc_summary [-file=<name>...] [-force-merge] [-apply-adjustments=no] [<prog>.pcv...]

Build-time options

You can specify build-time options on the link line when you instrument programs with PureCoverage. For example:

% purecov -cache-dir=$HOME/cache -always-use-cache-dir \
cc ...

Commonly used build-time options	Default
-always-use-cache-dir Forces all PureCoverage instrumented object files to be written to the global cache directory	no
-auto-mount-prefix Removes the prefix used by file system auto-mounters	/tmp_mnt
-cache-dir Specifies the global directory where PureCoverage caches instrumented object files	<purecovhome>/cache
-collector Specifies the collect program to handle static constructors (for use with gcc, g++)	none
-ignore-run-time-environment Prevents the run-time PureCoverage environment from overriding the option values used in building the program	no
-linker Specifies a linker other than the system default for building the executables	system-dependent

Run-time options

You can specify run-time options on the link line or by using the PURECOVOPTIONS environment variable. For example:

% setenv PURECOVOPTIONS \
"-counts-file=./test1.pcv 'printenv PURECOVOPTIONS'"

Commonly used run-time options	Default
-counts-file1 Specifies an alternate file for writing coverage count data in binary format	%v.pcv
-follow-child-processes Controls whether PureCoverage is enabled in forked child processes	no
-log-file1 Specifies a log file for PureCoverage run-time messages	stderr
-program-name Specifies the full pathname of the PureCoverage instrumented program	argv[0]
-user-path1 Specifies a list of directories to search for source code	none

¹  Can use the conversion characters listed in Conversion characters for filenames.

Analysis-time options

Use analysis-time options with analysis-time mode options. For example:

% purecov -merge=result.pcv -force-merge filea.pcv fileb.pcv

Commonly used analysis-time options	Default
-apply-adjustments Applies all adjustments in the $HOME/.purecov.adjust file to exported coverage data	yes
-force-merge Forces the merging of coverage data files (.pcv) obtained from different versions of the same object file	no

Analysis-time mode options

Command-line syntax:

% purecov -<mode option> [analysis-time options] \
<file1.pcv file2.pcv ...>

Analysis-time mode options	Compatible options
-export Merges and writes coverage counts from multiple coverage data files (.pcv) in export format to a specified file (-export=<filename>) or to stdout	-apply-adjustments
-extract Extracts adjustment data from source code files and writes it to $HOME/.purecov.adjust	none
-merge=<filename.pcv> Merges and writes coverage counts from multiple coverage data files (.pcv) in binary format	-force-merge
-view Opens the PureCoverage Viewer for analysis of one or more coverage data files (.pcv)	-force-merge, -user-path

Copyright© 1999, 2001 Rational Software Corporation. All rights reserved.

---