Module:UnitTests
Jump to navigation
Jump to search
- The following documentation is located at Module:UnitTests/documentation. [edit]
- Useful links: subpage list • links • transclusions • testcases • sandbox
This module facilitates creating unit tests for Lua modules.
Put the following at Module:name/testcases
:
local tests = require('Module:UnitTests')
function tests:test_example()
--[[ here be the tests ]]
end
return tests
Then put the following on Module:name/testcases/documentation
:
{{#invoke:name/testcases|run_tests}}
Tests should be written as Lua methods whose names start with test
. The self
object contains the following methods, which may be called from the method:
preprocess_equals(text, expected, options)
- Will check whether expanding templates in
text
results inexpected
. preprocess_equals_many(prefix, suffix, cases, options)
preprocess_equals_preprocess(text1, text2, options)
- Will check whether expanding templates in
text1
andtext2
results in the same string. preprocess_equals_preprocess_many(prefix1, suffix1, prefix2, suffix2, cases, options)
equals(name, actual, expected, options)
- Will check whether two primitive values are equal.
name
will be used as the row header. When the value is a table,equals_deep
should be used. equals_deep(name, actual, expected, options)
- Will check whether two values, which may be tables, are equal.
name
will be used as the row header. header(string)
- Create a heading in the table, which appears after the last-called checking function.
iterate
- Requires an array as its first argument. Iterates over the items in the array. If the item in the array is an array, a function will be called on the contents of the array. If the item is a string, a heading is created using
self:header()
. - Two variations:
iterate(array, function_name)
- Here,
function_name
is a string, the name of a method in theself
object. For instance,self:iterate({ { "a", "b" }, { "c", "d" } }, "check")
callsself:check("a", "b")
andself:check("c", "d")
. Thisself:check()
method must be defined separately.
iterate(array, func)
- Same as above, except the second argument is a function. For instance,
self:iterate( { { "a", "b" }, { "c", "d" } }, check)
will callcheck(self, "a", "b")
andcheck(self, "c", "d")
.
options
should be given in a table or omitted. Currently, these are the options supported:
nowiki
: Causes both the expected and the actual values to be wrapped in <nowiki> tags when rendering the results table.comment
: A comment to be added to the rightmost column of table.display
: A function to yield the form actually displayed in the table. This is used in testcases for pronunciation modules to make the IPA transcriptions display with the correct fonts.show_difference
: If this is set totrue
(or any truthy value besides a function), failing tests will have the first offending character highlighted in red (that is, the first character in the "actual" string that is different from the corresponding character in the "expected" string). If this is a function, the character will be highlighted using the function. (Currently only available in theequals
checking function. The highlighter will highlight combining characters together with the characters they are placed on.)
See also
Use Module:transliteration module testcases to quickly create testcases for a transliteration module. It uses this module. At the moment, it only supports romanization and a single set of examples.
local m_table = require("Module:table")
local UnitTester = {}
local concat = table.concat
local deep_equals = m_table.deepEquals
local explode_utf8 = require("Module:string utilities").explode_utf8
local html = mw.html
local insert = table.insert
local is_combining = require("Module:Unicode data").is_combining
local nowiki = require("Module:string/nowiki")
local shallowcopy = m_table.shallowcopy
local sort = table.sort
local sorted_pairs = m_table.sortedPairs
local ustring = mw.ustring
local tick, cross =
'[[File:Yes check.svg|20px|alt=Passed|link=|Test passed]]',
'[[File:X mark.svg|20px|alt=Failed|link=|Test failed]]'
local function first_difference(s1, s2)
if not (type(s1) == "string" and type(s2) == "string") then
return "N/A"
elseif s1 == s2 then
return ""
end
s1 = explode_utf8(s1)
s2 = explode_utf8(s2)
local i = 0
repeat
i = i + 1
until s1[i] ~= s2[i]
return i
end
local function highlight(str)
if ustring.find(str, "%s") then
return '<span style="background-color: pink;">' ..
string.gsub(str, " ", " ") .. '</span>'
else
return '<span style="color: red;">' ..
str .. '</span>'
end
end
local function find_noncombining(str, i, incr)
local char = ustring.sub(str, i, i)
while char ~= '' and is_combining(char) do
i = i + incr
char = ustring.sub(str, i, i)
end
return i
end
-- Highlight character where a difference was found. Start highlight at first
-- non-combining character before the position. End it after the first non-
-- combining characters after the position. Can specify a custom highlighing
-- function.
local function highlight_difference(actual, expected, differs_at, func)
if type(differs_at) ~= "number" or not (actual and expected) then
return actual
end
differs_at = find_noncombining(expected, differs_at, -1)
local i = find_noncombining(actual, differs_at, -1)
local j = find_noncombining(actual, differs_at + 1, 1)
j = j - 1
return ustring.sub(actual, 1, i - 1) ..
(type(func) == "function" and func or highlight)(ustring.sub(actual, i, j)) ..
ustring.sub(actual, j + 1, -1)
end
local function val_to_str(v)
if type(v) == 'string' then
v = string.gsub(v, '\n', '\\n')
if string.find(string.gsub(v, '[^\'"]', ''), '^"+$') then
return "'" .. v .. "'"
end
return '"' .. string.gsub(v, '"', '\\"' ) .. '"'
elseif type(v) == 'table' then
local result, done = {}, {}
for k, val in ipairs(v) do
insert(result, val_to_str(val))
done[k] = true
end
for k, val in sorted_pairs(v) do
if not done[k] then
if (type(k) ~= "string") or not string.find(k, '^[_%a][_%a%d]*$') then
k = '[' .. val_to_str(k) .. ']'
end
insert(result, k .. '=' .. val_to_str(val))
end
end
return "{" .. concat(result, ", ") .. "}"
else
return tostring(v)
end
end
local function deep_compare(t1, t2, ignore_mt)
return deep_equals(t1, t2, not ignore_mt)
end
local function get_differing_keys(t1, t2)
local ty1, ty2 = type(t1), type(t2)
if ty1 ~= ty2 then return nil
elseif ty1 ~= 'table' then return nil end
local mt = getmetatable(t1)
if not ignore_mt and mt and mt.__eq then return nil end
local keys = {}
for k1, v1 in pairs(t1) do
local v2 = t2[k1]
if v2 == nil or not deep_compare(v1, v2) then insert(keys, k1) end
end
for k2, v2 in pairs(t2) do
local v1 = t1[k2]
if v1 == nil or not deep_compare(v1, v2) then insert(keys, k2) end
end
return keys
end
local function extract_keys(table, keys)
if not keys then return table end
local new_table = {}
for _, key in ipairs(keys) do
new_table[key] = table[key]
end
return new_table
end
-- Return the header for the result table along with the number of columns in the table.
function UnitTester:new_result_table()
local header_row = html.create("tr")
:tag("th")
:attr("class", "unit-tests-img-corner")
:css("cursor", "pointer")
:attr("title", "Only failed tests")
:done()
local columns = shallowcopy(self.name_columns)
insert(columns, "Expected")
insert(columns, "Actual")
insert(columns, differs_at)
if self.differs_at then
insert(columns, "Differs at")
end
if self.comments then
insert(columns, "Comments")
end
for _, cell in ipairs(columns) do
header_row = header_row:tag("th")
:wikitext(cell)
:done()
end
self.columns = #columns + 1
return html.create("table")
:attr("class", "unit-tests wikitable")
:node(header_row)
end
function UnitTester:display_difference(success, name, actual, expected, options)
local differs_at = self.differs_at and first_difference(expected, actual)
local comment = self.comments and (options and options.comment or "")
expected = expected == nil and "(nil)" or tostring(expected)
actual = actual == nil and "(nil)" or tostring(actual)
if self.nowiki or options and options.nowiki then
expected = nowiki(expected)
actual = nowiki(actual)
end
if options and type(options.display) == "function" then
expected = options.display(expected)
actual = options.display(actual)
end
local cells
if type(name) == "table" then
cells = shallowcopy(name)
insert(cells, expected)
insert(cells, actual)
insert(cells, differs_at)
else
cells = {
name,
expected,
actual,
differs_at
}
end
insert(cells, comment) -- In case differs_at is nil.
local row = html.create("tr")
if success then
row = row:attr("class", "unit-test-pass")
insert(cells, 1, tick)
else
row = row:attr("class", "unit-test-fail")
insert(cells, 1, cross)
self.num_failures = self.num_failures + 1
end
for _, cell in ipairs(cells) do
row = row:tag("td")
:wikitext(cell)
:done()
end
self.result_table = self.result_table:node(row)
self.total_tests = self.total_tests + 1
end
function UnitTester:equals(name, actual, expected, options)
success = actual == expected
if options and options.show_difference then
local difference = first_difference(expected, actual)
if type(difference) == "number" then
actual = highlight_difference(actual, expected, difference,
type(options.show_difference) == "function" and options.show_difference)
end
end
self:display_difference(success, name, actual, expected, options)
end
function UnitTester:preprocess_equals(text, expected, options)
local actual = self.frame:preprocess(text)
self:equals(nowiki(text), actual, expected, options)
end
function UnitTester:preprocess_equals_many(prefix, suffix, cases, options)
for _, case in ipairs(cases) do
self:preprocess_equals(prefix .. case[1] .. suffix, case[2], options)
end
end
function UnitTester:preprocess_equals_preprocess(text1, text2, options)
local expected = self.frame:preprocess(text2)
self:preprocess_equals(text1, expected, options)
end
function UnitTester:preprocess_equals_preprocess_many(prefix1, suffix1, prefix2, suffix2, cases, options)
for _, case in ipairs(cases) do
self:preprocess_equals_preprocess(prefix1 .. case[1] .. suffix1, prefix2 .. (case[2] and case[2] or case[1]) .. suffix2, options)
end
end
function UnitTester:equals_deep(name, actual, expected, options)
local actual_str, expected_str
local success = deep_compare(actual, expected)
if success then
if options and options.show_table_difference then
actual_str = ''
expected_str = ''
end
else
if options and options.show_table_difference then
local keys = get_differing_keys(actual, expected)
actual_str = val_to_str(extract_keys(actual, keys))
expected_str = val_to_str(extract_keys(expected, keys))
end
end
if (not options) or not options.show_table_difference then
actual_str = val_to_str(actual)
expected_str = val_to_str(expected)
end
self:display_difference(success, name, actual_str, expected_str, options)
end
function UnitTester:iterate(examples, func)
require 'libraryUtil'.checkType('iterate', 1, examples, 'table')
if type(func) == 'string' then
func = self[func]
elseif type(func) ~= 'function' then
error(("bad argument #2 to 'iterate' (expected function or string, got %s)")
:format(type(func)), 2)
end
for i, example in ipairs(examples) do
if type(example) == 'table' then
func(self, unpack(example))
elseif type(example) == 'string' then
self:header(example)
else
error(('bad example #%d (expected table or string, got %s)')
:format(i, type(example)), 2)
end
end
end
function UnitTester:header(text)
local prefix, maintext = text:match('^#(h[0-9]+):(.*)$')
if not prefix then
maintext = text
end
local header = html.create("th")
:attr("colspan", self.columns)
if prefix == "h1" then
header = header:css("text-align", "center")
:css("font-size", "150%")
else
header = header:css("text-align", "left")
end
header = header:wikitext(maintext)
self.result_table = self.result_table:tag("tr")
:node(header)
:done()
end
function UnitTester:run(frame)
self.num_failures = 0
local output = {}
local iparams = {
["nowiki"] = {type = "boolean"},
["differs_at"] = {type = "boolean"},
["comments"] = {type = "boolean"},
["summarize"] = {type = "boolean"},
["name_column"] = {list = true, default = "Text"},
}
local iargs = require("Module:parameters").process(frame.args, iparams)
self.frame = frame
self.nowiki = iargs.nowiki
self.differs_at = iargs.differs_at
self.comments = iargs.comments
self.summarize = iargs.summarize
self.name_columns = iargs.name_column
self.total_tests = 0
-- Sort results into alphabetical order.
local self_sorted = {}
for key in pairs(self) do
if key:find('^test') then
insert(self_sorted, key)
end
end
sort(self_sorted)
-- Add results to the results table.
for _, key in ipairs(self_sorted) do
self.result_table = self:new_result_table()
:tag("caption")
:css("text-align", "left")
:css("font-weight", "bold")
:wikitext(key .. ":")
:done()
local traceback = "(no traceback)"
local success, mesg = xpcall(function()
return self[key](self)
end, function(mesg)
traceback = debug.traceback("", 2)
return mesg
end)
if not success then
self.result_table = self.result_table:tag("tr")
:tag("td")
:attr("colspan", self.columns)
:css("text-align", "left")
:tag("strong")
:attr("class", "error")
:wikitext("Script error during testing: " .. nowiki(mesg))
:done()
:wikitext(frame:extensionTag("pre", traceback))
:allDone()
self.num_failures = self.num_failures + 1
end
insert(output, tostring(self.result_table))
end
local refresh_link = tostring(mw.uri.fullUrl(mw.title.getCurrentTitle().fullText, 'action=purge&forcelinkupdate=1'))
local failure_cat = '[[Category:Failing testcase modules]]'
if mw.title.getCurrentTitle().text:find("/documentation$") then
failure_cat = ''
end
local num_successes = self.total_tests - self.num_failures
if self.summarize then
if self.num_failures == 0 then
return '<strong class="success">' .. self.total_tests .. '/' .. self.total_tests .. ' tests passed</strong>'
else
return '<strong class="error">' .. num_successes .. '/' .. self.total_tests .. ' tests passed</strong>'
end
else
return (self.num_failures == 0 and '<strong class="success">All tests passed.</strong>' or
'<strong class="error">' .. self.num_failures .. ' of ' .. self.total_tests .. ' test' .. (self.total_tests == 1 and '' or 's' ) .. ' failed.</strong>' .. failure_cat) ..
" <span class='plainlinks unit-tests-refresh'>[" .. refresh_link .. " (refresh)]</span>\n\n" ..
concat(output, "\n\n")
end
end
function UnitTester:new()
local o = {}
setmetatable(o, self)
self.__index = self
return o
end
local p = UnitTester:new()
function p.run_tests(frame) return p:run(frame) end
return p