LuaCov Coverage Analyzer

LuaCov normally saves statistics upon normal program termination. For daemons or processes that do not terminate normally, you must enable periodic saving to prevent data loss.

Option 1: Using the .luacov config Set tick = true in your .luacov file.

Option 2: Using the command line (Unix) Run your script using the luacov.tick module instead of the standard luacov module:

#!/usr/bin/env lua -lluacov.tick

To output the coverage report as an HTML document instead of the default text format, add the following settings to your .luacov configuration file:

reporter = "html"
reportfile = "luacov.report.html"

You can prevent certain lines from being marked as 'missed' in the report by wrapping them in special inline comments. This is useful for code paths that are intentionally not covered by tests (e.g., debug conditions).

Use -- luacov: disable to start ignoring coverage for a block and -- luacov: enable to resume it.

if SOME_DEBUG_CONDITION_THAT_IS_ALWAYS_FALSE_IN_TESTS then
   -- luacov: disable

   -- Lines here are not marked as missed even though they are not covered.

   -- luacov: enable
end

To collect coverage data, the luacov module must be loaded when running your Lua script. This generates a luacov.stats.out file containing execution counts for each line.

If the file already exists, new statistics are appended to it. To reset coverage, delete the luacov.stats.out file.

You can load the module in two ways:

1. Via Command Line (Recommended): Use the -l flag to load the module without modifying your source code.
2. Via Source Code: Add require("luacov") to the very first line of your script.

lua -lluacov test.lua

You can install the pure Lua version of LuaCov using Luarocks. For improved performance and analysis accuracy, you should install the cluacov package, which includes experimental C extensions.

To install the standard version:

luarocks install luacov

To install the high-performance version:

luarocks install cluacov

You can filter the files included in your coverage report by providing one or more Lua patterns as positional arguments to the luacov command. These patterns are treated as inclusions.

Internally, the CLI normalizes these patterns by converting backslashes to forward slashes and stripping the .lua extension before adding them to the include list in the configuration.

# Filter to a specific directory
luacov path/to/module

LuaCov can be configured using a .luacov file located in the project directory. This file should be a Lua script that sets options as globals or returns a table containing the options.

Alternatively, you can specify a custom configuration path using the LUACOV_CONFIG environment variable.

Example Configuration: This example configures coverage for a specific module foo and its submodules located in the src directory.

modules = {
   ["foo"] = "src/foo/init.lua",
   ["foo.*"] = "src"
}

The luacov command-line tool processes collected Lua coverage statistics and generates reports.

To perform coverage accounting, you must first launch your Lua programs with the -lluacov flag. Once your programs have finished running, use luacov to generate the report.

By default, luacov reports on every Lua file encountered during the execution. You can filter which files are included in the report by passing Lua patterns as command-line arguments or by using a configuration file.

# Example: Report only on modules in the foo/bar subtree
luacov foo/bar

The include key in the luacov.config.lua configuration file allows you to specify a list of files or directories that should be included in the code coverage analysis. Provide an array of strings representing the paths to the files or directories you want to track.

include = { "test2" }

Once luacov.stats.out has been generated, run the luacov command-line tool to process the data into a report (default filename: luacov.report.out).

Usage: luacov [-c=configfile] [filename...]

• -c=configfile: Path to a configuration file.
• filename...: Lua patterns used to include specific files in the report. Specifying a filename here is equivalent to adding it to the include list in a configuration file (the .lua extension is stripped automatically).

The luacov CLI supports the following options to control report generation:

Options:
   -c filename, --config filename
        Use a config file, .luacov by default. For details see luacov.defaults module.

   -r name, --reporter name
        Use a custom reporter - a module in luacov.reporter.* namespace.

   -h, --help
        Show this help message and exit.