Module:UnitTests/doc

UnitTests provides a unit test facility that can be used by other scripts using require. See Wikipedia:Lua#Unit_testing for details. The following is a sample from Module:Example/testcases:

<syntaxhighlight lang="lua"> -- Unit tests for Module:Example. Click talk page to run tests. local p = require('Module:UnitTests')

function p:test_hello()

   self:preprocess_equals('{{#invoke:Example | hello}}', 'Hello World!')

end

return p </syntaxhighlight>

The talk page Module talk:Example/testcases executes it with {{#invoke: Example/testcases | run_tests}}. Test methods like test_hello above must begin with "test".

Methods

run_tests

• <syntaxhighlight lang="text" class="" style="" inline="1">run_tests</syntaxhighlight>: Runs all tests. Normally used on talk page of unit tests. <syntaxhighlight lang="wikitext">

All 10 tests passed.

test_Name2

	Text	Expected	Actual
Template:Tick	{{#invoke:Example|Name2}}	Lonely	Lonely
Template:Tick	{{#invoke:Example|Name2|1}}	Lonely	Lonely
Template:Tick	{{#invoke:Example|Name2|1|2}}	Be positive!	Be positive!
Template:Tick	{{#invoke:Example|Name2|2|1}}	1	1

test_count_fruit

	Text	Expected	Actual
Template:Tick	{{#invoke:Example|count_fruit|bananas=5|apples=3}}	I have 5 bananas and 3 apples	I have 5 bananas and 3 apples
Template:Tick	{{#invoke:Example|count_fruit|bananas=1|apples=1}}	I have 1 banana and 1 apple	I have 1 banana and 1 apple
Template:Tick	{{#invoke:Example|count_fruit|bananas=Not a number|apples=Not a number}}	I have 0 bananas and 0 apples	I have 0 bananas and 0 apples
Template:Tick	{{#invoke:Example|count_fruit}}	I have 0 bananas and 0 apples	I have 0 bananas and 0 apples

test_hello

	Text	Expected	Actual
Template:Tick	{{#invoke:Example | hello}}	Hello World!	Hello World!

test_hello_to

	Text	Expected	Actual
Template:Tick	{{#invoke:Example|hello_to|Fred}}	Hello, Fred!	Hello, Fred!

</syntaxhighlight>

• If <syntaxhighlight lang="text" class="" style="" inline="1">differs_at</syntaxhighlight> is specified, a column will be added showing the first character position where the expected and actual results differ. <syntaxhighlight lang="wikitext">

All 10 tests passed.

test_Name2

	Text	Expected	Actual	Differs at
Template:Tick	{{#invoke:Example|Name2}}	Lonely	Lonely
Template:Tick	{{#invoke:Example|Name2|1}}	Lonely	Lonely
Template:Tick	{{#invoke:Example|Name2|1|2}}	Be positive!	Be positive!
Template:Tick	{{#invoke:Example|Name2|2|1}}	1	1

test_count_fruit

	Text	Expected	Actual	Differs at
Template:Tick	{{#invoke:Example|count_fruit|bananas=5|apples=3}}	I have 5 bananas and 3 apples	I have 5 bananas and 3 apples
Template:Tick	{{#invoke:Example|count_fruit|bananas=1|apples=1}}	I have 1 banana and 1 apple	I have 1 banana and 1 apple
Template:Tick	{{#invoke:Example|count_fruit|bananas=Not a number|apples=Not a number}}	I have 0 bananas and 0 apples	I have 0 bananas and 0 apples
Template:Tick	{{#invoke:Example|count_fruit}}	I have 0 bananas and 0 apples	I have 0 bananas and 0 apples

test_hello

	Text	Expected	Actual	Differs at
Template:Tick	{{#invoke:Example | hello}}	Hello World!	Hello World!

test_hello_to

	Text	Expected	Actual	Differs at
Template:Tick	{{#invoke:Example|hello_to|Fred}}	Hello, Fred!	Hello, Fred!

</syntaxhighlight>

• If <syntaxhighlight lang="text" class="" style="" inline="1">highlight</syntaxhighlight> is specified, failed tests will be highlighted to make them easier to spot. A user script that moves failed tests to the top is also available. <syntaxhighlight lang="wikitext">

All 10 tests passed.

test_Name2

	Text	Expected	Actual
Template:Tick	{{#invoke:Example|Name2}}	Lonely	Lonely
Template:Tick	{{#invoke:Example|Name2|1}}	Lonely	Lonely
Template:Tick	{{#invoke:Example|Name2|1|2}}	Be positive!	Be positive!
Template:Tick	{{#invoke:Example|Name2|2|1}}	1	1

test_count_fruit

	Text	Expected	Actual
Template:Tick	{{#invoke:Example|count_fruit|bananas=5|apples=3}}	I have 5 bananas and 3 apples	I have 5 bananas and 3 apples
Template:Tick	{{#invoke:Example|count_fruit|bananas=1|apples=1}}	I have 1 banana and 1 apple	I have 1 banana and 1 apple
Template:Tick	{{#invoke:Example|count_fruit|bananas=Not a number|apples=Not a number}}	I have 0 bananas and 0 apples	I have 0 bananas and 0 apples
Template:Tick	{{#invoke:Example|count_fruit}}	I have 0 bananas and 0 apples	I have 0 bananas and 0 apples

test_hello

	Text	Expected	Actual
Template:Tick	{{#invoke:Example | hello}}	Hello World!	Hello World!

test_hello_to

	Text	Expected	Actual
Template:Tick	{{#invoke:Example|hello_to|Fred}}	Hello, Fred!	Hello, Fred!

</syntaxhighlight>

• If <syntaxhighlight lang="text" class="" style="" inline="1">live_sandbox</syntaxhighlight> is specified, the header will show the columns "Test", "Live", "Sandbox", "Expected". This is required when using the <syntaxhighlight lang="text" class="" style="" inline="1">preprocess_equals_sandbox_many</syntaxhighlight> method.

preprocess_equals

• <syntaxhighlight lang="text" class="" style="" inline="1">preprocess_equals(text, expected, options)</syntaxhighlight>: Gives a piece of wikitext to preprocess and an expected resulting value. Scripts and templates can be invoked in the same manner they would be in a page. <syntaxhighlight lang="lua">

self:preprocess_equals('Hello World!', 'Hello, world!', {nowiki=1}) </syntaxhighlight>

preprocess_equals_many

• <syntaxhighlight lang="text" class="" style="" inline="1">preprocess_equals_many(prefix, suffix, cases, options)</syntaxhighlight>: Performs a series of preprocess_equals() calls on a set of given pairs. Automatically adds the given prefix and suffix to each text. <syntaxhighlight lang="lua">

self:preprocess_equals_many('Hello, ', '!', {

   {'John', 'Hello, John!'},
   {'Jane', 'Hello, Jane!'},

}, {nowiki=1}) </syntaxhighlight>

preprocess_equals_preprocess

• <syntaxhighlight lang="text" class="" style="" inline="1">preprocess_equals_preprocess(text, expected, options)</syntaxhighlight>: Gives two pieces of wikitext to preprocess and determines if they produce the same value. Useful for comparing scripts to existing templates. <syntaxhighlight lang="lua">

self:preprocess_equals_preprocess('Hello World!', 'Template:Hello', {nowiki=1}) </syntaxhighlight>

preprocess_equals_preprocess_many

• <syntaxhighlight lang="text" class="" style="" inline="1">preprocess_equals_preprocess_many(prefix1, suffix1, prefix2, suffix2, cases, options)</syntaxhighlight>: Performs a series of preprocess_equals_preprocess() calls on a set of given pairs. The prefix/suffix supplied for both arguments is added automatically. If in any case the second part is not specified, the first part will be used. <syntaxhighlight lang="lua">

self:preprocess_equals_preprocess_many('', 'Template:Spellnum', '', {

   {'2'}, -- equivalent to {'2','2'},
   {'-2', '-2.0'},

}, {nowiki=1}) </syntaxhighlight>

preprocess_equals_sandbox_many

• <syntaxhighlight lang="text" class="" style="" inline="1">preprocess_equals_sandbox_many(module, function, cases, options)</syntaxhighlight>: Performs a series of preprocess_equals_compare() calls on a set of given pairs. The test compares the live version of the module vs the /sandbox version and vs an expected result. Ensure live_sandbox is specified or there may be some errors in the output. <syntaxhighlight lang="lua">

self:preprocess_equals_sandbox_many('{{#invoke:Example', 'hello_to', {

   {'John', 'Hello, John!'},
   {'Jane', 'Hello, Jane!'},

}, {nowiki=1}) </syntaxhighlight>

equals

• <syntaxhighlight lang="text" class="" style="" inline="1">equals(name, actual, expected, options)</syntaxhighlight>: Gives a computed value and the expected value, and checks if they are equal according to the == operator. Useful for testing modules that are designed to be used by other modules rather than using #invoke. <syntaxhighlight lang="lua">

self:equals('Simple addition', 2 + 2, 4, {nowiki=1}) </syntaxhighlight>

equals_deep

• <syntaxhighlight lang="text" class="" style="" inline="1">equals_deep(name, actual, expected, options)</syntaxhighlight>: Like equals, but handles tables by doing a deep comparison. Neither value should contain circular references, as they are not handled by the current implementation and may result in an infinite loop. <syntaxhighlight lang="lua">

self:equals_deep('Table comparison', createRange(1,3), {1,2,3}, {nowiki=1}) </syntaxhighlight>

Test options

These are the valid options that can be passed into the options parameters of the test functions listed above.

nowiki

Enabling this wraps the output text in <nowiki>...</nowiki> tags to avoid the text being rendered (E.g. <span>[[Example|Page]]</span> instead of Page)

combined

Only available in preprocess_equals and preprocess_equals_preprocess

Enabling this will display the output text in both the rendered mode and the nowiki mode to allow for both a raw text and visual comparison.

templatestyles

Only available in preprocess_equals and preprocess_equals_preprocess

Enabling this fixes the IDs in the strip markers ...</templatestyles> produces when processed to avoid incorrectly failing the tests.

stripmarker

Only available in preprocess_equals and preprocess_equals_preprocess

Enabling this fixes the IDs in all strip markers produces when processed to avoid incorrectly failing the tests.

display

Only available in equals

An optional function that changes how the output from the tests are displayed. This doesn't effect the comparison process.

See also

• Module:ScribuntoUnit – alternative unit test module