Module:ScribuntoUnit/doc

This subpage provides documentation for Module:ScribuntoUnit.

This module provides unit tests for other Scribunto modules. To test a module, you must create a separate testing module, usually located on the module's /testcases subpage. The testing module uses ScribuntoUnit to verify that the operations defined in it produce the expected results.

Test module structure

To make a test module (test suite), start with the following code:

local myModule = require('Module:MyModule') -- the module to be tested
local ScribuntoUnit = require('Module:ScribuntoUnit')
local suite = ScribuntoUnit:new()

After you have done this you can add individual test functions. Any member function of the suite object that has a name beginning with "test" is treated as a test by ScribuntoUnit.

function suite:testSomeCall()
    self:assertEquals('expected value', myModule.someCall(123))
    self:assertEquals('other expected value', myModule.someCall(456))
end

function suite:testSomeOtherCall()
    self:assertEquals('expected value', myModule.someOtherCall(123))
    self:assertEquals('other expected value', myModule.someOtherCall(456))
end

The tests you write should make assertions, and ScribuntoUnit will check whether those assertions are true. For example, assertEquals checks that both of the arguments it is given are equal. If ScribuntoUnit doesn't find an assertion to be true, then the test will fail and an error message will be generated. The error message will show which assertion failed verification. (Other checks on the assertions are not made at this time.)

The return value of the test module should be the suite object.

return suite

Running the tests

When implemented correctly with ScribuntoUnit, the testing module located on a module's /testcases subpage will run automatically and display the results.

To run a testing module using the debug console, execute the following code: require('Module:MyModule/testcases').run()

To run a testing module using wikicode, use {{#invoke:MyModule/testcases|run}}. This will generate a table containing the results. To display a summary of the results, rather than the entire table, use {{#invoke:MyModule/testcases|run|displayMode=short}}.

Assertion methods

Error messages

The last parameter of all the assertion methods is a message that is displayed if validation fails.

self:assertEquals('expected value', myModule.someCall(123), 'This tests whether the function x does y.')

assertTrue, assertFalse

self:assertTrue(actual, message)
self:assertFalse(actual, message)

These methods assert that a value is true or false respectively. Note that in Lua, only the values false and nil evaluate to false; everything else evaluates to true, including the number 0 and the empty string.

self:assertTrue(2 + 2 == 4) -- true
self:assertTrue('foo') -- true
self:assertTrue(0) -- true
self:assertFalse(2 + 2 == 5) -- true
self:assertFalse(nil) -- true

assertStringContains

self:assertStringContains(pattern, s, plain, message)

This method asserts that pattern is found in the string s. If plain is true, then pattern is interpreted as literal text; otherwise, pattern is interpreted as a ustring pattern.

If the pattern is not found, the error message shows the values of pattern and s. (The output for these values is truncated if longer than 70 characters.) This method is useful for testing specific behaviors in complex wikitext.

self:assertStringContains("foo", "foobar") -- true
self:assertStringContains("foo", "fobar") -- false
self:assertStringContains(".oo", "foobar") -- true: matches "foo"
self:assertStringContains(".oo", "foobar", true) -- false: . is interpreted as a literal character

assertNotStringContains

self:assertNotStringContains(pattern, s, plain, message)

This method is the inverse of assertStringContains. It asserts that pattern is not found in the string s. If plain is true, then pattern is interpreted as literal text; otherwise, pattern is interpreted as a ustring pattern.

self:assertNotStringContains("foo", "foobar") -- false
self:assertNotStringContains("foo", "fobar") -- true
self:assertNotStringContains(".oo", "foobar") -- false: matches "foo"
self:assertNotStringContains(".oo", "foobar", true) -- true: . is interpreted as a literal character

assertEquals

self:assertEquals(expected, actual, message)

This method asserts that the first argument is equal to the second argument. If both arguments are numbers, the values are instead compared using assertWithinDelta with delta 1e-8 (0.00000001). (See #assertWithinDelta.)

self:assertEquals(4, 2 + 2) -- true

assertWithinDelta

self:assertWithinDelta(expected, actual, delta, message)

This method asserts that the first number argument is within a given distance (delta) from the second number argument. This is useful to compare floating point numbers, which are used to represent numbers in the standard installation of Lua. (To be precise, it uses double-precision floating point numbers.) For example, with the version of Scribunto installed on Path of Exile Wiki, the expression 0.3 – 0.2 == 0.1 evaluates to false. This is because the expression 0.3 – 0.2 actually evaluates to 0.09999999999999997780… in practice. The slight difference between the two means that Lua does not consider them equal when compared using the equality operator (==). Therefore, to test for equality between two floating point numbers, we should accept values within a small distance (delta) of each other, not just equal values. Note that this problem does not affect integers, which can be represented exactly using double-precision floating point numbers up to values of 2^53.

self:assertWithinDelta(0.1, 0.3 - 0.2, 1e-10) -- true

assertDeepEquals

self:assertDeepEquals(expected, actual, message)

This method asserts that the first argument is equal to the second argument. If the parameters are tables, they are compared recursively, and their __eq metamethods are respected.

self:assertDeepEquals(table1, table2)

assertTemplateEquals

self:assertTemplateEquals(expected, template, args, message)

This method asserts that the first argument equals the result of expanding a template. The second argument is the name of the template, and the third parameter is a table of the parameters given to the template.

self:assertTemplateEquals(4, 'add', {2, 2}) -- true, assuming {{add|2|2}} equals 4

Note that some special tags written in XML notation, such as <pre>, <nowiki>, <gallery> and <ref> cannot be compared correctly. These tags are converted to strip markers before they are processed by Lua. Strip markers are unique, even when generated from identical input, so any tests testing these tags for equality will fail. This also applies to the assertResultEquals and assertSameResult methods.

assertResultEquals

self:assertResultEquals(expected, text, message)

This method asserts that the first parameter equals the expansion of a string of wikitext. The second parameter can be any wikitext.

self:assertResultEquals(4, '{{#invoke:Calculator|add|2|2}}') -- true, assuming {{#invoke:Calculator|add|2|2}} equals 4

Note that some tags written in XML notation do not evaluate correctly using this method. (See #assertTemplateEquals.)

assertSameResult

self:assertSameResult(text1, text2, message)

This method asserts that the expansion of a given string of wikitext equals the expansion of another string of wikitext. This can be useful for verifying that a module behaves in the same way as a template it is intended to replace.

self:assertSameResult('{{add|2|2}}', '{{#invoke:Calculator|add|2|2}}') -- true, assuming {{add|2|2}} equals {{#invoke:Calculator|add|2|2}}