Loading repository data…
Loading repository data…
bluebird75 / repository
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, ...).
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
|CI| |Documentation Status| |Downloads| |License| |CII Best Practices|
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 <https://luarocks.org/modules/bluebird75/luaunit>__ 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 <http://luaunit.readthedocs.org/en/latest/>__.
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:
.. code:: lua
-- 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
.. code:: sh
$ lua test_some_lists_comparison.lua
TestListCompare.test1 ... FAIL test/some_lists_comparisons.lua:22: expected:
List difference analysis:
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 <http://luaunit.readthedocs.io/en/latest/#command-line-options>__
.
LuaUnit also provides some dedicated support to scientific computing.
See the documentation <http://luaunit.readthedocs.io/en/latest/#scientific-computing-and-luaunit>__
.
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.5 and LuaJIT 2.0) and on several OS (Windows Server, MacOs X and Ubuntu)
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 <http://luaunit.readthedocs.org/en/latest/#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.4 of LuaUnit has been downloaded more than 270 000 times on
LuaRocks <https://luarocks.org/modules/bluebird75/luaunit>__
LuaUnit is used in some very nice technological products. I like to mention:
SchedMD/Slurm <https://www.schedmd.com/>: 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 <https://github.com/SchedMD/slurm> .
MAD by the CERN <http://mad.web.cern.ch/mad/>: 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 <https://github.com/MethodicalAcceleratorDesign/MAD> .
NiteHawk <https://github.com/n1tehawk>__AbigailBuccaneer <https://github.com/AbigailBuccaneer>__Juan Julián Merelo Guervós <https://github.com/JJ>__Naoyuki Totani <https://github.com/ntotani>__Jennal <https://github.com/Jennal>__George Zhao <https://github.com/zhaozg>__Victor Seva <https://github.com/linuxmaniac>__Urs Breu <https://github.com/ubreu>__Douglas Jacobsen <https://github.com/dmjacobsen>__Mayama Takeshi <https://github.com/MayamaTakeshi>__LuaRocks
LuaUnit is available on
LuaRocks <https://luarocks.org/modules/bluebird75/luaunit>__. 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 git@github.com:bluebird75/luaunit.git
Then copy the file luaunit.lua into your project or in the Lua libs directory (if you are using regular Lua) or in the lua directory if you are using LuaJIT.
The version of the main branch on GitHub is always stable and can be used safely.
History
.. _version-35---26-march-2026:
Version 3.5 - 26 March 2026
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- support for Lua 5.5
- The name convention used to detect tests and test methods can now be
adjusted with options ``--test-prefix``, ``--test-suffix``,
``--method-prefix``
- add possiblity to pass command-line arguments to
``runSuitByInstances()``
- bugfix:
- LuaUnit correctly escapes invalid XML characters when outputting XML
- better error management when errors occurs during ``setupSuite()``,
``teardownSuite()``, ``setupClass()`` and ``teardownClass()``
.. _version-34---02-march-2021:
Version 3.4 - 02 March 2021
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- support for Lua 5.4
- ``assertAlmostEquals()`` works also on tables and nested structures
- choose test output style with environment variable ``LUAUNIT_OUTPUT``
- ``setOutputType()`` accepts the xml filename as second argument when
using the format junit
- improve printing of table information in case of cycles
- add ability to skip tests with ``skip()`` and ``skipIf()``
- detect attempts to exit the test suite before it is finished running
- add ``assertErrorMsgContentEquals()`` to validate exactly any error
message
- filter out some stack entries when printing assertions (useful when
embedding LuaUnit inside another test layer) with
``STRIP_EXTRA_ENTRIES_IN_STACK_TRACE``
- add ``assertTableContains()`` and ``assertNotTableContains()`` to
verify the presence of a given value within a table
- remove option ``TABLE_EQUALS_KEYBYCONTENT``, it did not make sense
- bugfix:
- ``assertIs()``/``assertNotIs()`` deals better with protected
metatables
- ``assertEquals()`` deals better with tables containing cycles of
different structure
- fix table length comparison for table returning inconsistent length
.. _version-33---6-march-2018:
Version 3.3 - 6. March 2018
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- General
- when comparing lists with ``assertEquals()``, failure message provides
an advanced comparison of the lists
- ``assertErrorMsgEquals()`` can check for error raised as tables
- tests may be finished early with ``fail()``, ``failIf()``,
``success()`` or ``successIf()``
- improve printing of recursive tables
- improvements and fixes to JUnit and TAP output
- stricter ``assertTrue()`` and ``assertFalse()``: they only succeed
with boolean values
- add ``assertEvalToTrue()`` and ``assertEvalToFalse()`` with
previous ``assertTrue()``/``assertFalse()`` behavior of coercing to
boolean before asserting
- all assertion functions accept an optional extra message, to be
printed along the failure
- New command-line arguments:
- can now shuffle tests with --shuffle or -s
- possibility to repeat tests (for example to trigger a JIT), with
--repeat NUM or -r NUM
- more flexible test selection with inclusion (--pattern / -p) or
exclusion (--exclude / -x) or combination of both
- Scientific computing dedicated support (see documentation):
- provide the machine epsilon in ``lu.EPS``
- new functions: ``assertNan()``, ``assertInf()``,
``assertPlusInf()``, ``assertMinusInf()``, ``assertPlusZero()``,
``assertMinusZero()``
- in ``assertAlmostEquals( a, b, margin )``, ``margin`` no longer
provides a default value of ``1E-11``; the machine epsilon is used
instead
- Platform and continuous integration support:
- validate LuaUnit on MacOs platform (thank to Travis CI)
- validate LuaUnit with 32 bits numbers (floats) and 64 bits numbers
(double)
- add test coverage measurements thank to coveralls.io . Status:
99.76% of the code is verified.
- use cache for AppVeyor and Travis builds
- support for luarocks doc command
- General doc improvements (detailed description of all output, more
cross-linking between sections)
.. _version-32---12-jul-2016:
Version 3.2 - 12. Jul 2016
^^^^^^^^^^^^^^^^^^^^^^^^^^
- distinguish between failures (failed assertion) and errors
- add command-line option to stop on first error or failure
- support for new versions: Lua 5.3 and LuaJIT (2.0, 2.1 beta)
- validation of all lua versions on Travis CI and AppVeyor
- added compatibility layer with forked luaunit v2.x
- added documentation about development process
- improved support for table containing keys of type table
- small bug fixes, several internal improvements
.. _version-31---10-mar-2015:
Version 3.1 - 10 Mar. 2015
^^^^^^^^^^^^^^^^^^^^^^^^^^
- luaunit no longer pollutes global namespace, unless defining
``EXPORT_ASSERT_TO_GLOBALS`` to true
- fixes and validation of JUnit XML generation
- strip luaunit internal information from stacktrace
- general improvements of test results with duration and other details
- improve printing for tables, with an option to always print table id
- fix printing of recursive tables
**Important note when upgrading to version 3.1** : assertions functions
are no longer exported directly to the global namespace. See
documentation for upgrade paths.
.. _version-30---9-oct-2014:
Version 3.0 - 9. Oct 2014
^^^^^^^^^^^^^^^^^^^^^^^^^
Since some people have forked LuaUnit and release some 2.x version, I am
jumping the version number to 3.
- moved to Github
- full documentation available in text, html and pdf at
read-the-docs.org
- new output format: JUnit
- much better table assertions
- new assertions for strings, with patterns and case insensitivity:
``assertStrContains()``, ``assertNotStrContains()``,
``assertNotStrIContains()``, ``assertStrIContains()``,
``assertStrMatches()``
- new assertions for floats: ``assertAlmostEquals()``,
``assertNotAlmostEquals()``
- type assertions: ``assertIsString()``, ``assertIsNumber()``, ...
- error assertions: ``assertErrorMsgEqu