Module:UnitTests/documentation

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 in expected.

preprocess_equals_many(prefix, suffix, cases, options)

preprocess_equals_preprocess(text1, text2, options)

Will check whether expanding templates in text1 and text2 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 the self object. For instance, self:iterate({ { "a", "b" }, { "c", "d" } }, "check") calls self:check("a", "b") and self:check("c", "d"). This self: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 call check(self, "a", "b") and check(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 to true (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 the equals 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.