| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Guile Reference Manual. |
| 3 | @c Copyright (C) 2010, 2013 Free Software Foundation, Inc. |
| 4 | @c See the file guile.texi for copying conditions. |
| 5 | |
| 6 | |
| 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 thunk |
| 18 | Run @var{thunk}, a zero-argument procedure, while instrumenting Guile's |
| 19 | virtual machine to collect code coverage data. Return code coverage |
| 20 | data and the values 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 |
| 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 |