Module:UnitTests/doc

This is a documentation subpage for Module:UnitTests.
It may contain usage information, categories and other content that is not part of the original module page.

This Lua module is used on many pages and changes may be widely noticed. Test changes in the module's /sandbox or /testcases subpages, or in your own module sandbox. Consider discussing changes on the talk page before implementing them.

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:

-- 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

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

run_tests: Runs all tests. Normally used on talk page of unit tests.
```
{{#invoke:Example/testcases|run_tests}}
```
If differs_at is specified, a column will be added showing the first character position where the expected and actual results differ.
```
{{#invoke:Example/testcases|run_tests|differs_at=1}}
```
If highlight 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.
```
{{#invoke:Example/testcases|run_tests|highlight=1}}
```
If live_sandbox is specified, the header will show the columns "Test", "Live", "Sandbox", "Expected". This is required when using the preprocess_equals_sandbox_many method.
```
{{#invoke:Example/testcases|run_tests|live_sandbox=1}}
```

preprocess_equals

preprocess_equals(text, expected, options): 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.
```
self:preprocess_equals('{{#invoke:Example | hello}}', 'Hello, world!', {nowiki=1})
```

preprocess_equals_many

preprocess_equals_many(prefix, suffix, cases, options): Performs a series of preprocess_equals() calls on a set of given pairs. Automatically adds the given prefix and suffix to each text.
```
self:preprocess_equals_many('{{#invoke:Example | hello_to |', '}}', {
	{'John', 'Hello, John!'},
	{'Jane', 'Hello, Jane!'},
}, {nowiki=1})
```

preprocess_equals_preprocess

preprocess_equals_preprocess(text, expected, options): Gives two pieces of wikitext to preprocess and determines if they produce the same value. Useful for comparing scripts to existing templates.
```
self:preprocess_equals_preprocess('{{#invoke:Example | hello}}', '{{Hello}}', {nowiki=1})
```

preprocess_equals_preprocess_many

preprocess_equals_preprocess_many(prefix1, suffix1, prefix2, suffix2, cases, options): 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.
```
self:preprocess_equals_preprocess_many('{{#invoke:ConvertNumeric | numeral_to_english|', '}}', '{{spellnum', '}}', {
	{'2'}, -- equivalent to {'2','2'},
	{'-2', '-2.0'},
}, {nowiki=1})
```

preproccess_equals_compare

preproccess_equals_compare(live, sandbox, expected, options)

Performs a single comparison between the output of specified modules (live and sandbox - these do not have to be the actual live and sandbox versions of the same module), and vs an expected result. Live and sandbox must each be specified as the full call to the module, with called function and parameters. Ensure live_sandbox=1 is specified in the call to run_tests() or there may be some errors in the output.

self:preproccess_equals_compare('{{#invoke:Example|hello_to|Jane}}',
'{{#invoke:Sandbox/ExampleUser/Example|hello_to|Jane}}',
'Hello, Jane!',
{nowiki=1})

preprocess_equals_sandbox_many

preprocess_equals_sandbox_many(module, function, cases, options): 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=1 is specified in the call to run_tests() or there may be some errors in the output.
```
self:preprocess_equals_sandbox_many('{{#invoke:Example', 'hello_to', {
	{'John', 'Hello, John!'},
	{'Jane', 'Hello, Jane!'},
}, {nowiki=1})
```

equals

equals(name, actual, expected, options): 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.
```
self:equals('Simple addition', 2 + 2, 4, {nowiki=1})
```

equals_deep

equals_deep(name, actual, expected, options): 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.
```
self:equals_deep('Table comparison', createRange(1,3), {1,2,3}, {nowiki=1})
```

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

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.

noexpectation

Enabling this and providing an empty string as an expected value makes a test always succeed, regardless of the actual value.

templatestyles

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

stripmarker

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

display

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