% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(test_cover): Clause coverage analysis}

\label{sec:testcover}

\begin{tags}
    \tag{bug}
Relies heavily on SWI-Prolog internals. We have considered using
a meta-interpreter for this purpose, but it is nearly impossible
to do 100\% complete meta-interpretation of Prolog. Example
problem areas include handling cuts in control-structures
and calls from non-interpreted meta-predicates.
\end{tags}

The purpose of this module is to find which part of the program has been
used by a certain goal. Usage is defined in terms of clauses for which
the \textit{head unification} succeeded. For each clause we count how often it
succeeded and how often it failed. In addition we track all \textit{call
sites}, creating goal-by-goal annotated clauses.

This module relies on the SWI-Prolog tracer hooks. It modifies these
hooks and collects the results, after which it restores the debugging
environment. This has some limitations:

\begin{itemize}
    \item The performance degrades significantly (about 10 times)
    \item It is not possible to use the debugger during coverage analysis
    \item The cover analysis tool is currently not thread-safe.
\end{itemize}

The result is represented as a list of clause-references. As the
references to clauses of dynamic predicates cannot be guaranteed, these
are omitted from the result.\vspace{0.7cm}

\begin{description}
    \predicate[semidet]{show_coverage}{1}{:Goal}
\nodescription
    \predicate[semidet]{show_coverage}{2}{:Goal, +Options}
\nodescription
    \predicate[semidet]{show_coverage}{2}{:Goal, +Modules:list(atom)}
Report on coverage by \arg{Goal}. \arg{Goal} is executed as in \predref{once}{1}. \arg{Options}
processed:

\begin{description}
    \termitem{modules}{+Modules}
Provide a detailed report on \arg{Modules}. For backwards
compatibility this is the same as providing a list of
modules in the second argument.
    \termitem{annotate}{+Bool}
Create an annotated file for the detailed results.
This is implied if the \const{ext} or \const{dir} option are
specified.
    \termitem{ext}{+Ext}
Extension to use for the annotated file. Default is
`.cov`.
    \termitem{dir}{+Dir}
Dump the annotations in the given directory. If not
given, the annotated files are created in the same
directory as the source file. Each clause that is
related to a physical line in the file is annotated
with one of:

\begin{quote}
\begin{tabulary}{0.9\textwidth}{|l|L|}
\hline
\#\#\# & Clause was never executed. \\
++N & Clause was entered N times and always succeeded \\
--N & Clause was entered N times and never succeeded \\
+N-M & Clause has succeeded N times and failed M times \\
+N*M & Clause was entered N times and succeeded M times \\
\hline
\end{tabulary}
\end{quote}

All \textit{call sites} are annotated using the same conventions,
except that \verb$---$ is used to annotate subgoals that were
never called.
    \termitem{line_numbers}{Boolean}
If \const{true} (default), add line numbers to the annotated file.
    \termitem{color}{Boolean}
Controls using ANSI escape sequences to color the output
in the annotated source. Default is \const{true}.
\end{description}

    \predicate[semidet,multifile]{report_hook}{2}{+Succeeded, +Failed}
This hook is called after the data collection. It is passed a list
of objects that have succeeded as well as a list of objects that
have failed. The objects are one of

\begin{description}
    \termitem{\arg{ClauseRef}}{}
The specified clause
    \termitem{call_site}{ClauseRef, PC, PI}
A call was make in \arg{ClauseRef} at the given program counter to
the predicate indicated by \arg{PI}.
\end{description}
\end{description}