WOLFRAM

Wolfram Language & System Documentation Center

Coverage Tutorial

The functions in the Instrumentation` context provide support for coverage reporting of WL code.

CoverageInstrument[inputDir,outputDir]instrument WL code for coverage reporting
CoverageEvaluate[expr]evaluate expr for coverage reporting
CoverageProcess[data,outputDir,lCovData]process coverage data

Reporting coverage of WL code.

First we need to load the Instrumentation` package
Wolfram Language code: Needs["Instrumentation`"]
Next we must instrument the code for coverage reporting.
Wolfram Language code: Quiet[DeleteDirectory[FileNameJoin[{$TemporaryDirectory, "Collatz-example"}], DeleteContents -> True], {DeleteDirectory::nodir}]; tmp = CreateDirectory[FileNameJoin[{$TemporaryDirectory, "Collatz-example"}]]
Wolfram Language code: paclet = PacletFind["Instrumentation"][[1]];
Wolfram Language code: file = File[paclet["AssetLocation", "Collatz"]];
Copy the original files to a temporary location.
Wolfram Language code: CreateDirectory[FileNameJoin[{tmp, "Collatz-orig", "Collatz"}], CreateIntermediateDirectories -> True]; CopyFile[file, FileNameJoin[{tmp, "Collatz-orig", "Collatz", "Collatz.m"}]]
Instrument the code and collect the baseline data.
Wolfram Language code: baselineData = CoverageInstrument[FileNameJoin[{tmp, "Collatz-orig", "Collatz"}], FileNameJoin[{tmp, "Collatz-coverage", "Collatz"}]];
Verify baselineData is present
Wolfram Language code: baselineData
Verify that instrumented code is found
Wolfram Language code: PrependTo[$Path, FileNameJoin[{tmp, "Collatz-coverage", "Collatz"}]];
Wolfram Language code: FindFile["Collatz`"]
Evaluate an expression for coverage reporting. We include the Needs because we want to include the code that runs at startup in the coverage report.
Wolfram Language code: {res, runData} = CoverageEvaluate[Needs["Collatz`"];Collatz`Collatz[27]];
Verify runData
Wolfram Language code: runData
Process the coverage data
Wolfram Language code: CoverageProcess[baselineData, FileNameJoin[{tmp, "Collatz-coverage", "Collatz"}], "coverage-baseline.lcov"]
Wolfram Language code: CoverageProcess[runData, FileNameJoin[{tmp, "Collatz-coverage", "Collatz"}], "coverage-run.lcov"]
Now you must run the lcov and genhtml commands on the command-line.
lcov -a coverage-baseline.lcov -a coverage-run.lcov -o coverage-combined.lcov
genhtml --num-spaces 4 coverage-combined.lcov -o report
Below is a transcript of running the commands on a machine.
user@usermaclap Collatz % lcov -a coverage-baseline.lcov -a coverage-run.lcov -o coverage-combined.lcov
Combining tracefiles.
Reading tracefile coverage-baseline.lcov
Reading tracefile coverage-run.lcov
Writing data to coverage-combined.lcov
Summary coverage rate:
  lines......: 80.0% (4 of 5 lines)
  functions..: 80.0% (4 of 5 functions)
  branches...: no data found
  
user@usermaclap Collatz % genhtml --num-spaces 4 coverage-combined.lcov -o report
Reading data file coverage-combined.lcov
Found 1 entries.
Found common filename prefix "/private/var/folders/d_/tyn9s8p54fz2_zfvtx_frkb00000gn/T/Collatz-example/Collatz-orig"
Writing .css and .png files.
Generating output.
Processing file Collatz/Collatz.m
Writing directory view page.
Overall coverage rate:
  lines......: 80.0% (4 of 5 lines)
  functions..: 80.0% (4 of 5 functions)
user@usermaclap Collatz %
The report is generated in the report directory. The toplevel index page shows the line coverage and function coverage of each directory.

You can dig down to individual files and see line coverage and function coverage.