Previous: sb-rotate-byte, Up: Contributed Modules


16.7 sb-cover

The sb-cover module provides a code coverage tool for SBCL. The tool has support for expression coverage, and for some branch coverage. Coverage reports are only generated for code compiled using compile-file with the value of the sb-cover:store-coverage-data optimization quality set to 3.

As of SBCL 1.0.6 sb-cover is still experimental, and the interfaces documented here might change in later versions.

16.7.1 Example Usage

     ;;; Load SB-COVER
     (require :sb-cover)
     
     ;;; Turn on generation of code coverage instrumentation in the compiler
     (declaim (optimize sb-cover:store-coverage-data))
     
     ;;; Load some code, ensuring that it's recompiled with the new optimization
     ;;; policy.
     (asdf:oos 'asdf:load-op :cl-ppcre-test :force t)
     
     ;;; Run the test suite.
     (cl-ppcre-test:test)
     
     ;;; Produce a coverage report
     (sb-cover:report "/tmp/report/")
     
     ;;; Turn off instrumentation
     (declaim (optimize (sb-cover:store-coverage-data 0)))

16.7.2 Functions

— Function: sb-cover:report directory &key form-mode external-format

Print a code coverage report of all instrumented files into directory. If directory does not exist, it will be created. The main report will be printed to the file cover-index.html. The external format of the source files can be specified with the external-format parameter.

If the keyword argument form-mode has the value :car, the annotations in the coverage report will be placed on the CARs of any cons-forms, while if it has the value :whole the whole form will be annotated (the default). The former mode shows explicitly which forms were instrumented, while the latter mode is generally easier to read.

— Function: sb-cover:reset-coverage

Reset all coverage data back to the `Not executed` state.

— Function: sb-cover:clear-coverage

Clear all files from the coverage database. The files will be re-entered into the database when the fasl files (produced by compiling store-coverage-data optimization policy set to 3) are loaded again into the image.

— Function: sb-cover:save-coverage

Returns an opaque representation of the current code coverage state. The only operation that may be done on the state is passing it to restore-coverage. The representation is guaranteed to be readably printable. A representation that has been printed and read back will work identically in restore-coverage.

— Function: sb-cover:save-coverage-in-file pathname

Call save-coverage and write the results of that operation into the file designated by pathname.

— Function: sb-cover:restore-coverage coverage-state

Restore the code coverage data back to an earlier state produced by save-coverage.

— Function: sb-cover:restore-coverage-from-file pathname

read the contents of the file designated by pathname and pass the result to restore-coverage.