LuaCov Reference

# 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.

generated by LDoc 1.5.0 Last updated 2024-12-04 15:36:32