elisp: Coverage Testing
17.2.13 Coverage Testing
------------------------
Edebug provides rudimentary coverage testing and display of execution
frequency.
Coverage testing works by comparing the result of each expression
with the previous result; each form in the program is considered covered
if it has returned two different values since you began testing coverage
in the current Emacs session. Thus, to do coverage testing on your
program, execute it under various conditions and note whether it behaves
correctly; Edebug will tell you when you have tried enough different
conditions that each form has returned two different values.
Coverage testing makes execution slower, so it is only done if
‘edebug-test-coverage’ is non-‘nil’. Frequency counting is performed
for all executions of an instrumented function, even if the execution
mode is Go-nonstop, and regardless of whether coverage testing is
enabled.
Use ‘C-x X =’ (‘edebug-display-freq-count’) to display both the
coverage information and the frequency counts for a definition. Just
‘=’ (‘edebug-temp-display-freq-count’) displays the same information
temporarily, only until you type another key.
-- Command: edebug-display-freq-count
This command displays the frequency count data for each line of the
current definition.
It inserts frequency counts as comment lines after each line of
code. You can undo all insertions with one ‘undo’ command. The
counts appear under the ‘(’ before an expression or the ‘)’ after
an expression, or on the last character of a variable. To simplify
the display, a count is not shown if it is equal to the count of an
earlier expression on the same line.
The character ‘=’ following the count for an expression says that
the expression has returned the same value each time it was
evaluated. In other words, it is not yet covered for coverage
testing purposes.
To clear the frequency count and coverage data for a definition,
simply reinstrument it with ‘eval-defun’.
For example, after evaluating ‘(fac 5)’ with a source breakpoint, and
setting ‘edebug-test-coverage’ to ‘t’, when the breakpoint is reached,
the frequency data looks like this:
(defun fac (n)
(if (= n 0) (edebug))
;#6 1 = =5
(if (< 0 n)
;#5 =
(* n (fac (1- n)))
;# 5 0
1))
;# 0
The comment lines show that ‘fac’ was called 6 times. The first ‘if’
statement returned 5 times with the same result each time; the same is
true of the condition on the second ‘if’. The recursive call of ‘fac’
did not return at all.