Usage

Test suite syntax

1. The test suite is initialised by calling the ScribuntoUnit:new constructor:

   local module = require('Module:<MODULENAME>')
   local suite = require('Module:ScribuntoUnit'):new()
   

2. The test suite registers methods prefixed with test as tests.

   function suite:test_someCall()
       self:assertEquals('expected value', module._someCall(123))
       self:assertEquals('other expected value', module._someCall(456))
   end
   
   function suite:test_someOtherCall()
       self:assertEquals('expected value', module._someOtherCall(123))
       self:assertEquals('other expected value', module._someOtherCall(456))
   end
   

   • Assertions for methods are called in each test. Tests can target a module method's functionality or any specific feature, at will.
   • Tests will generate an error message if they fail validation, resulting in the failure of the test suite. This information will appear in the third column of the test report table, as necessary.
   • Note that functions not prefixed by test will not appear in the test result table. These can be called as dependencies in the test suite.
3. The test suite instance is returned at the end of the module:

   return suite
   

Test suite execution

Validation failure messages

The last parameter of all `ScribuntoUnit` assertion methods is a message that is displayed in the third report column if validation fails.

function suite:test_SomeCall()
    self:assertEquals(
        "expected value",
        module._someCall(123),
        "validation failed for module._someCall(123)"
    )
end

Documentation

Package items

ScribuntoUnit:run(displayMode) (function)

Invocation entry point for running the tests. This method can be called without a frame, in which case it will use mw.log for output. However, the following assertion methods require template or wikitext expansions and will be skipped:

• ScribuntoUnit:assertResultEquals - requires frame:preprocess
• ScribuntoUnit:assertSameResult - requires frame:preprocess
• ScribuntoUnit:assertTemplateEquals - requires frame:expandTemplate

Parameter: displayMode Accepts:

• "table" - shows result report as a wikitext table that displays which test(s) failed and the failure message.
• "log" - shows result as a console log for debugging purposes. Skips frame-dependent assertions.
• "short" - displays result report as a short sentence.
• "tableshort" - as "short", unless there is a failing test. Then, as "table".

(string)

Usage:

