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
A pathname designator.
A code-coverage-data object.
A string, a function or a symbol naming a function.
A string or nil.
A boolean.
A boolean.
A boolean.
nil, :before, :after, :both or t.
A pathname designator or nil.
A string.
One of the keywords :relative-name, :name and :uncovered.
A boolean.
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:
cl:enough-namestring) merged with the target directory. 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 passed the filter are produced, and the target HTML file has the filename of the source file inside the target directory. 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 the target path to generate the full path. Note that the file type should be included in either index-filename or the target path. 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 runtime 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 runtime part for uncovered lambdas. The default value of index-mark-not-entered is t.
index-mark-partial controls whether to mark cells in the runtime 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-runtime 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.
code-coverage-data-generate-coloring-html generates a HTML file for each source file in code-coverage-data that is inside the shared-source-directory (or all source files if shared-source-directory is nil) and pass the 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.
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: runtime lambdas and optional non-runtime lambdas. "Lambda" here means a separate piece of code (for example code that is called inline does not count as a separate lambda). Runtime lambdas refer to code that is expected to run at runtime, which includes things like functions and methods. Non-runtimes are other lambdas, like macros and top-level forms (as known as one-shot forms). More accurately, runtime and non-runtime 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 runtime and the non-runtime parts each contain 4 columns:
The total number of lambdas, as returned by code-coverage-file-stats-lambdas-count.
The number of lambdas that were fully covered, as returned by code-coverage-file-stats-fully-covered.
The number of lambdas that were partially covered, as returned by code-coverage-file-stats-partially-covered.
The number of lambdas that were not covered, as returned by code-coverage-file-stats-not-called.
In the runtime columns, Partial and None cells which are non-zero are optionally marked with a colored background. This helps you to see which files contain runtime 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.
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 Understanding the code coverage output.
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.
code-coverage-data
code-coverage-set-html-background-colors
Code Coverage
Understanding the code coverage output
LispWorks User Guide and Reference Manual - 13 Feb 2015