LuaUnit Documentation

When executing tests contained within a table (a test suite), you can use lifecycle methods to manage test state:

• setUp(): Called immediately before each individual test execution. If setUp() fails or encounters an error, the test itself will not be executed, and the failure/error will be reported in the suite.
• tearDown(): Called immediately after each individual test execution. This runs even if the test failed or if setUp() encountered an error. Any failure or error during tearDown() will be reported in the suite.

When comparing tables that use other tables as keys, LuaUnit performs a reference check on the keys rather than just checking the content of the keys.

Even if two key-tables have identical content, they are considered different keys if they are different objects in memory. Consequently, two parent tables containing these 'identical' key-tables will be considered unequal by lu.assertEquals.

local lu = require('luaunit')

local t1 = { 1, 2 }
local t2 = { 1, 2 }

-- These are equal because they have the same content
lu.assertEquals(t1, t2)

-- Using tables as keys
local t3 = { t1 = 'a' }
local t4 = { t2 = 'a' }

-- This fails because t1 and t2 are different table references,
-- even though their content is identical.
lu.assertEquals(t3, t4)

When using test tables, you can define setUp() and tearDown() functions. These are executed before and after every individual test in that table, respectively. They are ideal for preparing resources (like files or database connections) and cleaning up the environment.

Note:

• Errors occurring in setUp() or tearDown() are reported as errors, not failures.
• For compatibility with other frameworks, you may also use setup(), SetUp(), Setup(), teardown(), or TearDown().

TestLogger = {}

function TestLogger:setUp()
    -- Prepare environment
    self.fname = 'mytmplog.log'
    os.remove(self.fname)
end

function TestLogger:testLoggerCreatesFile()
    initLog(self.fname)
    log('toto')
    f = io.open(self.fname, 'r')
    lu.assertNotNil(f)
    f:close()
end

function TestLogger:tearDown()
    -- Cleanup environment
    os.remove(self.fname)
end

To organize large test suites, group related tests into tables. The table name must start with Test or test. Test functions within these tables should be defined using the colon syntax (function TableName:testName) to ensure they have access to the table context.

TestAdd = {}

function TestAdd:testAddPositive()
    lu.assertEquals(add(1,1), 2)
end

function TestAdd:testAddZero()
    lu.assertEquals(add(1,0), 0)
end

To verify code changes, run the unit-test suite using the run_unit_tests.lua script. All proposed changes should pass these tests, and you should add new tests to cover any bug fixes or new functionality.

$ lua run_unit_tests.lua

The nil format suppresses all output during test execution. The only way to determine if tests passed or failed is by checking the command's exit code. This mode is primarily used for LuaUnit's internal validation.

lua my_test_suite_with_failures.lua -o nil --verbose

The TEXT format is the default output for LuaUnit. It provides a compact summary of test results inspired by Python's unittest library.

• Compact mode (default): Prints a single character per test: . for success, F for failure, and E for error. A summary of failures/errors and a final tally are provided at the end.
• Verbose mode (--verbose): Prints the start time, one line per test (ending in Ok, FAIL, or ERROR), and a detailed summary of failures/errors. This is useful when tests produce debug output that needs to be aligned with the test results.

# Default compact output
lua my_test_suite.lua

# Verbose output
lua my_test_suite_with_failures.lua --verbose

You can install LuaUnit using the LuaRocks package manager. This requires LuaRocks version 2.4.4 or higher to ensure compatibility with GitHub HTTPS downloading.

# Use LuaRocks to install the module
luarocks install bluebird75/luaunit