• {{testunit|scrib}}
• {{#invoke:ScribuntoUnit|run|displayMode = <table/log>}}

ScribuntoUnit:new(o) (function • constructor)

Instantiates a new ScribuntoUnit for a test suite module. The developer can call this method with a table constructor/upvalue, or they can attach their methods to the returned instance's table.

Parameter: o a table with test functions. (table; optional)

Returns: Self-executable instance of ScribuntoUnit. (ScribuntoUnit)

Usage:

• local suite = require('Module:ScribuntoUnit'):new()
• return require('Module:ScribuntoUnit'):new(suite)

ScribuntoUnit:markTestSkipped(message) (function)

When used in a test, that test gets ignored, and the skipped count increases by one.

Parameter: message Optional description. (string; optional)

Error: ScribuntoUnit error with field skipped as true. (table)

ScribuntoUnit:assertTrue(actual, message) (function)

Assertion checking that the input evaluates as true as a Lua expression. In Lua, anything that isn't the false or nil primitives is "truthy".

Parameters:

• actual A Lua expression - potentially an upvalue or condition evaluated by the test suite.
• message Optional description of the test. (string; optional)

Error: ScribuntoUnit error with assertion failure, if the expression value is falsy. (table; optional)

Usage:

• suite:assertTrue(2 + 2 == 4)
• suite:assertTrue('foo')

ScribuntoUnit:assertFalse(actual, message) (function)

Assertion checking that the input evaluates as false as a Lua expression. In Lua, only the false and nil primitives are "falsy".

Parameters:

• actual A Lua expression - potentially a variable or condition evaluated by the test suite.
• message Optional description of the test. (string; optional)

Error: ScribuntoUnit error with assertion failure, if the expression value is truthy. (table; optional)

Usage:

• suite:assertFalse(2 + 2 == 5)
• suite:assertFalse(false)

ScribuntoUnit:assertStringContains(pattern, str, plain, message) (function)

Assertion testing for the presence of an expected pattern or string in an input string. If the string is not found, the error message shows the values of pattern and str. If str is more than 70 characters long, a truncated version is displayed in the error message. This method is useful for testing specific behaviours in complex wikitext.

Parameters:

• pattern Pattern or string to perform lookup with. (boolean; optional)
• str Target string to perform lookup on. (boolean; optional)
• plain Search with a plain string instead of a ustring pattern. Default: false. (boolean; optional)
• message Optional description of the test. (string; optional)

Usage:

• suite:assertStringContains("foo", "foobar")
• suite:assertStringContains("foo[", "foo[bar", true)

ScribuntoUnit:assertNotStringContains(pattern, str, plain, message) (function)

Assertion testing for the absence of an expected pattern or string in an input string. If the string is not found, the error message shows the values of pattern and str. This test method has similar validation and rendering behaviour to ScribuntoUnit:assertStringContains.

Parameters:

• pattern Pattern or string to perform lookup with. (boolean; optional)
• str Target string to perform lookup on. (boolean; optional)
• plain Search with a plain string instead of a ustring pattern. Default: false. (boolean; optional)
• message Optional description of the test. (string; optional)

Usage:

• suite:assertNotStringContains("baz", "foobar")
• suite:assertNotStringContains("[qux", "baz]qux", true)

ScribuntoUnit:assertEquals(expected, actual, message) (function)

Assertion for the strict equality of an input upvalue against an expected value. This method uses == instead of rawequal, thus supporting __eq metamethods where applicable. Tables and functions are compared by reference in the assertion (i.e. by whether they reference the same object).

If both parameters are numbers, the values are instead compared using ScribuntoUnit:assertWithinDelta with delta 1e-8 (0.00000001) since Lua numbers are represented as floating-point numbers with limited precision.

Parameters:

• expected Target Lua upvalue for comparison, generated by the test module.
• actual Value to compare against in the comparison, provided in the test suite.
• message Optional description of the test. (string; optional)

Usage: suite:assertEquals(4, calculator._add(2, 2), "2 + 2 should be 4")

ScribuntoUnit:assertWithinDelta(expected, actual, delta, message) (function)

Assertion for the numerical equivalence of a input upvalue against an expected numerical value, within a closed interval or "distance" (delta). Lua non-integer numbers are represented as double-precision floating-point numbers with limited precision. Generally, Lua numerical comparisons involve a rounding step by ${\displaystyle 2^{-55}}$ when one of the values is irrational. The slight error between the compared numbers means that Lua does not consider them equal. This necessitates a ranged comparison using a delta when handling these numbers.

Parameters:

• expected Numerical value to compare against, provided in the test suite. (number)
• actual Target Lua upvalue for comparison, generated by the test module. (number)
• delta Closed interval range to permit value difference within. Should range between 1e-8 and 1e-16. (number)
• message Optional description of the test. (string; optional)

Usage: suite:assertWithinDelta(0.1, calculator._subtract(0.3, 0.2), 1e-10)

ScribuntoUnit:assertDeepEquals(expected, actual, message) (function)

Assertion for the recursive equivalence of two tables. This function works by computing the path to every primitive in the tables, then comparing them by reference. Respects the __eq metamethod of the expected table.

If a non-table value is provided for expected and actual, the values are assumed to be primitives and compared by reference.

Parameters:

• expected Target Lua upvalue for recursive comparison, provided in the test suite. (table)
• actual Value to compare against in the recursive comparison, generated by the test module. (table)
• message Optional description of the test. (string; optional)

Usage: suite:assertDeepEquals({ { 1, 3 }, { 2, 4 } }, calculator._partition("odd", { 1, 2, 3, 4 }))

ScribuntoUnit:assertResultEquals(expected, text, message) (function)

Assertion for processing of unprocessed wikitext against an expected result.

Parameters:

• expected Processed wikitext output for comparison. (string)
• text Unprocessed wikitext to compare with. (string)
• message Optional description of the test. (string; optional)

Usage: suite:assertResultEquals("4", "{{calculator|addition|2|2}}")

ScribuntoUnit:assertSameResult(text1, text2, message) (function)

Assertion for comparison of two unprocessed wikitext strings.

Parameters:

• text1 Unprocessed wikitext for comparison. (string)
• text2 Unprocessed wikitext to compare with. (string)
• message Optional description of the test. (string; optional)

Usage: suite:assertSameResult("{{#expr: 2 + 2}}", "{{calculator|addition|2|2}}")

ScribuntoUnit:assertTemplateEquals(expected, template, args, message) (function)

Assertion for a template call comparison against expected output.

Parameters:

• expected Processed output to compare against. (string)
• template Template name, following MediaWiki transclusion syntax (e.g. : prefix for mainspace pages). (string)
• args Table of template arguments to pass. (table; optional)
• message Optional description of the test. (string; optional)

Usage: suite:assertTemplateEquals("4", "calculator", {"add", "2", "2"})

ScribuntoUnit:assertThrows(fn, expectedMessage, message) (function)

Assertion for an uncaught exception for a function call.

Parameters:

• fn The function to be tested via a protected call with no arguments. (function)
• expectedMessage Expected message to compare the thrown exception against. (boolean; optional)
• message Optional description of the test. (string; optional)

Usage: suite:assertThrows(error, "unknown error")

See also

Original module on Wikipedia