|
|
|
|
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 lines and functions in your code that have not been exercised by testing. It supports C and C++ applications, as well as Java applications running on a Solaris SPARC 32-bit Java virtual machine (JVM).
- Pinpoint untested areas of your code
- 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
- Collect coverage data on UNIX for viewing on a Windows system
PureCoverage provides the information you need to identify gaps in testing quickly, saving time and effort.
This chapter introduces the basic concepts involved in using PureCoverage. For complete information, see the PureCoverage online help system, including the Java Supplement for PureCoverage.
Finding untested Java code
PureCoverage provides accurate coverage information that identifies all the gaps in your testing of Java code. To collect Java code coverage data, run PureCoverage with the -java option, as follows:
- For an applet:
% purecov [<PureCoverage options>] -java <applet viewer> [<applet viewer options>] <html file>
- For a class file:
% purecov [<PureCoverage options>] -java <Java executable> <Java options>] <class>
- For a JAR file:
% purecov [<PureCoverage options>] -java < Java executable> [<Java options>] <JAR switch> <JAR file>.jar
- For a container program:
% purecov [<PureCoverage options>] -java <exename> [<arguments to exename>]
PureCoverage also monitors native methods written in languages such as C/C++ and assembly using the Java Native Interface (JNI).
To display the coverage data for the program, use the command:
% purecov -view java.pcv
For an example showing how to use PureCoverage to monitor Java code, and for information about ways to control code monitoring, see the Java Supplement for PureCoverage, which is included with the PureCoverage online help system.
Finding untested C/C++ code
This chapter shows you how to use PureCoverage to find the untested parts of the hello_world.c program.
- 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* .
- 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 C/C++ program
- Compile and link the Hello World program, then run the program to verify that it produces the expected output:
- 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.cNote: 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 2003.06.00 Solaris 2 (32-bit), Copyright (C)1994-2003 Rational Software Corp. All rights reserved. Instrumenting: hello_world.o LinkingNote: When you compile and link in separate stages, add purecov only to the link line.
Running the instrumented C/C++ program
Run the instrumented Hello World program:
% a.outPureCoverage 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 C/C++ coverage data
To display the coverage data for the program, use the command:
% purecov -view a.out.pcvThis 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 the button 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 toolnext 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:
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:
- Without exiting PureCoverage, run the program again, this time with an argument. For example:
% a.out GoodbyePureCoverage displays the following:
**** PureCoverage instrumented a.out (pid 17331 at Wed Feb 6 10:38:07 2003) PureCoverage 2003.06.00 Solaris 2 (32-bit), Copyright (C) 1994-2003 Rational Software Corp. * All rights reserved. * For contact information type: "purecov -help" * Options settings: -purecov \ -purecov-home=/usr/rational/releases/purecov.sol.2003.06.00 * License successfully checked out * Command-line: a.out Goodbye 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- 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.
Viewing UNIX coverage data on Windows
You can collect coverage data on your UNIX system and view it on Windows using Rational PureCoverage for Windows.
To collect coverage data for viewing on Windows, assign the value windows or both to the -view-file-format option. You can specify the option in the environment variable PURECOVOPTIONS or on the command line.
With the option set to windows, PureCoverage saves coverage data to a .cfy file, which you can analyze using PureCoverage for Windows. With the option set to both, PureCoverage saves data to a .pcv file as well.
PureCoverage for UNIX does not merge .cfy files, unlike .pcv files. You can merge .cfy files when you view them on Windows.
For more information, see the online help systems for PureCoverage on both UNIX and Windows.
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.
PureCoverage options
PureCoverage provides command-line options for controlling operations and handling coverage data both for C/C++ and for Java code.
Build-time options
For a C or C++ application, specify build-time options on the link line when you instrument with PureCoverage. For example:
% purecov -always-use-cache-dir cc ...For a Java application, specify these options (which for Java are not actually build-time options) on the command line when you run the application with PureCoverage.
For C, C++, and Java applications, you can also set these options using the PURECOVOPTIONS environment variable. For example:
% setenv PURECOVOPTIONS "-always-use-cache-dir"Runtime options
For a C or C++ application, specify runtime options on the link line when you instrument with PureCoverage. For a Java application, specify these options on the command line when you run the application with PureCoverage.
For C, C++, and Java applications, you can also set these options using the PURECOVOPTIONS environment variable. For example:
% setenv PURECOVOPTIONS "-counts-file=./test1.pcv ‘printenv PURECOVOPTIONS‘"1 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.pcvAnalysis-time mode options
Command-line syntax:% purecov -<mode option> [analysis-time options] \ <file1.pcv file2.pcv ...>
-user-pathCopyright© 1992-2003 Rational Software Corporation. All rights reserved.
