10.1 Using Code Coverage

Using Code Coverage involves four steps, described in this section:

1. Compiling the code to record code coverage information.
2. Loading the code.
3. Exercising the code.
4. Displaying the results.

   Optionally, you can get a copy of the results and manipulate these before displaying them, as described in 10.2 Manipulating code coverage data.

10.1.1 Compiling the code to record code coverage information

Switch on generation of Code Coverage by either calling generate-code-coverage (which switches it globally), or using the macro with-code-coverage-generation (which switches it on only within the dynamic scope of the macro). Then compile your file(s) by calling compile-file. Alternatively you can use something that calls compile-file such as compile-system, menu command File > Compile... or the editor command Compile File.

Code Coverage works only when compiling into binary files, rather than into memory (which is what some editor commands such as Compile Buffer do).

When compile-file is called with code coverage generation, it generates code that keeps track of execution and contains some extra data. This results in slightly slower code and larger binary files that use more memory when loaded.

10.1.2 Loading the code

Load your compiled files as usual by calling cl:load. Alternatively you can use something that calls cl:load such as load-system, menu command File > Load... or the editor command Load File.

When a file that was compiled with code coverage generation is loaded, it automatically adds itself to the internal code-coverage-data structure (overwriting existing data), and from that point any access to this structure (see below) will include information about the code in this file. Executing code that was compiled with code coverage generation always updates the internal code-coverage-data structure (it is not switchable).

10.1.3 Exercising the code

Decide what you want to check, and run the entry points.

Code Coverage measures which parts of the program were executed, so you need to decide what you want to check and call the entry points. In a graphical application, you need to display the main window and interact with it.

10.1.4 Displaying the results

There are two ways to view the results:

• as HTML files in a web browser, or:
• with the Editor and Code Coverage Browser tools in the LispWorks IDE.

HTML display is done by calling code-coverage-data-generate-coloring-html, which in general generates one HTML file per source file in the code-coverage-data, and also an index HTML file with hyperlinks to all of them. Editor display is done by the function editor-color-code-coverage, which takes the name of a source file and creates a new editor buffer with the source colored according to the code coverage. Both functions take various keywords to control what they actually do. By default, both of them use the internal code-coverage-data structure, but can also use a manipulated code-coverage-data. See code-coverage-data-generate-coloring-html and editor-color-code-coverage for full details.