code-coverage-data-generate-coloring-html Function

Summary

Generates HTML showing the code coverage.

Package

hcl

Signature

code-coverage-data-generate-coloring-html target &key code-coverage-data shared-source-directory filter target-type color-uncovered color-covered show-counters counter-space index-filename index-name index-sort index-mark-not-entered index-mark-partial index-show-non-runtime open

Arguments

Description

The function code-coverage-data-generate-coloring-html generates HTML showing the code coverage.

target specifies the directory for the HTML files, and optionally the name of the index file, if target has a name component and index-filename is not supplied.

code-coverage-data must be a code-coverage-data object to use. Otherwise code-coverage-data-generate-coloring-html uses the internal data.

shared-source-directory must specify a directory path. It has two effects:

• HTML is produced only for source files in the directory specified by shared-source-directory (filter may exclude some of these).
• The path of each HTML file is constructed from the relative path of the source file with respect to shared-source-directory (as produced by cl:enough-namestring) merged with target. The result is a tree of HTML files which is parallel to the tree of the source files.

If shared-source-directory is not supplied, all files that pass filter are produced, and the target HTML file has the same filename as the source file, but inside the directory specified by target. Note that this may cause clashes if there are files with the same name in the data.

filter can be used to restrict which files HTML is produced for. If filter is a string it is interpreted as a regexp. If the cl:namestring of the truename of a source file matches filter (as by find-regexp-in-string) then HTML is produced for this source file. If filter is a function (or fbound symbol) it must take two arguments, the truename and the code-coverage-file-stats for this source file, and return a boolean specifying whether to produce HTML for this source file. The stats object can be accessed by the code-coverage-file-stats accessor functions (for example code-coverage-file-stats-lambdas-count). If filter is not supplied, all files (or, if shared-source-directory is supplied, all those files inside it) are produced.

target-type specifies the type of the output files. The default value of target-type is "htm".

color-uncovered, color-covered, show-counters and counter-space control the HTML output. See "Source files HTML coloring" below for details. Note that the colors to actually use are specified by code-coverage-set-html-background-colors.

color-uncovered controls whether uncovered forms are colored. These include forms that did not execute at all, eliminated forms and forms which were partially executed but the unexecuted part is hidden (in a macroexpansion). The default value of color-uncovered is t.

color-covered controls whether covered forms are colored. These include forms that were fully executed, and those parts of partially executed forms that were executed. The default value of color-covered is nil.

show-counters controls whether to insert counters in the HTML. The default value of show-counters is t.

counter-space specifies whether to insert a space before and/or after each counter. The value t has the same meaning as :both. The default value of counter-space is :after.

index-filename, index-name, index-sort, index-mark-not-entered, index-mark-partial and index-show-non-runtime control the generation of the index file. See "Index file" below for the description of the index file's contents.

index-filename, when supplied, specifies the name of the index file. It is merged with target to generate the full path. Note that the file type should be included in either index-filename or target. If index-filename is not supplied, it defaults to "code-coverage-index.htm". If index-filename is nil, no index file is produced.

index-name is printed (with format directive ~A) as part of the title of the index file, and not used otherwise. The default value of index-name is "Index".

index-sort controls the order files are listed in the table in the index. :relative-name means sort by the relative name of the source file with respect to shared-source-directory. If shared-source-directory is not supplied, :relative-name has the same effect as :name. :name means sort by the name of the source file. :uncovered means sort by the number of not fully covered run time lambdas in the file (the sum of code-coverage-file-stats-not-called and code-coverage-file-stats-partially-covered called with :runtime). The default value of index-sort is :relative-name.

index-mark-not-entered controls whether to mark cells in the run time part for uncovered lambdas. The default value of index-mark-not-entered is t.

index-mark-partial controls whether to mark cells in the run time part for lambdas that are partially covered. The default value of index-mark-partial is t.

index-show-non-runtime controls whether to show the non-run time part of the table. The default value of index-show-non-runtime is t.

open specifies whether the index file should opened (by open-url) once it is generated. The default value of open is nil.

The HTML output

code-coverage-data-generate-coloring-html generates a HTML file for each source file in code-coverage-data found in shared-source-directory (or all source files if shared-source-directory is nil) and pass filter (or all if filter is nil), as described above, and one index file with statistics. It uses background colors to mark various things (see below), and these colors can be set by code-coverage-set-html-background-colors. The colors that are described below are the default colors.

Index file

The index file contains a table with a single row per file.

The first column shows the file "relative name", which is relative to the optional shared-source-directory, or just the filename. The rest of the columns contain statistics, which are divided into 2 parts: run time lambdas and optional non-run time lambdas. "Lambda" here means a separate piece of code (for example code that is called inline does not count as a separate lambda). Run time lambdas refer to code that is expected to run at run time, which includes things like functions and methods. Non-run time lambdas are other lambdas, like macros and top-level forms (as known as one-shot forms). More accurately, run time and non-run time refer to the counts which are returned by the code-coverage-file-stats accessor functions (for example code-coverage-file-stats-lambdas-count) when they are called with :runtime or :non-runtime. See code-coverage-file-stats for details.

The run time and the non-run time parts each contain 4 columns:

In the run time columns, Partial and None cells which are non-zero are optionally marked with a colored background. This helps you to see which files contain run time forms that were not executed. The default color is DarkSalmon, and this can be set by code-coverage-set-html-background-colors with keyword argument marked-cell.

Source files HTML coloring

The HTML file corresponding to a source file contains the full text of the source file (including comments), with parts optionally highlighted by background colors, and optional counters and some text added. At the time of writing, the default behavior is to highlight uncovered forms and add counters. The background colors can be changed by code-coverage-set-html-background-colors. The general issues associated with coloring are covered in 10.7 Understanding the code coverage output.

Notes

If no file containing code coverage code was loaded, there is no internal data, so if code-coverage-data is not supplied then code-coverage-data-generate-coloring-html signals an error.

See also

code-coverage-data
code-coverage-set-html-background-colors
10 Code Coverage
10.7 Understanding the code coverage output