released version 0.5
[lunit.git] / DOCUMENTATION
blobbcf33762e57bdd6190bec78d8d2f88bb7e618808
2 To use the lunit unit testing framework copy these files to your
3 lua search path or include it to your package:
5         lunit
6         lunit.lua
7         lunit-console.lua
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.
13         require "lunit"
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:
19         require "lunit"
21         module( "my_testcase", lunit.testcase, package.seeall )
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:
27         require "lunit"
29         module( "my_testcase", lunit.testcase, package.seeall )
31         function FirstTest()
32           -- Test code goes here
33         end
35         function test_something()
36             -- Test code goes here
37         end
40 Inside the test functions you use asserts to test your code or package.
41 Lunit defines 26 assert functions:
43         fail( [msg] )
45               Always fails.
47         assert( assertion, [msg] )
49               Fails, if 'assertion' is false or nil.
51         assert_true( actual, [msg] )
53               Fails, if 'actual' isn't true.
55         assert_false( actual, [msg] )
57               Fails, if 'actual' isn't false. (Even fails if 'actual' is
58               a nil value!)
60         assert_equal( expected, actual, [msg] )
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.
66         assert_not_equal( unexpected, actual, [msg] )
68               Fails, if 'actual' and 'unexpected' are equal.
70         assert_match( pattern, actual, [msg] )
72               Fails, if the string 'actual' doesn't match 'pattern'.
74         assert_not_match( pattern, actual, [msg] )
76               Fails, if the string 'actual' match 'pattern'.
78         assert_nil( actual, [msg] )
80               Fails, if 'actual' isn't a nil value.
82         assert_not_nil( actual, [msg] )
84               Fails, if 'actual' is a nil value.
86         assert_boolean( actual, [msg] )
88               Fails, if 'actual' isn't true or false.
90         assert_not_boolean( actual, [msg] )
92               Fails, if 'actual' is true or false.
94         assert_number( actual, [msg] )
96               Fails, if 'actual' isn't a number.
98         assert_not_number( actual, [msg] )
100               Fails, if 'actual' is a number.
102         assert_string( actual, [msg] )
104               Fails, if 'actual' isn't a string.
106         assert_not_string( actual, [msg] )
108               Fails, if 'actual' is a string.
110         assert_table( actual, [msg] )
112               Fails, if 'actual' isn't a table.
114         assert_not_table( actual, [msg] )
116               Fails, if 'actual' is a table.
118         assert_function( actual, [msg] )
120               Fails, if 'actual' isn't a function.
122         assert_not_function( actual, [msg] )
124               Fails, if 'actual' is a function.
126         assert_thread( actual, [msg] )
128               Fails, if 'actual' isn't a thread (created by
129               coroutine.create or coroutine.wrap).
131         assert_not_thread( actual, [msg] )
133               Fails, if 'actual' is a thread.
135         assert_userdata( actual, [msg] )
137               Fails, if 'actual' isn't userdata.
139         assert_not_userdata( actual, [msg] )
141               Fails, if 'actual' is userdata.
143         assert_error( [msg], func )
145               Fails, if 'func' doesn't raises an error (using error()).
147         assert_pass( [msg], func )
149               Fails, if 'func' raises an error.
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.
156 There are also useful functions to test for the type of a value:
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 )
167 These all returns true if 'actual' is of correct type, otherwise false. 
169 You use the assert functions and the is_type functions in your tests to check
170 your code or package. Example:
172         require "lunit"
174         module( "my_testcase", lunit.testcase, package.seeall )
176         function FirstTest()
177           local result = compute_some_value()
178           assert_string( result )
179           assert_equal("foobar", result)
180         end
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
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:
200         require "lunit"
202         module( "resource_testcase", lunit.testcase, package.seeall )
204         local orig_content, handle
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
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
221         function test_select()
222           local content = database_select(handle, ...)
223           assert_table( content )
224           assert_equal( orig_content, content )
225         end
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
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
242 To run your testcases, simply use the shell script "lunit". Example:
244         # ./lunit my_testcase.lua