6.3 Line coverage
The line coverage library provides a means to ascertain exactly how
many times individual clauses are called during the evaluation of a
The library works by placing coverage counters at strategic
points throughout the code being analysed. These counters are
incremented each time the evaluation of a query passes them. There
are three locations in which coverage counters can be inserted.
Locations where coverage counters can be placed
A code block is defined to be a conjunction of predicate calls. ie. a
sequence of goals separated by commas.
At the beginning of a code block.
- Between predicate calls within a code block.
- At the end of a code block.
As previously mentioned, by default, code coverage counters are
inserted before and after every subgoal in the code. For instance, in
four counters would be inserted: before the call to
s, and after
This is the most precise form provided. The counter values do not only
show whether all code points were reached but also whether subgoals
failed or aborted (in which case the counter before a subgoal will
have a higher value than the counter after it). For example, the
result of running the above code is:
p :- point(1), q, point(2), r, point(3), s, point(4).
which indicates that
p :- 43 q, 25 r, 25 s 0 .
q was called 43 times, but succeeded only
r was called 25 times and succeeded always, and
s was called 25 times and never succeeded. Coverage counts of
zero are displayed in red (the final box) because they indicate
unreached code. The format of the display is explained in the next
In order to add the coverage counters to code, it must be compiled with
predicate which can be found in the
ccompile/1 (note the initial `c' stands for
coverage) can be used in place of the normal
predicate to compile a file with coverage counters.
Here we see the results of compiling the n-queens example
given in the previous section.
Once compiled, predicates can be called as usual and will (by default)
have no visible side effects. Internally however, the counters will
be incremented as the execution progresses. To see this in action,
consider issuing the following query having compiled the previously
defined code using
coverage: inserted 22 coverage counters into module eclipse
foo.ecl compiled traceable 5744 bytes in 0.00 seconds
Yes (0.00s cpu)
The default behaviour of the
?- queens([1,2,3,4,5,6,7,8,9], Out).
ccompile/1 predicate is to place
coverage counters as explained above, however such a level of detail
may be unnecessary. If one is interested in reachability analysis the
two argument predicate
can take a list of
which can be used to control the exact manner in which coverage
counters are inserted.
In particular by specifying the
ccompile/2 for a
full list of the available flags.
blocks_only:on, counters will only be inserted at the
beginning and end of code blocks. Reusing the above example this would
result in counters at point(1) and point(4).
This can be useful in tracking down unexpected failures by looking for
exit counters which differ from entry counters, for example.
p :- 43 q, r, s 0 .
To generate an html file
containing the coverage counter results issue the following query.
This will create the result file coverage/queens.html which
can be viewed using any browser. It contains a pretty-printed form of
the source, annotated with the values of the code coverage counters as
described above. An example is shown in figure 6.1.
For extra convenience the
Figure 6.1: Results of running queens([1,2,3,4,5,6,7,8,9],_)
result/0 is provided which will create results for
all files which have been compiled with coverage counters.
generated and viewed results for one run, the coverage counters can be
reset by calling
results for all files which have been compiled with coverage counters.
predicate takes a single argument which is the name of the file to
print the coverage counters for.
The result predicate has a two argument form, the
second argument defining a number of flags which control (amongst
The directory in which to create the results file. Default:
- The format of the results file (html or text). Default:
- See coverage library
library for more details
Figure 6.2: Result generating commands
Yes (0.00s cpu)