LuaCov
Coverage analysis for Lua scripts

Overview

LuaCov is a simple coverage analyzer for Lua scripts. When a Lua script is run with the luacov module loaded, it generates a stats file with the number of executions of each line of the script and its loaded modules. The luacov command-line script then processes this file generating a report file which allows one to visualize which code paths were not traversed, which is useful for verifying the effectiveness of a test suite.

LuaCov is free software and uses the same license as Lua.

Download

LuaCov can be downloaded via LuaRocks:

luarocks install luacov

LuaCov is written in pure Lua and has no external dependencies.

Instructions

Using LuaCov consists of two steps: running your script to collect coverage data, and then running luacov on the collected data to generate a report.

To collect coverage data, your script needs to load the luacov Lua module. This can be done from the command-line, without modifying your script, like this:

lua -lluacov test.lua
or
lua -erequire('luacov.runner')('myconfigfilename') test.lua

(Alternatively, you can add require("luacov") to the first line of your script.)

Once the script is run, a file called luacov.stats.out is generated. If the file already exists, statistics are added to it. This is useful, for example, for making a series of runs with different input parameters in a test suite. To start the accounting from scratch, just delete the stats file.

To generate a report, just run the luacov command-line script. It expects to find a file named luacov.stats.out in the current directory, and outputs a file named luacov.report.out.

This is an example output of the report file:

============================================================
../test.lua
============================================================

        -- Which branch will run?
1       if 10 > 100 then
0          print("I don't think this line will execute.")
0       else
1          print("Hello, LuaCov!")
1       end

Note that to generate this report, luacov reads the source files. Therefore, it expects to find them in the same location they were when the luacov module ran (the stats file stores the filenames, but not the sources themselves).

LuaCov saves its stats upon normal program termination. If your program is a daemon -- in other words, if it does not terminate normally -- you can use the luacov.tick module, which periodically saves the stats file. For example, to run (on Unix systems) LuaCov on Xavante, just modify the first line of xavante_start.lua so it reads:

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

Credits

LuaCov was originally designed and implemented by Hisham Muhammad as a tool for testing LuaRocks. A number of people have improved it since: see the Git logs for the full list of contributors!

Contact

For more information please contact us. Comments are welcome!

Valid XHTML 1.0!