2 Racket API

2 Racket API🔗ℹ

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

1	Basic Usage of Cover
2	Racket API
3	Creating Custom Output Formats
	Index