DOCUMENTATION

   1
   2 To use the lunit unit testing framework copy these files to your
   3 lua search path or include it to your package:
   4
   5         lunit
   6         lunit.lua
   7         lunit-console.lua
   8
   9
  10 To write a testcase, open the framework using require. The "lunit" shell script
  11 works hard to find the "lunit.lua" and "lunit-console.lua" in all cases.
  12
  13         require "lunit"
  14
  15
  16 Lunit uses the lua-5.1 module system. A testcase is a arbitrarily named module
  17 marked with "lunit.testcase" as a testcase. An example:
  18
  19         require "lunit"
  20
  21         module( "my_testcase", lunit.testcase, package.seeall )
  22
  23
  24 The tests itself in a testcase are functions whose names must begin
  25 or end with 'test'. The function names are case insensitive. Example:
  26
  27         require "lunit"
  28
  29         module( "my_testcase", lunit.testcase, package.seeall )
  30
  31         function FirstTest()
  32           -- Test code goes here
  33         end
  34
  35         function test_something()
  36             -- Test code goes here
  37         end
  38
  39
  40 Inside the test functions you use asserts to test your code or package.
  41 Lunit defines 26 assert functions:
  42
  43         fail( [msg] )
  44
  45               Always fails.
  46
  47         assert( assertion, [msg] )
  48
  49               Fails, if 'assertion' is false or nil.
  50
  51         assert_true( actual, [msg] )
  52
  53               Fails, if 'actual' isn't true.
  54
  55         assert_false( actual, [msg] )
  56
  57               Fails, if 'actual' isn't false. (Even fails if 'actual' is
  58               a nil value!)
  59
  60         assert_equal( expected, actual, [msg] )
  61
  62               Fails, if 'actual' is different from 'expected'. Make sure
  63               that you don't mix 'expected' and 'actual' because they are
  64               used to build a nice error message.
  65
  66         assert_not_equal( unexpected, actual, [msg] )
  67
  68               Fails, if 'actual' and 'unexpected' are equal.
  69
  70         assert_match( pattern, actual, [msg] )
  71
  72               Fails, if the string 'actual' doesn't match 'pattern'.
  73
  74         assert_not_match( pattern, actual, [msg] )
  75
  76               Fails, if the string 'actual' match 'pattern'.
  77
  78         assert_nil( actual, [msg] )
  79
  80               Fails, if 'actual' isn't a nil value.
  81
  82         assert_not_nil( actual, [msg] )
  83
  84               Fails, if 'actual' is a nil value.
  85
  86         assert_boolean( actual, [msg] )
  87
  88               Fails, if 'actual' isn't true or false.
  89
  90         assert_not_boolean( actual, [msg] )
  91
  92               Fails, if 'actual' is true or false.
  93
  94         assert_number( actual, [msg] )
  95
  96               Fails, if 'actual' isn't a number.
  97
  98         assert_not_number( actual, [msg] )
  99
 100               Fails, if 'actual' is a number.
 101
 102         assert_string( actual, [msg] )
 103
 104               Fails, if 'actual' isn't a string.
 105
 106         assert_not_string( actual, [msg] )
 107
 108               Fails, if 'actual' is a string.
 109
 110         assert_table( actual, [msg] )
 111
 112               Fails, if 'actual' isn't a table.
 113
 114         assert_not_table( actual, [msg] )
 115
 116               Fails, if 'actual' is a table.
 117
 118         assert_function( actual, [msg] )
 119
 120               Fails, if 'actual' isn't a function.
 121
 122         assert_not_function( actual, [msg] )
 123
 124               Fails, if 'actual' is a function.
 125
 126         assert_thread( actual, [msg] )
 127
 128               Fails, if 'actual' isn't a thread (created by
 129               coroutine.create or coroutine.wrap).
 130
 131         assert_not_thread( actual, [msg] )
 132
 133               Fails, if 'actual' is a thread.
 134
 135         assert_userdata( actual, [msg] )
 136
 137               Fails, if 'actual' isn't userdata.
 138
 139         assert_not_userdata( actual, [msg] )
 140
 141               Fails, if 'actual' is userdata.
 142
 143         assert_error( [msg], func )
 144
 145               Fails, if 'func' doesn't raises an error (using error()).
 146
 147         assert_pass( [msg], func )
 148
 149               Fails, if 'func' raises an error.
 150
 151
 152 All assert functions take an optional message as the last argument. Only
 153 assert_pass() and assert_error() require the optional message as the first
 154 argument. The last argument of these two are functions.
 155
 156 There are also useful functions to test for the type of a value:
 157
 158         is_nil( actual )
 159         is_boolean( actual )
 160         is_number( actual )
 161         is_string( actual )
 162         is_table( actual )
 163         is_function( actual )
 164         is_thread( actual )
 165         is_userdata( actual )
 166
 167 These all returns true if 'actual' is of correct type, otherwise false.
 168
 169 You use the assert functions and the is_type functions in your tests to check
 170 your code or package. Example:
 171
 172         require "lunit"
 173
 174         module( "my_testcase", lunit.testcase, package.seeall )
 175
 176         function FirstTest()
 177           local result = compute_some_value()
 178           assert_string( result )
 179           assert_equal("foobar", result)
 180         end
 181
 182         function test_something()
 183           local result = flip_coin()    -- flip_coin returns at random 0 or 1
 184           assert_number(result)
 185           if result == 0 then
 186             -- ok
 187           elseif result == 1 then
 188             -- ok
 189           else
 190             fail("flip_coin: invalid number: "..tostring(result))
 191           end
 192         end
 193
 194
 195 You can define the functions setup() and teardown() if you have to allocate
 196 some resources or obtain some handles for your tests.
 197 The setup() function is called before every test and teardown() is
 198 called after every test. Example:
 199
 200         require "lunit"
 201
 202         module( "resource_testcase", lunit.testcase, package.seeall )
 203
 204         local orig_content, handle
 205
 206         function setup()
 207           orig_content = { "row 1", "row 2", "row 3" }
 208           handle = database_open("test.db")
 209           database_create_table(handle, ...)
 210           database_fill_table(handle, orig_content, ...)
 211         end
 212
 213         function teardown()
 214           database_drop_table(handle, ...)
 215           database_close(handle)
 216           handle = nil
 217           orig_content = nil
 218           delete_file("test.db")
 219         end
 220
 221         function test_select()
 222           local content = database_select(handle, ...)
 223           assert_table( content )
 224           assert_equal( orig_content, content )
 225         end
 226
 227         function test_insert()
 228           database_insert(handle, "row 4", ...)
 229           local content = database_select(handle, ...)
 230           assert_table( content )
 231           assert_equal( { "row 1", "row 2", "row 3", "row 4" }, content )
 232         end
 233
 234         function test_delete()
 235           database_delete(handle, "row 2", ...)
 236           local content = database_select(handle, ...)
 237           assert_table( content )
 238           assert_equal( { "row 1", "row 3" }, content )
 239         end
 240
 241
 242 To run your testcases, simply use the shell script "lunit". Example:
 243
 244         # ./lunit my_testcase.lua
 245