Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
554 lines (497 sloc) 17.7 KB
--[[
luaunit.lua
Description: A unit testing framework
Homepage: http://phil.freehackers.org/luaunit/
Initial author: Ryu, Gwang (http://www.gpgstudy.com/gpgiki/LuaUnit)
Lot of improvements by Philippe Fremy <phil@freehackers.org>
More improvements by Ryan P. <rjpcomputing@gmail.com>
Version: 2.0
License: X11 License, see LICENSE.txt
Changes between 2.0 and 1.3:
- This is a major update that has some breaking changes to make it much more easy to use and code in many different styles
- Made the module only touch the global table for the asserts. You now use the module much more like Lua 5.2 when you require it.
You need to store the LuaUnit table after you require it to allow you access to the LuaUnit methods and variables.
(ex. local LuaUnit = require( "luaunit" ))
- Made changes to the style of which LuaUnit forced users to code there test classes. It now is more layed back and give the ability to code in a few styles.
- Made "testable" classes able to start with 'test' or 'Test' for their name.
- Made "testable" methods able to start with 'test' or 'Test' for their name.
- Made testClass:setUp() methods able to be named with 'setUp' or 'Setup' or 'setup'.
- Made testClass:tearDown() methods able to be named with 'tearDown' or 'TearDown' or 'teardown'.
- Made LuaUnit.wrapFunctions() function able to be called with 'wrapFunctions' or 'WrapFunctions' or 'wrap_functions'.
- Made LuaUnit:run() method able to be called with 'run' or 'Run'.
- Added the ability to tell if tables are equal using assertEquals. This uses a deep compare, not just the equality that they are the same memory address.
- Added LuaUnit.is<Type> and LuaUnit.is_<type> helper functions. (e.g. assert( LuaUnit.isString( getString() ) )
- Added assert<Type> and assert_<type>
- Added assertNot<Type> and assert_not_<type>
- Added _VERSION variable to hold the LuaUnit version
- Added LuaUnit:setVerbosity(lvl) method to the LuaUnit table to allow you to control the verbosity now. If lvl is greater than 1 it will give verbose output.
This can be called from alias of LuaUnit.SetVerbosity() and LuaUnit:set_verbosity().
- Moved wrapFunctions to the LuaUnit module table (e.g. local LuaUnit = require( "luaunit" ); LuaUnit.wrapFunctions( ... ) )
- Fixed the verbosity to actually format in a way that is closer to other unit testing frameworks I have used.
NOTE: This is not the only way, I just thought the old output was way to verbose and duplicated the errors.
- Made the errors only show in the "test report" section (at the end of the run)
Changes between 1.3 and 1.2a:
- port to lua 5.1
- use orderedPairs() to iterate over a table in the right order
- change the order of expected, actual in assertEquals() and the default value of
USE_EXPECTED_ACTUAL_IN_ASSERT_EQUALS. This can be adjusted with
USE_EXPECTED_ACTUAL_IN_ASSERT_EQUALS.
Changes between 1.2a and 1.2:
- fix: test classes were not run in the right order
Changes between 1.2 and 1.1:
- tests are now run in alphabetical order
- fix a bug that would prevent all tests from being run
Changes between 1.1 and 1.0:
- internal variables are not global anymore
- you can choose between assertEquals( actual, expected) or assertEquals(
expected, actual )
- you can assert for an error: assertError( f, a, b ) will assert that calling
the function f(a,b) generates an error
- display the calling stack when an error is spotted
- a dedicated class collects and displays the result, to provide easy
customisation
- two verbosity level, like in python unittest
]]--
-- SETUP -----------------------------------------------------------------------
--
local argv = arg
local typenames = { "Nil", "Boolean", "Number", "String", "Table", "Function", "Thread", "Userdata" }
--[[ Some people like assertEquals( actual, expected ) and some people prefer
assertEquals( expected, actual ).
]]--
USE_EXPECTED_ACTUAL_IN_ASSERT_EQUALS = USE_EXPECTED_ACTUAL_IN_ASSERT_EQUALS or true
-- HELPER FUNCTIONS ------------------------------------------------------------
--
local function tablePrint(tt, indent, done)
done = done or {}
indent = indent or 0
if type(tt) == "table" then
local sb = {}
for key, value in pairs(tt) do
table.insert(sb, string.rep(" ", indent)) -- indent it
if type(value) == "table" and not done[value] then
done[value] = true
table.insert(sb, "[\""..key.."\"] = {\n");
table.insert(sb, tablePrint(value, indent + 2, done))
table.insert(sb, string.rep(" ", indent)) -- indent it
table.insert(sb, "}\n");
elseif "number" == type(key) then
table.insert(sb, string.format("\"%s\"\n", tostring(value)))
else
table.insert(sb, string.format(
"%s = \"%s\"\n", tostring(key), tostring(value)))
end
end
return table.concat(sb)
else
return tt .. "\n"
end
end
local function toString( tbl )
if "nil" == type( tbl ) then
return tostring(nil)
elseif "table" == type( tbl ) then
return tablePrint(tbl)
elseif "string" == type( tbl ) then
return tbl
else
return tostring(tbl)
end
end
local function deepCompare(t1, t2, ignore_mt)
local ty1 = type(t1)
local ty2 = type(t2)
if ty1 ~= ty2 then return false end
-- non-table types can be directly compared
if ty1 ~= 'table' and ty2 ~= 'table' then return t1 == t2 end
-- as well as tables which have the metamethod __eq
local mt = getmetatable(t1)
if not ignore_mt and mt and mt.__eq then return t1 == t2 end
for k1,v1 in pairs(t1) do
local v2 = t2[k1]
if v2 == nil or not deepCompare(v1,v2) then return false end
end
for k2,v2 in pairs(t2) do
local v1 = t1[k2]
if v1 == nil or not deepCompare(v1,v2) then return false end
end
return true
end
-- Order of testing
local function __genOrderedIndex( t )
local orderedIndex = {}
for key,_ in pairs(t) do
table.insert( orderedIndex, key )
end
table.sort( orderedIndex )
return orderedIndex
end
local function orderedNext(t, state)
-- Equivalent of the next() function of table iteration, but returns the
-- keys in the alphabetic order. We use a temporary ordered key table that
-- is stored in the table being iterated.
--print("orderedNext: state = "..tostring(state) )
if state == nil then
-- the first time, generate the index
t.__orderedIndex = __genOrderedIndex( t )
local key = t.__orderedIndex[1]
return key, t[key]
end
-- fetch the next value
local key = nil
for i = 1,#t.__orderedIndex do
if t.__orderedIndex[i] == state then
key = t.__orderedIndex[i+1]
end
end
if key then
return key, t[key]
end
-- no more value to return, cleanup
t.__orderedIndex = nil
return
end
local function orderedPairs(t)
-- Equivalent of the pairs() function on tables. Allows to iterate
-- in order
return orderedNext, t, nil
end
-- ASSERT FUNCTIONS ------------------------------------------------------------
--
function assertError(f, ...)
-- assert that calling f with the arguments will raise an error
-- example: assertError( f, 1, 2 ) => f(1,2) should generate an error
local has_error, error_msg = not pcall( f, ... )
if has_error then return end
error( "No error generated", 2 )
end
assert_error = assertError
function assertEquals(actual, expected)
-- assert that two values are equal and calls error else
if not USE_EXPECTED_ACTUAL_IN_ASSERT_EQUALS then
expected, actual = actual, expected
end
if "table" == type(actual) then
if not deepCompare(actual, expected, true) then
error("table expected: \n"..toString(expected)..", actual: \n"..toString(actual))
end
else
if actual ~= expected then
local function wrapValue( v )
if type(v) == 'string' then return "'"..v.."'" end
return tostring(v)
end
local errorMsg
--if type(expected) == 'string' then
-- errorMsg = "\nexpected: "..wrapValue(expected).."\n"..
-- "actual : "..wrapValue(actual).."\n"
--else
errorMsg = "expected: "..wrapValue(expected)..", actual: "..wrapValue(actual)
--end
--print(errorMsg)
error(errorMsg, 2)
end
end
end
assert_equals = assertEquals
-- assert_<type> functions
for _, typename in ipairs(typenames) do
local tName = typename:lower()
local assert_typename = "assert"..typename
_G[assert_typename] = function(actual, msg)
local actualtype = type(actual)
if actualtype ~= tName then
local errorMsg = tName.." expected but was a "..actualtype
if msg then
errorMsg = msg.."\n"..errorMsg
end
error(errorMsg, 2)
end
return actual
end
-- Alias to lower underscore naming
_G["assert_"..tName] = _G[assert_typename]
end
-- assert_not_<type> functions
for _, typename in ipairs(typenames) do
local tName = typename:lower()
local assert_not_typename = "assertNot"..typename
_G[assert_not_typename] = function(actual, msg)
if type(actual) == tName then
local errorMsg = tName.." not expected but was one"
if msg then
errorMsg = msg.."\n"..errorMsg
end
error(errorMsg, 2)
end
end
-- Alias to lower underscore naming
_G["assert_not_"..tName] = _G[assert_not_typename]
end
-- UNITRESULT CLASS ------------------------------------------------------------
--
local UnitResult = { -- class
failureCount = 0,
testCount = 0,
errorList = {},
currentClassName = "",
currentTestName = "",
testHasFailure = false,
verbosity = 1
}
function UnitResult:displayClassName()
--if self.verbosity == 0 then print("") end
print(self.currentClassName)
end
function UnitResult:displayTestName()
if self.verbosity == 0 then
io.stdout:write(".")
else
io.stdout:write((" [%s] "):format(self.currentTestName))
end
end
function UnitResult:displayFailure(errorMsg)
if self.verbosity == 0 then
io.stdout:write("F")
else
--print(errorMsg)
print("", "Failed")
end
end
function UnitResult:displaySuccess()
if self.verbosity == 0 then
io.stdout:write(".")
else
print("", "Ok")
end
end
function UnitResult:displayOneFailedTest(failure)
local testName, errorMsg = unpack(failure)
print(">>> "..testName.." failed")
print(errorMsg)
end
function UnitResult:displayFailedTests()
if #self.errorList == 0 then return end
print("Failed tests:")
print("-------------")
for i,v in ipairs(self.errorList) do self.displayOneFailedTest(i, v) end
end
function UnitResult:displayFinalResult()
if self.verbosity == 0 then print("") end
print("=========================================================")
self:displayFailedTests()
local failurePercent, successCount
if self.testCount == 0 then
failurePercent = 0
else
failurePercent = 100 * self.failureCount / self.testCount
end
local successCount = self.testCount - self.failureCount
print( string.format("Success : %d%% - %d / %d",
100-math.ceil(failurePercent), successCount, self.testCount) )
return self.failureCount
end
function UnitResult:startClass(className)
self.currentClassName = className
self:displayClassName()
-- indent status messages
if self.verbosity == 0 then io.stdout:write("\t") end
end
function UnitResult:startTest(testName)
self.currentTestName = testName
self:displayTestName()
self.testCount = self.testCount + 1
self.testHasFailure = false
end
function UnitResult:addFailure( errorMsg )
self.failureCount = self.failureCount + 1
self.testHasFailure = true
table.insert( self.errorList, { self.currentTestName, errorMsg } )
self:displayFailure( errorMsg )
end
function UnitResult:endTest()
if not self.testHasFailure then
self:displaySuccess()
end
end
-- class UnitResult end
-- LUAUNIT CLASS ---------------------------------------------------------------
--
local LuaUnit = {
result = UnitResult,
_VERSION = "2.0"
}
-- Sets the verbosity level
-- @param lvl {number} If greater than 0 there will be verbose output. Defaults to 0
function LuaUnit:setVerbosity(lvl)
self.result.verbosity = lvl or 0
assert("number" == type(self.result.verbosity), ("bad argument #1 to 'setVerbosity' (number expected, got %s)"):format(type(self.result.verbosity)))
end
-- Other alias's
LuaUnit.set_verbosity = LuaUnit.setVerbosity
LuaUnit.SetVerbosity = LuaUnit.setVerbosity
-- Split text into a list consisting of the strings in text,
-- separated by strings matching delimiter (which may be a pattern).
-- example: strsplit(",%s*", "Anna, Bob, Charlie,Dolores")
function LuaUnit.strsplit(delimiter, text)
local list = {}
local pos = 1
if string.find("", delimiter, 1) then -- this would result in endless loops
error("delimiter matches empty string!")
end
while 1 do
local first, last = string.find(text, delimiter, pos)
if first then -- found?
table.insert(list, string.sub(text, pos, first-1))
pos = last+1
else
table.insert(list, string.sub(text, pos))
break
end
end
return list
end
-- Type check functions
for _, typename in ipairs(typenames) do
local tName = typename:lower()
LuaUnit["is"..typename] = function(x)
return type(x) == tName
end
-- Alias to lower underscore naming
LuaUnit["is_"..tName] = LuaUnit["is"..typename]
end
-- Use me to wrap a set of functions into a Runnable test class:
-- TestToto = wrapFunctions( f1, f2, f3, f3, f5 )
-- Now, TestToto will be picked up by LuaUnit:run()
function LuaUnit.wrapFunctions(...)
local testClass, testFunction
testClass = {}
local function storeAsMethod(idx, testName)
testFunction = _G[testName]
testClass[testName] = testFunction
end
for i, v in ipairs {...} do storeAsMethod(i, v) end
return testClass
end
-- Other alias's
LuaUnit.wrap_functions = LuaUnit.wrapFunctions
LuaUnit.WrapFunctions = LuaUnit.wrapFunctions
function LuaUnit.strip_luaunit_stack(stack_trace)
local stack_list = LuaUnit.strsplit( "\n", stack_trace )
local strip_end = nil
for i = #stack_list,1,-1 do
-- a bit rude but it works !
if string.find(stack_list[i],"[C]: in function `xpcall'",0,true)
then
strip_end = i - 2
end
end
if strip_end then
table.setn( stack_list, strip_end )
end
local stack_trace = table.concat( stack_list, "\n" )
return stack_trace
end
function LuaUnit:runTestMethod(aName, aClassInstance, aMethod)
local ok, errorMsg
-- example: runTestMethod( 'TestToto:test1', TestToto, TestToto.testToto(self) )
LuaUnit.result:startTest(aName)
-- run setUp first(if any)
if self.isFunction( aClassInstance.setUp) then
aClassInstance:setUp()
elseif self.isFunction( aClassInstance.Setup) then
aClassInstance:Setup()
elseif self.isFunction( aClassInstance.setup) then
aClassInstance:setup()
end
local function err_handler(e)
return e..'\n'..debug.traceback()
end
-- run testMethod()
local ok, errorMsg = xpcall( aMethod, err_handler )
if not ok then
errorMsg = self.strip_luaunit_stack(errorMsg)
LuaUnit.result:addFailure( errorMsg )
end
-- lastly, run tearDown(if any)
if self.isFunction(aClassInstance.tearDown) then
aClassInstance:tearDown()
elseif self.isFunction(aClassInstance.TearDown) then
aClassInstance:TearDown()
elseif self.isFunction(aClassInstance.teardown) then
aClassInstance:teardown()
end
self.result:endTest()
end
function LuaUnit:runTestMethodName(methodName, classInstance)
-- example: runTestMethodName( 'TestToto:testToto', TestToto )
local methodInstance = loadstring(methodName .. '()')
LuaUnit:runTestMethod(methodName, classInstance, methodInstance)
end
function LuaUnit:runTestClassByName(aClassName)
--assert("table" == type(aClassName), ("bad argument #1 to 'runTestClassByName' (string expected, got %s). Make sure you are not trying to just pass functions not part of a class."):format(type(aClassName)))
-- example: runTestMethodName( 'TestToto' )
local hasMethod, methodName, classInstance
hasMethod = string.find(aClassName, ':' )
if hasMethod then
methodName = string.sub(aClassName, hasMethod+1)
aClassName = string.sub(aClassName,1,hasMethod-1)
end
classInstance = _G[aClassName]
if "table" ~= type(classInstance) then
error("No such class: "..aClassName)
end
LuaUnit.result:startClass( aClassName )
if hasMethod then
if not classInstance[ methodName ] then
error( "No such method: "..methodName )
end
LuaUnit:runTestMethodName( aClassName..':'.. methodName, classInstance )
else
-- run all test methods of the class
for methodName, method in orderedPairs(classInstance) do
--for methodName, method in classInstance do
if LuaUnit.isFunction(method) and (string.sub(methodName, 1, 4) == "test" or string.sub(methodName, 1, 4) == "Test") then
LuaUnit:runTestMethodName( aClassName..':'.. methodName, classInstance )
end
end
end
end
function LuaUnit:run(...)
-- Run some specific test classes.
-- If no arguments are passed, run the class names specified on the
-- command line. If no class name is specified on the command line
-- run all classes whose name starts with 'Test'
--
-- If arguments are passed, they must be strings of the class names
-- that you want to run
local args = {...}
if #args > 0 then
for i, v in ipairs(args) do LuaUnit.runTestClassByName(i, v) end
else
if argv and #argv > 1 then
-- Run files passed on the command line
for i, v in ipairs(argv) do LuaUnit.runTestClassByName(i, v) end
else
-- create the list before. If you do not do it now, you
-- get undefined result because you modify _G while iterating
-- over it.
local testClassList = {}
for key, val in pairs(_G) do
if "table" == type(val) then
if string.sub(key, 1, 4) == "Test" or string.sub(key, 1, 4) == "test" then
table.insert( testClassList, key )
end
end
end
for i, val in orderedPairs(testClassList) do
LuaUnit:runTestClassByName(val)
end
end
end
return LuaUnit.result:displayFinalResult()
end
-- Other alias
LuaUnit.Run = LuaUnit.run
-- end class LuaUnit
return LuaUnit