To use the lunit unit testing framework copy these files to your

lua search path or include it to your package:

        lunit

        lunit.lua

        lunit-console.lua

To write a testcase, open the framework using require. The "lunit" shell script

works hard to find the "lunit.lua" and "lunit-console.lua" in all cases.

        require "lunit"

Lunit uses the lua-5.1 module system. A testcase is a arbitrarily named module

marked with "lunit.testcase" as a testcase. An example:

        require "lunit"

        module( "my_testcase", lunit.testcase, package.seeall )

The tests itself in a testcase are functions whose names must begin

or end with 'test'. The function names are case insensitive. Example:

        require "lunit"

        module( "my_testcase", lunit.testcase, package.seeall )

        function FirstTest()

          -- Test code goes here

        end

        function test_something()

            -- Test code goes here

        end

Inside the test functions you use asserts to test your code or package.

Lunit defines 26 assert functions:

        fail( [msg] )

              Always fails.

        assert( assertion, [msg] )

              Fails, if 'assertion' is false or nil.

        assert_true( actual, [msg] )

              Fails, if 'actual' isn't true.

        assert_false( actual, [msg] )

              Fails, if 'actual' isn't false. (Even fails if 'actual' is

              a nil value!)

        assert_equal( expected, actual, [msg] )

              Fails, if 'actual' is different from 'expected'. Make sure

              that you don't mix 'expected' and 'actual' because they are

              used to build a nice error message.

        assert_not_equal( unexpected, actual, [msg] )

              Fails, if 'actual' and 'unexpected' are equal.

        assert_match( pattern, actual, [msg] )

              Fails, if the string 'actual' doesn't match 'pattern'.

        assert_not_match( pattern, actual, [msg] )

              Fails, if the string 'actual' match 'pattern'.

        assert_nil( actual, [msg] )

              Fails, if 'actual' isn't a nil value.

        assert_not_nil( actual, [msg] )

              Fails, if 'actual' is a nil value.

        assert_boolean( actual, [msg] )

              Fails, if 'actual' isn't true or false.

        assert_not_boolean( actual, [msg] )

              Fails, if 'actual' is true or false.

        assert_number( actual, [msg] )

              Fails, if 'actual' isn't a number.

        assert_not_number( actual, [msg] )

              Fails, if 'actual' is a number.

        assert_string( actual, [msg] )

              Fails, if 'actual' isn't a string.

        assert_not_string( actual, [msg] )

              Fails, if 'actual' is a string.

        assert_table( actual, [msg] )

              Fails, if 'actual' isn't a table.

        assert_not_table( actual, [msg] )

              Fails, if 'actual' is a table.

        assert_function( actual, [msg] )

              Fails, if 'actual' isn't a function.

        assert_not_function( actual, [msg] )

              Fails, if 'actual' is a function.

        assert_thread( actual, [msg] )

              Fails, if 'actual' isn't a thread (created by

              coroutine.create or coroutine.wrap).

        assert_not_thread( actual, [msg] )

              Fails, if 'actual' is a thread.

        assert_userdata( actual, [msg] )

              Fails, if 'actual' isn't userdata.

        assert_not_userdata( actual, [msg] )

              Fails, if 'actual' is userdata.

        assert_error( [msg], func )

              Fails, if 'func' doesn't raises an error (using error()).

        assert_pass( [msg], func )

              Fails, if 'func' raises an error.

All assert functions take an optional message as the last argument. Only 

assert_pass() and assert_error() require the optional message as the first

argument. The last argument of these two are functions.

There are also useful functions to test for the type of a value:

        is_nil( actual )

        is_boolean( actual )

        is_number( actual )

        is_string( actual )

        is_table( actual )

        is_function( actual )

        is_thread( actual )

        is_userdata( actual )

These all returns true if 'actual' is of correct type, otherwise false. 

You use the assert functions and the is_type functions in your tests to check

your code or package. Example:

        require "lunit"

        module( "my_testcase", lunit.testcase, package.seeall )

        function FirstTest()

          local result = compute_some_value()

          assert_string( result )

          assert_equal("foobar", result)

        end

        function test_something()

          local result = flip_coin()	-- flip_coin returns at random 0 or 1

          assert_number(result)

          if result == 0 then

            -- ok

          elseif result == 1 then

            -- ok

          else

            fail("flip_coin: invalid number: "..tostring(result))

          end

        end

You can define the functions setup() and teardown() if you have to allocate

some resources or obtain some handles for your tests.

The setup() function is called before every test and teardown() is

called after every test. Example:

        require "lunit"

        module( "resource_testcase", lunit.testcase, package.seeall )

        local orig_content, handle

        function setup()

          orig_content = { "row 1", "row 2", "row 3" }

          handle = database_open("test.db")

          database_create_table(handle, ...)

          database_fill_table(handle, orig_content, ...)

        end

        function teardown()

          database_drop_table(handle, ...)

          database_close(handle)

          handle = nil

          orig_content = nil

          delete_file("test.db")

        end

        function test_select()

          local content = database_select(handle, ...)

          assert_table( content )

          assert_equal( orig_content, content )

        end

        function test_insert()

          database_insert(handle, "row 4", ...)

          local content = database_select(handle, ...)

          assert_table( content )

          assert_equal( { "row 1", "row 2", "row 3", "row 4" }, content )

        end

        function test_delete()

          database_delete(handle, "row 2", ...)

          local content = database_select(handle, ...)

          assert_table( content )

          assert_equal( { "row 1", "row 3" }, content )

        end

To run your testcases, simply use the shell script "lunit". Example:

        # ./lunit my_testcase.lua