doc/ref/api-coverage.texi

   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