If you run extensive tests on your code, you often want to figure out if the tests exercise all parts of the code. This is called (test) coverage. The file coverage.fs contains tools for measuring the coverage as well as execution frequency.
Code coverage inserts counting code in every basic block (straight-line code sequence) loaded after coverage.fs. Each time that code is run, it increments the counter for that basic block. Later you can show the source file with the counts inserted in these basic blocks.
A simple use of the coverage tools is as follows:
This shows the source program annotated with execution counts (and code that is never executed in red). A more sophisticated usgae is:
gforth coverage.fs source.fs tests1.fs -e "save-cov bye" gforth coverage.fs source.fs -e "load-cov" tests2.fs -e "save-cov bye" gforth coverage.fs source.fs -e "load-cov" tests3.fs -e "bw-cover annotate-cov bye"
This runs the tests in three steps, saving and restoring the coverage
information from one step to the next. Eventually the execution
counts are put in copies of the source file(s), with an appended
extension .cov (e.g., source.fs.cov). The counts are
shown in parentheses (due to bw-cover) rather than in color
(default).
Show code with execution frequencies.
For every file with coverage information, produce a .cov
file that has the execution frequencies inserted. We recommend
to use bw-cover first (with the default
color-cover you get escape sequences in the files).
By default, the counts are shown in colour (using ANSI escape
sequences), but you can use bw-cover to show them in
parenthesized form without escape sequences.
Print execution counts in parentheses (source-code compatible).
Print execution counts in colours (default).
You can save and reload the coverage counters in binary format, to aggregate coverage counters across several test runs of the same program.
Save coverage counters.
Load coverage counters.
In addition, there are the following words that one may want to use in special circumstances.
(Immediate) Turn coverage off temporarily.
(Immediate) End of temporary turned off coverage.
(Immediate) Place a coverage counter here.
(Immediate) A coverage counter for a flag; in the coverage
output you see three numbers behind ?cov: The first is
the number of executions where the top-of-stack was non-zero;
the second is the number of executions where it was zero; the
third is the total number of executions.
Print the percentage of basic blocks loaded after coverage.fs that are executed at least once.
Print raw execution counts.