LuaCov

• Index

Contents

• Functions
• Fields

Modules

• luacov
• luacov.defaults
• luacov.hook
• luacov.reporter
• luacov.runner
• luacov.stats
• luacov.tick
• luacov.util

Module luacov.runner

Statistics collecting module.

Calling the module table is a shortcut to calling the init function.

Functions

file_included (filename)	Uses LuaCov's configuration to check if a file is included for coverage data collection.
update_stats (old_stats, extra_stats)	Adds stats to an existing file stats table.
debug_hook (_, line_nr[, level])	Debug hook set by LuaCov.
run_report ([configuration])	Runs the reporter specified in configuration.
real_name (filename)	Returns real name for a source file name using luacov.defaults.modules option.
load_config ([configuration])	Loads a valid configuration.
pause ()	Pauses saving data collected by LuaCov's runner.
resume ()	Resumes saving data collected by LuaCov's runner.
with_luacov (f)	Wraps a function, enabling coverage gathering in it explicitly.
init ([configuration])	Initializes LuaCov runner to start collecting data.
shutdown ()	Shuts down LuaCov's runner.
excludefile (name)	Adds a file to the exclude list (see luacov.defaults).
includefile (name)	Adds a file to the include list (see luacov.defaults).
excludetree (name, level)	Adds a tree to the exclude list (see luacov.defaults).
includetree (name, level)	Adds a tree to the include list (see luacov.defaults).

Fields

version

LuaCov version in MAJOR.MINOR.PATCH format.

Functions

file_included (filename)

Uses LuaCov's configuration to check if a file is included for coverage data collection.

Parameters:

• filename name of the file.

Returns:

true if file is included, false otherwise.

update_stats (old_stats, extra_stats)

Adds stats to an existing file stats table.

Parameters:

• old_stats stats to be updated.
• extra_stats another stats table, will be broken during update.

debug_hook (_, line_nr[, level])

Debug hook set by LuaCov. Acknowledges that a line is executed, but does nothing if called manually before coverage gathering is started.

Parameters:

• _ event type, should always be "line".
• line_nr line number.
• level passed to debug.getinfo to get name of processed file, 2 by default. Increase it if this function is called manually from another debug hook. (optional)

Usage:

local function custom_hook(_, line)
   runner.debug_hook(_, line, 3)
   extra_processing(line)
end

run_report ([configuration])

Runs the reporter specified in configuration.

Parameters:

• configuration if string, filename of config file (used to call load_config). If table then config table (see file luacov.default.lua for an example). If configuration.reporter is not set, runs the default reporter; otherwise, it must be a module name in 'luacov.reporter' namespace. The module must contain 'report' function, which is called without arguments. (optional)

real_name (filename)

Returns real name for a source file name using luacov.defaults.modules option.

Parameters:

• filename name of the file.

load_config ([configuration])

Loads a valid configuration.

Parameters:

• configuration user provided config (config-table or filename) (optional)

Returns:

existing configuration if already set, otherwise loads a new config from the provided data or the defaults. When loading a new config, if some options are missing, default values from luacov.defaults are used instead.

pause ()

Pauses saving data collected by LuaCov's runner. Allows other processes to write to the same stats file. Data is still collected during pause.

resume ()

Resumes saving data collected by LuaCov's runner.

with_luacov (f)

Wraps a function, enabling coverage gathering in it explicitly. LuaCov gathers coverage using a debug hook, and patches coroutine library to set it on created threads when under standard Lua, where each coroutine has its own hook. If a coroutine is created using Lua C API or before the monkey-patching, this wrapper should be applied to the main function of the coroutine. Under LuaJIT this function is redundant, as there is only one, global debug hook.

Parameters:

• f a function

Returns:

a function that enables coverage gathering and calls the original function.

Usage:

local coro = coroutine.create(runner.with_luacov(func))

init ([configuration])

Initializes LuaCov runner to start collecting data.

Parameters:

• configuration if string, filename of config file (used to call load_config). If table then config table (see file luacov.default.lua for an example) (optional)

shutdown ()

Shuts down LuaCov's runner. This should only be called from daemon processes or sandboxes which have disabled os.exit and other hooks that are used to determine shutdown.

excludefile (name)

Adds a file to the exclude list (see luacov.defaults). If passed a function, then through debuginfo the source filename is collected. In case of a table it will recursively search the table for a function, which is then resolved to a filename through debuginfo. If the parameter is a string, it will first check if a file by that name exists. If it doesn't exist it will call require(name) to load a module by that name, and the result of require (function or table expected) is used as described above to get the sourcefile.

Parameters:

• name
  • string; literal filename,
  • string; modulename as passed to require(),
  • function; where containing file is looked up,
  • table; module table where containing file is looked up

Returns:

the pattern as added to the list, or nil + error

includefile (name)

Adds a file to the include list (see luacov.defaults).

Parameters:

• name see excludefile

Returns:

the pattern as added to the list, or nil + error

excludetree (name, level)

Adds a tree to the exclude list (see luacov.defaults). If name = 'luacov' and level = nil then module 'luacov' (luacov.lua) and the tree 'luacov' (containing luacov/runner.lua etc.) is excluded. If name = 'pl.path' and level = true then module 'pl' (pl.lua) and the tree 'pl' (containing pl/path.lua etc.) is excluded. NOTE: in case of an 'init.lua' file, the 'level' parameter will always be set

Parameters:

• name see excludefile
• level if truthy then one level up is added, including the tree

Returns:

the 2 patterns as added to the list (file and tree), or nil + error

includetree (name, level)

Adds a tree to the include list (see luacov.defaults).

Parameters:

• name see excludefile
• level see includetree

Returns:

the 2 patterns as added to the list (file and tree), or nil + error

Fields

version

LuaCov version in MAJOR.MINOR.PATCH format.