Commit | Line | Data |
---|---|---|
36b5e394 LC |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 2010 Free Software Foundation, Inc. | |
4 | @c See the file guile.texi for copying conditions. | |
5 | ||
6 | ||
36b5e394 LC |
7 | @node Code Coverage |
8 | @section Code Coverage Reports | |
9 | ||
10 | @cindex code coverage | |
11 | @cindex coverage | |
12 | When writing a test suite for a program or library, it is desirable to know what | |
13 | part of the code is @dfn{covered} by the test suite. The @code{(system vm | |
14 | coverage)} module provides tools to gather code coverage data and to present | |
15 | them, as detailed below. | |
16 | ||
17 | @deffn {Scheme Procedure} with-code-coverage vm thunk | |
18 | Run @var{thunk}, a zero-argument procedure, using @var{vm}; instrument @var{vm} | |
19 | to collect code coverage data. Return code coverage data and the values | |
20 | returned by @var{thunk}. | |
21 | @end deffn | |
22 | ||
23 | @deffn {Scheme Procedure} coverage-data? obj | |
24 | Return @code{#t} if @var{obj} is a @dfn{coverage data} object as returned by | |
25 | @code{with-code-coverage}. | |
26 | @end deffn | |
27 | ||
28 | @deffn {Scheme Procedure} coverage-data->lcov data port #:key modules | |
29 | Traverse code coverage information @var{data}, as obtained with | |
30 | @code{with-code-coverage}, and write coverage information to port in the | |
31 | @code{.info} format used by @url{http://ltp.sourceforge.net/coverage/lcov.php, | |
32 | LCOV}. The report will include all of @var{modules} (or, by default, all the | |
33 | currently loaded modules) even if their code was not executed. | |
34 | ||
35 | The generated data can be fed to LCOV's @command{genhtml} command to produce an | |
36 | HTML report, which aids coverage data visualization. | |
37 | @end deffn | |
38 | ||
39 | Here's an example use: | |
40 | ||
41 | @example | |
42 | (use-modules (system vm coverage) | |
43 | (system vm vm)) | |
44 | ||
45 | (call-with-values (lambda () | |
46 | (with-code-coverage (the-vm) | |
47 | (lambda () | |
48 | (do-something-tricky)))) | |
49 | (lambda (data result) | |
50 | (let ((port (open-output-file "lcov.info"))) | |
51 | (coverage-data->lcov data port) | |
52 | (close file)))) | |
53 | @end example | |
54 | ||
55 | In addition, the module provides low-level procedures that would make it | |
56 | possible to write other user interfaces to the coverage data. | |
57 | ||
58 | @deffn {Scheme Procedures} instrumented-source-files data | |
59 | Return the list of ``instrumented'' source files, i.e., source files whose | |
60 | code was loaded at the time @var{data} was collected. | |
61 | @end deffn | |
62 | ||
63 | @deffn {Scheme Procedures} line-execution-counts data file | |
64 | Return a list of line number/execution count pairs for @var{file}, or | |
65 | @code{#f} if @var{file} is not among the files covered by @var{data}. This | |
66 | includes lines with zero count. | |
67 | @end deffn | |
68 | ||
69 | @deffn {Scheme Procedures} instrumented/executed-lines data file | |
70 | Return the number of instrumented and the number of executed source lines | |
71 | in @var{file} according to @var{data}. | |
72 | @end deffn | |
73 | ||
74 | @deffn {Scheme Procedures} procedure-execution-count data proc | |
75 | Return the number of times @var{proc}'s code was executed, according to | |
76 | @var{data}, or @code{#f} if @var{proc} was not executed. When @var{proc} | |
77 | is a closure, the number of times its code was executed is returned, not | |
78 | the number of times this code associated with this particular closure was | |
79 | executed. | |
80 | @end deffn |