diff options
Diffstat (limited to 'extras/luacov/README.md')
-rw-r--r-- | extras/luacov/README.md | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/extras/luacov/README.md b/extras/luacov/README.md new file mode 100644 index 0000000..efc31c5 --- /dev/null +++ b/extras/luacov/README.md @@ -0,0 +1,79 @@ +## Overview + +LuaCov is a simple coverage analyzer for [Lua](http://www.lua.org) +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, like Lua, is released under the +[MIT License](http://www.lua.org/license.html). + +## Download and Installation + +LuaCov can be downloaded from its +[LuaForge page](http://luaforge.net/projects/luacov/files). + +It can also be installed using 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 + +Alternatively, you can add `require("luacov")` to the first line +of your script. + +Once the script is run, a file called `lcov.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 `lcov.stats.out` in the current +directory, and outputs a file named `lcov.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](http://www.keplerproject.org/xavante), +just modify the first line of `xavante_start.lua` so it reads: + + #!/usr/bin/env lua -lluacov.tick + +## Credits + +LuaCov was designed and implemented by Hisham Muhammad as a tool for +testing [Luarocks](http://luarocks.luaforge.net). |