▼Cover:   A test coverage tool
►2 Racket API
On this page:
2.1 A High Level API
coverage/  c
test-files!
get-test-coverage
irrelevant-submodules
generate-html-coverage
environment?
current-cover-environment
make-cover-environment
  top  ← prev  up  next → 

2 Racket API

 (require cover) package: cover-lib

Warning: The API presented here is unstable, and may change without warning.

In addition to being a raco tool, Cover provides racket bindings for running tests and collecting coverage information. The following are the basic functions of test coverage.

2.1 A High Level API

value

coverage/c : contract?

 = 
(-> any/c exact-positive-integer?
     (or/c 'covered 'uncovered 'irrelevant))
Coverage information is represented as a mapping from a file’s key and a character location to whether or not that location in the file was covered.

The files key is determined by the first non-#f syntax-source of the program after reading it. Typically this is the string? for of the absolute path of the file path.

The character locations are 1 indexed.

procedure

(test-files! [#:submod submod] files ...) → any

  submod : (or/c symbol? (listof symbol?)) = 'test
  files : 
(or/c path-string?
      (list/c path-string?
               (vectorof string? #:immutable #t)))
Runs all given files and each submodule submod (if it exists), storing the coverage information. If the path is paired with a vector then that vector is used as the current-command-line-arguments when executing that file. This vector must be immutable and not wrapped by a chaperone? or impersonator?, nor may its elements be wrapped in a chaperone? or impersonator?. The function returns false if any tests fail. Test coverage information is still collected when test fail. Test coverage info is added to existing coverage info.

procedure

(get-test-coverage [environment]) → coverage/c

  environment : environment? = (current-cover-environment)
Gets the current coverage information.

There are three possible results for coverage:

  • 'irrelevant — The location is not considered relevant to coverage information. It is either not in the coverage information; is in a submodule specified by irrelevant-submodules; is a begin-for-syntax form; or lexes (in the sense of that language’s color-lexer) as a comment or whitespace.

  • 'covered — The location is not 'irrelevant and is covered

  • 'uncovered — The location is not 'uncovered and is not covered

value

irrelevant-submodules : (parameter/c (or/c #f (listof symbol?)))

A parameter that controls with submodules are considered irrelevant by get-test-coverage. It defaults to #f, which tells make-covered? to consider all submodules irrelevant. If its value is a list, then each element of that list is the name of a submodule to be considered irrelevant.

procedure

(generate-html-coverage c files [p]) → any

  c : coverage/c
  files : (listof path-string?)
  p : path-string? = "coverage"
Generates coverage information as formatted html. Equivalent to the specifications of the -c argument to raco cover. Uses make-covered? to determine file coverage.

procedure

(environment? v) → any/c

  v : any/c
Tests if the given value is a coverage environment.

parameter

(current-cover-environment) → environment?

(current-cover-environment environment) → void?
  environment : environment?
 = (make-cover-environment)
The current coverage environment. Replacing this has the effect of clearing the coverage table and any loaded files.

procedure

(make-cover-environment) → environment?

Make a new coverage environment

  top  ← prev  up  next →