LuaUnit is a popular unit-testing framework for Lua, with an interface typical of xUnit libraries (Python unittest, Junit, NUnit, ...). It supports several output formats (Text, TAP, JUnit, ...) to be used directly or work with Continuous Integration platforms (Jenkins, Maven, ...).
OTHER License
by Philippe Fremy
LuaUnit is a popular unit-testing framework for Lua, with an interface typical of xUnit libraries (Python unittest, Junit, NUnit, ...). It supports several output formats (Text, TAP, JUnit, ...) to be used directly or work with Continuous Integration platforms (Jenkins, Hudson, ...).
LuaUnit may be installed as a rock or directly added to your project. For simplicity, LuaUnit is contained into a single-file and has no external dependency.
Tutorial and reference documentation is available on read-the-docs
LuaUnit may also be used as an assertion library, to validate assertions inside a running program. In addition, it provides a pretty stringifier which converts any type into a nicely formatted string (including complex nested or recursive tables).
LuaUnit provides a wide range of assertions and goes into great efforts to provide the most useful output. For example since version 3.3 , comparing lists will provide a detailed difference analysis:
-- lua test code. Can you spot the difference ?
function TestListCompare:test1()
local A = { 121221, 122211, 121221, 122211, 121221, 122212, 121212, 122112, 122121, 121212, 122121 }
local B = { 121221, 122211, 121221, 122211, 121221, 122212, 121212, 122112, 121221, 121212, 122121 }
lu.assertEquals( A, B )
end
$ lua test_some_lists_comparison.lua
TestListCompare.test1 ... FAIL
test/some_lists_comparisons.lua:22: expected:
List difference analysis:
* lists A (actual) and B (expected) have the same size
* lists A and B start differing at index 9
* lists A and B are equal again from index 10
* Common parts:
= A[1], B[1]: 121221
= A[2], B[2]: 122211
= A[3], B[3]: 121221
= A[4], B[4]: 122211
= A[5], B[5]: 121221
= A[6], B[6]: 122212
= A[7], B[7]: 121212
= A[8], B[8]: 122112
* Differing parts:
- A[9]: 122121
+ B[9]: 121221
* Common parts at the end of the lists
= A[10], B[10]: 121212
= A[11], B[11]: 122121
The command-line options provide a flexible interface to select tests by name or patterns, control output format, set verbosity and more. See the documentation .
LuaUnit also provides some dedicated support to scientific computing. See the documentation .
LuaUnit is very well tested: code coverage is 99.5% . The test suite is run on every version of Lua (Lua 5.1 to 5.4, LuaJIT 2.0 and 2.1 beta) and on many OS (Windows Seven, Windows Server 2012, MacOs X and Ubuntu). You can check the continuous build results on Travis-CI and AppVeyor.
LuaUnit is maintained on GitHub: https://github.com/bluebird75/luaunit . We gladly accept feature requests and even better Pull Requests. For more information on LuaUnit development, please check: Developing LuaUnit .
LuaUnit is released under the BSD license.
The main developer can be reached at phil.fremy at free.fr . If you have security issue to report requiring confidentiality, this is the address to use.
Version 3.2 of LuaUnit has been downloaded more than 235 000 times on LuaRocks
LuaUnit is used in some very nice technological products. I like to mention:
SchedMD/Slurm: Slurm is an open-source cluster resource management and job scheduling system that strives to be simple, scalable, portable, fault-tolerant, and interconnect agnostic. On the June 2017 Top 500 computer list, Slurm was performing workload management on six of the ten most powerful computers in the world including the number 1 system, Sunway TaihuLight with 10,649,600 computing cores. LuaUnit is used by Slurm to validate plugins written in Lua. Thanks Douglas Jacobsen to contribute back to LuaUnit. See the GitHub repository of Slurm .
MAD by the CERN: CERN is the European Organization for Nuclear Research, where physicists and engineers are probing the fundamental structure of the universe. MAD is one of the CERN project: MAD aims to be at the forefront of computational physics in the field of particle accelerator design and simulation. Its scripting language is de facto the standard to describe particle accelerators, simulate beam dynamics and optimize beam optics at CERN. Lua is the main language of MAD-ng, the new generatino of MAD. A fork of LuaUnit is used extensively for all MAD calculation and framework validation. Thanks Laurent Deniau for contributing back to LuaUnit. See the GitHub repository of MAD .
LuaRocks
LuaUnit is available on LuaRocks. To install it, you need at least LuaRocks version 2.4.4 (due to old versions of wget being incompatible with GitHub https downloading)
GitHub
The simplest way to install LuaUnit is to fetch the GitHub version:
git clone [email protected]:bluebird75/luaunit.git
Then copy the file luaunit.lua into your project or the Lua libs directory.
The version of the main branch on GitHub is always stable and can be used safely.
assertAlmostEquals()
works also on tables and nested structuresLUAUNIT_OUTPUT
setOutputType()
accepts the xml filename as second argument when using the format junitskip()
and skipIf()
assertErrorMsgContentEquals()
to validate exactly any error messageSTRIP_EXTRA_ENTRIES_IN_STACK_TRACE
assertTableContains()
and assertNotTableContains()
to verify the presence of a given value within a tableTABLE_EQUALS_KEYBYCONTENT
, it did not make senseassertIs()
/assertNotIs()
deals better with protected metatablesassertEquals()
deals better with tables containing cycles of different structureImportant note when upgrading to version 3.1 : assertions functions are no longer exported directly to the global namespace. See documentation for upgrade paths.
Since some people have forked LuaUnit and release some 2.x version, I am jumping the version number to 3.
Unofficial fork from version 1.3 by rjbcomupting