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.