Module:Assert/doc

The Assert module contains several convenience functions for common assertion use cases.

Using the module

To use the module, it must first be imported at the top of your module.

local Assert = require('Module:Assert')

Once the module is imported, simply call any of its functions to use it.

Custom Message Assertions

Every assertion has an additional *Msg variant which allows the caller to provide its own error message and optionally string format arguments. These functions drop the arguments that are used for formatting the default message and instead take a single message argument. If additional arguments are passed in, the message argument will be treated as a format string and passed to the string.format along with the additional arguments.

The "isType" assertion

The isType assertion checks that a value is of an expected type. If the value is not one of the expected types, then the assertion fails and an error is raised.

The value argument is returned to the caller upon successful completion.

Parameters

Parameter	Type	Description
value	any	The value to test the assertion against.
expected	string or string[]	The expected type or list of types which value must be one of.
name	string?	The name of the parameter to use in the error message, or nil for a generic error message.

Example Usage

-- Succeeds: "Alice" is a string
Assert.isType('Alice', 'string', 'name')

-- Succeeds: 25 is a number or a string
Assert.isType(25, { 'string', 'number' }, 'age')

-- Fails: true is a boolean, but is expected to be a string
Assert.isType(true, 'string', 'height')

-- Fails with error message: 'This is a custom error, the value is actually a string'
Assert.isTypeMsg('abc', 'number', 'This is a custom error, the value was actually a %s', type('abc'))

The "exists" assertion

The isType assertion checks that a value is not nil. If the value is nil, then the assertion fails and an error is raised. This assertion also returns the value argument upon successful completion.

The value argument is returned to the caller upon successful completion.

Parameters

Parameter	Type	Description
value	any	The value to test the existence of.
name	string?	The name of the parameter to use in the error message, or nil for a generic error message.

Example Usage

--- Maps a quantity suffix to its exponent.
local UNIT_EXPONENTS = {
  'k' = 3,
  'm' = 6,
  'b' = 9,
  't' = 12
}

-- Succeeds: The value exists and is assigned to exponent.
local exponent = Assert.exists(UNIT_EXPONENTS['k'], 'exponent')

-- Fails: The value does not exist.
local exponent = Assert.exists(UNIT_EXPONENTS['p'], 'exponent')

-- Fails with custom error message: "Uh oh, something which should exist doesn't!"
local exponent = Assert.existsMsg(UNIT_EXPONENTS['p'], "Uh oh, something which should exist doesn't!")

The "isTrue/isFalse" assertions

The isTrue assertion checks that an expression evaluates to true. If the expression evaluates to false, then the assertion fails and an error is raised. The isFalse assertion functions the same way, but negates the logic.

These functions do not return the condition to the caller.

Parameters

Parameter	Type	Description
value	any	The expression to test the truthiness of.

Example Usage

-- Succeeds: 'Bob' has a length greater than 0.
Assert.isTrue(string.len('Bob') > 0)

-- Fails with message: '3 is not an even number.'
local number = 3
Assert.isTrueMsg(number % 2 == 0, '%d is not an even number.', number)

The "equal" and "notEqual" assertions

The equal assertion checks that two values are equal. If the values are unequal, then the assertion fails and an error is raised. The notEqual assertion functions the same way, but negates the logic.

These functions return both a and b to the caller.

Parameters

Parameter	Type	Description
a	any	The first value being compared.
b	any	The second value being compared.

Example Usage

-- Succeeds: a = 'hi', b = 'hi'
local a, b = Assert.equal('hi', 'hi')

-- Fails: 'Hello' and 'World' are not equal
Assert.equal('Hello', 'World')

-- Fails with custom error: 'These things just aren't the same'
local first, second = Assert.equalMsg(true, false, "These things just aren't the same")