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`.