|
| 1 | +[](https://ci.appveyor.com/project/bluebird75/luaunit) |
| 2 | +[](https://travis-ci.org/bluebird75/luaunit) |
| 3 | +[](https://readthedocs.org/projects/luaunit/?badge=latest) |
| 4 | +[](https://coveralls.io/github/bluebird75/luaunit?branch=master) |
| 5 | +[](https://luarocks.org/modules/bluebird75/luaunit) |
| 6 | +[](LICENSE.txt) |
| 7 | +[](https://bestpractices.coreinfrastructure.org/projects/2756) |
| 8 | + |
| 9 | +## LuaUnit |
| 10 | +by Philippe Fremy |
| 11 | + |
| 12 | +LuaUnit is a popular unit-testing framework for Lua, with an interface typical |
| 13 | +of xUnit libraries (Python unittest, Junit, NUnit, ...). It supports |
| 14 | +several output formats (Text, TAP, JUnit, ...) to be used directly or work with Continuous Integration platforms |
| 15 | +(Jenkins, Hudson, ...). |
| 16 | + |
| 17 | +LuaUnit may be installed as a [rock](https://luarocks.org/modules/bluebird75/luaunit) or directly added to your project. |
| 18 | +For simplicity, LuaUnit is contained into a single-file and has no external dependency. |
| 19 | + |
| 20 | +Tutorial and reference documentation is available on |
| 21 | +[read-the-docs](http://luaunit.readthedocs.org/en/latest/) |
| 22 | + |
| 23 | +LuaUnit may also be used as an assertion library, to validate assertions inside a running program. In addition, it provides |
| 24 | +a pretty stringifier which converts any type into a nicely formatted string (including complex nested or recursive tables). |
| 25 | + |
| 26 | +## More details |
| 27 | + |
| 28 | +LuaUnit provides a wide range of assertions and goes into great efforts to provide the most useful output. For example |
| 29 | +since version 3.3 , comparing lists will provide a detailed difference analysis: |
| 30 | + |
| 31 | + -- lua test code. Can you spot the difference ? |
| 32 | + function TestListCompare:test1() |
| 33 | + local A = { 121221, 122211, 121221, 122211, 121221, 122212, 121212, 122112, 122121, 121212, 122121 } |
| 34 | + local B = { 121221, 122211, 121221, 122211, 121221, 122212, 121212, 122112, 121221, 121212, 122121 } |
| 35 | + lu.assertEquals( A, B ) |
| 36 | + end |
| 37 | + |
| 38 | + $ lua test_some_lists_comparison.lua |
| 39 | + |
| 40 | + TestListCompare.test1 ... FAIL |
| 41 | + test/some_lists_comparisons.lua:22: expected: |
| 42 | + |
| 43 | + List difference analysis: |
| 44 | + * lists A (actual) and B (expected) have the same size |
| 45 | + * lists A and B start differing at index 9 |
| 46 | + * lists A and B are equal again from index 10 |
| 47 | + * Common parts: |
| 48 | + = A[1], B[1]: 121221 |
| 49 | + = A[2], B[2]: 122211 |
| 50 | + = A[3], B[3]: 121221 |
| 51 | + = A[4], B[4]: 122211 |
| 52 | + = A[5], B[5]: 121221 |
| 53 | + = A[6], B[6]: 122212 |
| 54 | + = A[7], B[7]: 121212 |
| 55 | + = A[8], B[8]: 122112 |
| 56 | + * Differing parts: |
| 57 | + - A[9]: 122121 |
| 58 | + + B[9]: 121221 |
| 59 | + * Common parts at the end of the lists |
| 60 | + = A[10], B[10]: 121212 |
| 61 | + = A[11], B[11]: 122121 |
| 62 | + |
| 63 | + |
| 64 | +The command-line options provide a flexible interface to select tests by name or patterns, control output |
| 65 | +format, set verbosity and more. See [the documentation](http://luaunit.readthedocs.io/en/latest/#command-line-options) . |
| 66 | + |
| 67 | +LuaUnit also provides some dedicated support to scientific computing. See [the documentation](http://luaunit.readthedocs.io/en/latest/#scientific-computing-and-luaunit) . |
| 68 | + |
| 69 | +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) |
| 70 | +and on many OS (Windows Seven, Windows Server 2012, MacOs X and Ubuntu). You can check the continuous build results on [Travis-CI](https://travis-ci.org/bluebird75/luaunit) and [AppVeyor](https://ci.appveyor.com/project/bluebird75/luaunit). |
| 71 | + |
| 72 | +LuaUnit is maintained on GitHub: https://github.com/bluebird75/luaunit . We gladly accept feature requests and even better Pull Requests. |
| 73 | +For more information on LuaUnit development, please check: [Developing LuaUnit](http://luaunit.readthedocs.org/en/latest/#developing-luaunit) . |
| 74 | + |
| 75 | +LuaUnit is released under the BSD license. |
| 76 | + |
| 77 | +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. |
| 78 | + |
| 79 | +## LuaUnit successes |
| 80 | + |
| 81 | +Version 3.2 of LuaUnit has been downloaded more than 235 000 times on [LuaRocks](https://luarocks.org/modules/bluebird75/luaunit) |
| 82 | + |
| 83 | +LuaUnit is used in some very nice technological products. I like to mention: |
| 84 | + |
| 85 | +* [SchedMD/Slurm](https://www.schedmd.com/): Slurm is an open-source cluster resource management and job scheduling |
| 86 | +system that strives to be simple, scalable, portable, fault-tolerant, and interconnect agnostic. On the June 2017 Top 500 computer |
| 87 | +list, Slurm was performing workload management on six of the ten most powerful computers in the world including the number 1 system, |
| 88 | +Sunway TaihuLight with 10,649,600 computing cores. LuaUnit is used by Slurm to validate plugins written in Lua. Thanks Douglas Jacobsen |
| 89 | +to contribute back to LuaUnit. See the [GitHub repository of Slurm](https://github.com/SchedMD/slurm) . |
| 90 | + |
| 91 | +* [MAD by the CERN](http://mad.web.cern.ch/mad/): CERN is the European Organization for Nuclear Research, where physicists and engineers are |
| 92 | +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 |
| 93 | +the field of particle accelerator design and simulation. Its scripting language is de facto the standard to describe particle accelerators, simulate |
| 94 | +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 |
| 95 | +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) . |
| 96 | + |
| 97 | +## Contributors |
| 98 | +* [NiteHawk](https://github.com/n1tehawk) |
| 99 | +* [AbigailBuccaneer](https://github.com/AbigailBuccaneer) |
| 100 | +* [Juan Julián Merelo Guervós](https://github.com/JJ) |
| 101 | +* [Naoyuki Totani](https://github.com/ntotani) |
| 102 | +* [Jennal](https://github.com/Jennal) |
| 103 | +* [George Zhao](https://github.com/zhaozg) |
| 104 | +* kbuschelman |
| 105 | +* [Victor Seva](https://github.com/linuxmaniac) |
| 106 | +* [Urs Breu](https://github.com/ubreu) |
| 107 | +* Jim Anderson |
| 108 | +* [Douglas Jacobsen](https://github.com/dmjacobsen) |
| 109 | +* [Mayama Takeshi](https://github.com/MayamaTakeshi) |
| 110 | + |
| 111 | + |
| 112 | +## Installation |
| 113 | + |
| 114 | +**LuaRocks** |
| 115 | + |
| 116 | +LuaUnit is available on [LuaRocks](https://luarocks.org/modules/bluebird75/luaunit). To install it, you need at least |
| 117 | +LuaRocks version 2.4.4 (due to old versions of wget being incompatible with GitHub https downloading) |
| 118 | + |
| 119 | +**GitHub** |
| 120 | + |
| 121 | +The simplest way to install LuaUnit is to fetch the GitHub version: |
| 122 | + |
| 123 | + git clone git@github.com:bluebird75/luaunit.git |
| 124 | + |
| 125 | +Then copy the file luaunit.lua into your project or the Lua libs directory. |
| 126 | + |
| 127 | +The version of the main branch on GitHub is always stable and can be used safely. |
| 128 | + |
| 129 | +### History |
| 130 | + |
| 131 | +#### Version 3.4 - 02 March 2021 |
| 132 | +* support for Lua 5.4 |
| 133 | +* assertAlmostEquals() works also on tables and nested structures |
| 134 | +* choose test output style with environment variable LUAUNIT_OUTPUT |
| 135 | +* setOutputType() accepts the xml filename as second argument when using the format junit |
| 136 | +* improve printing of table information in case of cycles |
| 137 | +* add ability to skip tests with XXX |
| 138 | +* detect attempts to exit the test suite before it is finished running |
| 139 | +* add assertErrorMsgContentEquals() to validate exactly any error message |
| 140 | +* filter out some stack entries when printing assertions (useful when embedding LuaUnit inside another test layer) with XXX |
| 141 | +* add assertTableContains() and assertNotTableContains() to verify the presence of a given value within a table XXX |
| 142 | +* remove option TABLE_EQUALS_KEYBYCONTENT, it did not make sense |
| 143 | +* bugfix: |
| 144 | + * assertIs()/assertNotIs() deals better with protected metatables |
| 145 | + * assertEquals() deals better with tables containing cycles of different structure |
| 146 | + * fix table length comparison for table returning inconsistent length |
| 147 | + |
| 148 | + |
| 149 | +#### Version 3.3 - 6. March 2018 |
| 150 | +* General |
| 151 | + * when comparing lists with assertEquals(), failure message provides an advanced comparison of the lists |
| 152 | + * assertErrorMsgEquals() can check for error raised as tables |
| 153 | + * tests may be finished early with fail(), failIf(), success() or successIf() |
| 154 | + * improve printing of recursive tables |
| 155 | + * improvements and fixes to JUnit and TAP output |
| 156 | + * stricter assertTrue() and assertFalse(): they only succeed with boolean values |
| 157 | + * add assertEvalToTrue() and assertEvalToFalse() with previous assertTrue()/assertFalse() behavior of coercing to boolean before asserting |
| 158 | + ** all assertion functions accept an optional extra message, to be printed along the failure |
| 159 | +* New command-line arguments: |
| 160 | + * can now shuffle tests with --shuffle or -s |
| 161 | + * possibility to repeat tests (for example to trigger a JIT), with --repeat NUM or -r NUM |
| 162 | + * more flexible test selection with inclusion (--pattern / -p) or exclusion (--exclude / -x) or combination of both |
| 163 | +* Scientific computing dedicated support (see documentation): |
| 164 | + * provide the machine epsilon in lu.EPS |
| 165 | + * new functions: assertNan(), assertInf(), assertPlusInf(), assertMinusInf(), assertPlusZero(), assertMinusZero() |
| 166 | + * in assertAlmostEquals( a, b, margin ), margin no longer provides a default value of 1E-11, the machine epsilon is used instead |
| 167 | +* Platform and continuous integration support: |
| 168 | + * validate LuaUnit on MacOs platform (thank to Travis CI) |
| 169 | + * validate LuaUnit with 32 bits numbers (floats) and 64 bits numbers (double) |
| 170 | + * add test coverage measurements thank to coveralls.io . Status: 99.76% of the code is verified. |
| 171 | + * use cache for AppVeyor and Travis builds |
| 172 | + * support for luarocks doc command |
| 173 | +* General doc improvements (detailed description of all output, more cross-linking between sections) |
| 174 | + |
| 175 | + |
| 176 | +#### Version 3.2 - 12. Jul 2016 |
| 177 | +* distinguish between failures (failed assertion) and errors |
| 178 | +* add command-line option to stop on first error or failure |
| 179 | +* support for new versions: Lua 5.3 and LuaJIT (2.0, 2.1 beta) |
| 180 | +* validation of all lua versions on Travis CI and AppVeyor |
| 181 | +* added compatibility layer with forked luaunit v2.x |
| 182 | +* added documentation about development process |
| 183 | +* improved support for table containing keys of type table |
| 184 | +* small bug fixes, several internal improvements |
| 185 | + |
| 186 | + |
| 187 | +#### Version 3.1 - 10 Mar. 2015 |
| 188 | +* luaunit no longer pollutes global namespace, unless defining EXPORT_ASSERT_TO_GLOBALS to true |
| 189 | +* fixes and validation of JUnit XML generation |
| 190 | +* strip luaunit internal information from stacktrace |
| 191 | +* general improvements of test results with duration and other details |
| 192 | +* improve printing for tables, with an option to always print table id |
| 193 | +* fix printing of recursive tables |
| 194 | + |
| 195 | +**Important note when upgrading to version 3.1** : assertions functions are |
| 196 | +no longer exported directly to the global namespace. See documentation for upgrade |
| 197 | +paths. |
| 198 | + |
| 199 | + |
| 200 | +#### Version 3.0 - 9. Oct 2014 |
| 201 | + |
| 202 | +Since some people have forked LuaUnit and release some 2.x version, I am |
| 203 | +jumping the version number to 3. |
| 204 | + |
| 205 | +- moved to Github |
| 206 | +- full documentation available in text, html and pdf at read-the-docs.org |
| 207 | +- new output format: JUnit |
| 208 | +- much better table assertions |
| 209 | +- new assertions for strings, with patterns and case insensitivity: assertStrContains, |
| 210 | + assertNotStrContains, assertNotStrIContains, assertStrIContains, assertStrMatches |
| 211 | +- new assertions for floats: assertAlmostEquals, assertNotAlmostEquals |
| 212 | +- type assertions: assertIsString, assertIsNumber, ... |
| 213 | +- error assertions: assertErrorMsgEquals, assertErrorMsgContains, assertErrorMsgMatches |
| 214 | +- improved error messages for several assertions |
| 215 | +- command-line options to select test, control output type and verbosity |
| 216 | + |
| 217 | + |
| 218 | +#### Version 2.0 |
| 219 | +Unofficial fork from version 1.3 by rjbcomupting |
| 220 | +- lua 5.2 module style, without global namespace pollution |
| 221 | +- setUp() may be named Setup() or setup() |
| 222 | +- tearDown() may be named Teardown() or teardown() |
| 223 | +- wrapFunction() may be called WrapFunctions() or wrap_functions() |
| 224 | +- run() may also be called Run() |
| 225 | +- table deep comparision (also available in 1.4) |
| 226 | +- control verbosity with setVerbosity() SetVerbosity() and set_verbosity() |
| 227 | +- More assertions: |
| 228 | + - is<Type>, is_<type>, assert<Type> and assert_<type> (e.g. assert( LuaUnit.isString( getString() ) ) |
| 229 | + - assertNot<Type> and assert_not_<type> |
| 230 | + |
| 231 | + |
| 232 | +#### Version 1.5 - 8. Nov 2012 |
| 233 | +- compatibility with Lua 5.1 and 5.2 |
| 234 | +- better object model internally |
| 235 | +- a lot more of internal tests |
| 236 | +- several internal bug fixes |
| 237 | +- make it easy to customize the test output |
| 238 | +- running test functions no longer requires a wrapper |
| 239 | +- several level of verbosity |
| 240 | + |
| 241 | + |
| 242 | +#### Version 1.4 - 26. Jul 2012 |
| 243 | +- table deep comparison |
| 244 | +- switch from X11 to more popular BSD license |
| 245 | +- add TAP output format for integration into Jenkins |
| 246 | +- official repository now on GitHub |
| 247 | + |
| 248 | + |
| 249 | +#### Version 1.3 - 30. Oct 2007 |
| 250 | +- port to lua 5.1 |
| 251 | +- iterate over the test classes, methods and functions in the alphabetical order |
| 252 | +- change the default order of expected, actual in assertEquals (adjustable with USE_EXPECTED_ACTUAL_IN_ASSERT_EQUALS). |
| 253 | + |
| 254 | + |
| 255 | +#### Version 1.2 - 13. Jun 2005 |
| 256 | +- first public release |
| 257 | + |
| 258 | + |
| 259 | +#### Version 1.1 |
| 260 | +- move global variables to internal variables |
| 261 | +- assertion order is configurable between expected/actual or actual/expected |
| 262 | +- new assertion to check that a function call returns an error |
| 263 | +- display the calling stack when an error is spotted |
| 264 | +- two verbosity level, like in python unittest |
| 265 | + |
| 266 | + |
| 267 | + |
0 commit comments