with-coverage

Arguments: ( &rest funcs) &body body

Executes body and returns the result. As a side-effect, the functions specified by the funcs list (either as function objects or as function specs) are instrumented with breakpoints that will determine how well those functions are being exercised in the body form. When the body form is finished, statitics are printed on how good the coverage is.

Certain additional tools must be activated. The compiler switch save-source-level-debug-info-switch must be true during compilation (which is the default happens when the debug optimization quality is 3). Further source file recording must be on, that is *record-source-file-info* and *load-source-file-info* must both be true (if source file info is recorded but not loaded, you will be prompted for the name of the relevant fasl file).

Example script

(with-open-file (ff "cov-test.cl"
		 :direction :output
		 :if-exists :supersede)
  (setq *load-source-file-info* t *record-source-file-info* t)
  (write-string "

(eval-when (load compile eval) (require :coverage))

(eval-when (compile) (declaim (optimize (debug 3))))

(defun foo ()
  (let ((x (random 3)))
    (cond ((zerop x) (write-string \"yes \"))
          (t (bar \"no \")))))

(defun bar (x)
  (if (string= x \"yes \")
      (progn (write-string x) (write-string \"!\"))
    (write-string x)))
" ff))

(compile-file "cov-test.cl")
(load "cov-test.fasl")

(excl::with-coverage (foo bar)
  (funcall 'foo)
  (funcall 'foo))

;; The last form produces the following output (what you see
;; if you try this may differ in detail):

;; Found 9 applicable records for #<Function foo>:
  pc 0: (defun foo ()
          (let ((x (random 3)))
            (cond ((zerop x) (write-string yes )) (t (bar no )))))
  pc 31: (let ((x (random 3)))
           (cond ((zerop x) (write-string yes )) (t (bar no ))))
  pc 31: (random 3)
  (duplicate)
  pc 56: ((x (random 3)) x nil)
  pc 56: (cond ((zerop x) (write-string yes )) (t (bar no )))
  (duplicate)
  pc 56: (zerop x)
  (duplicate)
  pc 65: (write-string yes )
  pc 108: (bar no )
  pc 84: (defun foo ()
           (let ((x (random 3)))
             (cond ((zerop x) (write-string yes )) (t (bar no )))))
;; Found 6 applicable records for #<Function bar>:
  pc 0: (defun bar (x)
          (if (string= x yes )
              (progn (write-string x) (write-string !))
            (write-string x)))
  pc 37: (string= x yes )
  pc 53: (progn (write-string x) (write-string !))
  pc 53: (write-string x)
  (duplicate)
  pc 64: (write-string !)
  pc 88: (write-string x)
;; Starting executing of ((funcall 'foo) (funcall 'foo))
no no 
;; Finished executing.

Coverage report for #<Function foo>:
    Not hit: (write-string "yes ")
  subtotal = 88%  (8 of 9 breakpoints hit).

Coverage report for #<Function bar>:
    Not hit: (write-string "!")
    Not hit: (write-string x)
    Not hit: (progn (write-string x) (write-string "!"))
  subtotal = 50%  (3 of 6 breakpoints hit).
Total coverage = 73%  (11 of 15 breakpoints hit).
"no "
cl-user(6): 

See Coverage analysis in Allegro CL in miscellaneous.htm.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 8.2 release.
Created 2016.6.21.