l0.DependencyControl.UnitTestSuite¶

MoonScriptLua

UnitTestSuite = require "l0.DependencyControl.UnitTestSuite"

local UnitTestSuite = require("l0.DependencyControl.UnitTestSuite")

UnitTest ¶

A class for all single unit tests. Provides useful assertion and logging methods for a user-specified test function.

Constructor ¶

MoonScriptLua

unitTest = UnitTest name, f, testClass

local unitTest = UnitTest(name, f, testClass)

Creates a single unit test. Instead of calling this constructor you'd usually provide test data in a table structure to UnitTestSuite() as an argument.

param	type	description
name	`string`	A descriptive title for the test.
f?	`fun(test: UnitTest, ...)`	The function containing the test code.
testClass	UnitTestClass	The test class this test belongs to.

Instance methods¶

run ¶

MoonScriptLua

unitTest\run ...

unitTest:run(...)

Runs the unit test function. In addition to the UnitTest object itself, it also passes the specified arguments into the function.

param	type	description
...	`any`	Optional modules or other data the test function needs.

Returns:

success boolean
errMsg string? — The error message describing how the test failed.

skip ¶

MoonScriptLua

unitTest\skip reason

unitTest:skip(reason)

Aborts the running test immediately and marks it skipped with the given reason. Call from within a test to gate it at runtime, e.g. on an unmet environment precondition.

param	type	description
reason?	`string`	Why the test is skipped; shown beside the skip marker and in the report.

stub ¶

MoonScriptLua

unitTest\stub tbl, key

unitTest:stub(tbl, key)

Replaces tbl[key] with a Stub and registers it for automatic cleanup after the test. If tbl is a string, looks up the module in package.loaded.

param	type	description
tbl	`table`\|`string`	The table (or module name) containing the value to replace.
key	`string`	The field name to stub.

Returns:

Stub

spy ¶

MoonScriptLua

unitTest\spy tbl, key

unitTest:spy(tbl, key)

Wraps tbl[key] with a Stub that forwards all calls to the original. The original value is restored automatically (LIFO) after the test completes.

param	type	description
tbl	`table`\|`string`	The table (or module name) containing the value to wrap.
key	`string`	The field name to spy on.

Returns:

Stub

stubModule ¶

MoonScriptLua

unitTest\stubModule name

unitTest:stubModule(name)

Replaces a whole module in the require cache with a stub, so a later require of that name yields the stub instead (configure it with \returns/\calls). Restored automatically after the test. Reach for this to swap a lazily-required collaborator wholesale, such as a class the code constructs; to intercept a single method of an already-required class, stub its __base field instead.

param	type	description
name	`string`	The module name, as passed to `require`.

Returns:

stub Stub — Standing in for the module until the test ends.

assertType ¶

MoonScriptLua

unitTest\assertType val, expected

unitTest:assertType(val, expected)

Fails the assertion if the specified value didn't have the expected type.

param	type	description
val	`any`	The value to be type-checked.
expected	`string`	The expected type.

assertSameType ¶

MoonScriptLua

unitTest\assertSameType actual, expected

unitTest:assertSameType(actual, expected)

Fails the assertion if the types of the actual and expected value didn't match.

param	type	description
actual	`any`	The actual value.
expected	`any`	The expected value.

assertBoolean ¶

MoonScriptLua

unitTest\assertBoolean val

unitTest:assertBoolean(val)

Fails the assertion if the specified value isn't a boolean.

param	type	description
val	`any`	The value expected to be a boolean.

assertBool ¶

MoonScriptLua

unitTest\assertBool val

unitTest:assertBool(val)

Shorthand for assertBoolean.

param	type	description
val	`any`	The value expected to be a boolean.

assertFunction ¶

MoonScriptLua

unitTest\assertFunction val

unitTest:assertFunction(val)

Fails the assertion if the specified value isn't a function.

param	type	description
val	`any`	The value expected to be a function.

assertNumber ¶

MoonScriptLua

unitTest\assertNumber val

unitTest:assertNumber(val)

Fails the assertion if the specified value isn't a number.

param	type	description
val	`any`	The value expected to be a number.

assertString ¶

MoonScriptLua

unitTest\assertString val

unitTest:assertString(val)

Fails the assertion if the specified value isn't a string.

param	type	description
val	`any`	The value expected to be a string.

assertTable ¶

MoonScriptLua

unitTest\assertTable val

unitTest:assertTable(val)

Fails the assertion if the specified value isn't a table.

param	type	description
val	`any`	The value expected to be a table.

assertTrue ¶

MoonScriptLua

unitTest\assertTrue val

unitTest:assertTrue(val)

Fails the assertion if the specified value isn't the boolean true.

param	type	description
val	`any`	The value expected to be `true`.

assertTruthy ¶

MoonScriptLua

unitTest\assertTruthy val

unitTest:assertTruthy(val)

Fails the assertion if the specified value doesn't evaluate to boolean true. In Lua this is only ever the case for nil and boolean false.

param	type	description
val	`any`	The value expected to be truthy.

assertFalse ¶

MoonScriptLua

unitTest\assertFalse val

unitTest:assertFalse(val)

Fails the assertion if the specified value isn't the boolean false.

param	type	description
val	`any`	The value expected to be `false`.

assertFalsy ¶

MoonScriptLua

unitTest\assertFalsy val

unitTest:assertFalsy(val)

Fails the assertion if the specified value doesn't evaluate to boolean false. In Lua nil is the only other value that evaluates to false.

param	type	description
val	`any`	The value expected to be falsy.

assertNil ¶

MoonScriptLua

unitTest\assertNil val

unitTest:assertNil(val)

Fails the assertion if the specified value is not nil.

param	type	description
val	`any`	The value expected to be `nil`.

assertNotNil ¶

MoonScriptLua

unitTest\assertNotNil val

unitTest:assertNotNil(val)

Fails the assertion if the specified value is nil.

param	type	description
val	`any`	The value expected to not be `nil`.

assertInRange ¶

MoonScriptLua

unitTest\assertInRange actual, min, max

unitTest:assertInRange(actual, min, max)

Fails the assertion if a number is out of the specified range.

param	type	description
actual	`number`	The number expected to be in range.
min?	`number`	The minimum (inclusive) value.
max?	`number`	The maximum (inclusive) value.

assertLessThan ¶

MoonScriptLua

unitTest\assertLessThan actual, limit

unitTest:assertLessThan(actual, limit)

Fails the assertion if a number is not lower than the specified value.

param	type	description
actual	`number`	The number to compare.
limit	`number`	The lower limit (exclusive).

assertLessThanOrEquals ¶

MoonScriptLua

unitTest\assertLessThanOrEquals actual, limit

unitTest:assertLessThanOrEquals(actual, limit)

Fails the assertion if a number is not lower than or equal to the specified value.

param	type	description
actual	`number`	The number to compare.
limit	`number`	The lower limit (inclusive).

assertGreaterThan ¶

MoonScriptLua

unitTest\assertGreaterThan actual, limit

unitTest:assertGreaterThan(actual, limit)

Fails the assertion if a number is not greater than the specified value.

param	type	description
actual	`number`	The number to compare.
limit	`number`	The upper limit (exclusive).

assertGreaterThanOrEquals ¶

MoonScriptLua

unitTest\assertGreaterThanOrEquals actual, limit

unitTest:assertGreaterThanOrEquals(actual, limit)

Fails the assertion if a number is not greater than or equal to the specified value.

param	type	description
actual	`number`	The number to compare.
limit	`number`	The upper limit (inclusive).

assertAlmostEquals ¶

MoonScriptLua

unitTest\assertAlmostEquals actual, expected, margin

unitTest:assertAlmostEquals(actual, expected, margin)

Fails the assertion if a number is not within an expected value ± a specified margin.

param	type	description
actual	`number`	The actual value.
expected	`number`	The expected value.
margin?	`number`	The maximum (inclusive) acceptable margin of error (default 1e-8).

assertNotAlmostEquals ¶

MoonScriptLua

unitTest\assertNotAlmostEquals actual, value, margin

unitTest:assertNotAlmostEquals(actual, value, margin)

Fails the assertion if a number differs from another value by at most a specified margin. Inverse of assertAlmostEquals.

param	type	description
actual	`number`	The actual value.
value	`number`	The value being compared against.
margin?	`number`	The maximum (inclusive) margin of error for the numbers to be considered equal (default 1e-8).

assertZero ¶

MoonScriptLua

unitTest\assertZero actual

unitTest:assertZero(actual)

Fails the assertion if a number is not equal to 0 (zero).

param	type	description
actual	`number`	The value.

assertNotZero ¶

MoonScriptLua

unitTest\assertNotZero actual

unitTest:assertNotZero(actual)

Fails the assertion if a number is equal to 0 (zero). Inverse of assertZero.

param	type	description
actual	`number`	The value.

assertInteger ¶

MoonScriptLua

unitTest\assertInteger actual

unitTest:assertInteger(actual)

Fails the assertion if a specified number has a fractional component. All numbers in Lua share a common data type, which is usually a double, which is the reason this is not a type check.

param	type	description
actual	`number`	The value.

assertPositive ¶

MoonScriptLua

unitTest\assertPositive actual, includeZero

unitTest:assertPositive(actual, includeZero)

Fails the assertion if a specified number is less than or equal to 0.

param	type	description
actual	`number`	The value.
includeZero?	`boolean`	Consider 0 to be positive (default false).

assertNegative ¶

MoonScriptLua

unitTest\assertNegative actual, includeZero

unitTest:assertNegative(actual, includeZero)

Fails the assertion if a specified number is greater than or equal to 0.

param	type	description
actual	`number`	The value.
includeZero?	`boolean`	Consider 0 to be negative (default false).

assertEquals ¶

MoonScriptLua

unitTest\assertEquals actual, expected

unitTest:assertEquals(actual, expected)

Fails the assertion if the actual value is not equal to the expected value. On the requirements for equality see UnitTest:equals.

param	type	description
actual	`any`	The actual value.
expected	`any`	The expected value.

assertNotEquals ¶

MoonScriptLua

unitTest\assertNotEquals actual, expected

unitTest:assertNotEquals(actual, expected)

Fails the assertion if the actual value is equal to the expected value. Inverse of assertEquals.

param	type	description
actual	`any`	The actual value.
expected	`any`	The expected value.

assertIs ¶

MoonScriptLua

unitTest\assertIs actual, expected

unitTest:assertIs(actual, expected)

Fails the assertion if the actual value is not identical to the expected value. Uses the == operator, so in contrast to assertEquals, this compares tables by reference.

param	type	description
actual	`any`	The actual value.
expected	`any`	The expected value.

assertIsNot ¶

MoonScriptLua

unitTest\assertIsNot actual, expected

unitTest:assertIsNot(actual, expected)

Fails the assertion if the actual value is identical to the expected value. Inverse of assertIs.

param	type	description
actual	`any`	The actual value.
expected	`any`	The expected value.

assertItemsEqual ¶

MoonScriptLua

unitTest\assertItemsEqual actual, expected, onlyNumKeys

unitTest:assertItemsEqual(actual, expected, onlyNumKeys)

Fails the assertion if the items of one table aren't equal to the items of another. Unlike assertEquals this ignores table keys, so e.g. two numerically-keyed tables with equal items in a different order are still considered equal. By default only values at numerical indexes are compared (see UnitTest:itemsEqual for details).

param	type	description
actual	`table`	The first table.
expected	`table`	The second table.
onlyNumKeys?	`boolean`	Disable to also compare items with non-numerical keys, at a performance cost (default true).

assertItemsAre ¶

MoonScriptLua

unitTest\assertItemsAre actual, expected, onlyNumKeys

unitTest:assertItemsAre(actual, expected, onlyNumKeys)

Fails the assertion if the items of one table aren't identical to the items of another. Like assertItemsEqual this ignores table keys, but compares table items by reference. By default only values at numerical indexes are compared (see UnitTest:itemsEqual for details).

param	type	description
actual	`table`	The first table.
expected	`table`	The second table.
onlyNumKeys?	`boolean`	Disable to also compare items with non-numerical keys (default true).

assertContinuous ¶

MoonScriptLua

unitTest\assertContinuous tbl

unitTest:assertContinuous(tbl)

Fails the assertion if the numerically-keyed items of a table aren't continuous. The rationale is that when iterating a table with ipairs or retrieving its length with the

operator, Lua may stop processing once the item at index n is nil, hiding subsequent values.¶

param	type	description
tbl	`table`	The table to be checked.

assertMatches ¶

MoonScriptLua

unitTest\assertMatches str, pattern

unitTest:assertMatches(str, pattern)

Fails the assertion if a string doesn't match the specified pattern. Accepts a Lua string pattern or a compiled aegisub.re pattern object.

param	type	description
str	`string`	The input string.
pattern	`string`\|`userdata`	Lua pattern string or compiled aegisub.re pattern.

assertContains ¶

MoonScriptLua

unitTest\assertContains str, needle, caseSensitive, init

unitTest:assertContains(str, needle, caseSensitive, init)

Fails the assertion if a string doesn't contain a specified substring. Search is case-sensitive by default.

param	type	description
str	`string`	The input string.
needle	`string`	The substring to be found.
caseSensitive?	`boolean`	Disable for locale-dependent case-insensitive comparison (default true).
init?	`number`	The first byte to start the search at (default 1).

assertError ¶

MoonScriptLua

unitTest\assertError func, ...

unitTest:assertError(func, ...)

Fails the assertion if calling a function with the specified arguments doesn't make it throw an error.

param	type	description
func	`function`	The function to be called.
...	`any`	Arguments to be passed into the function.

Returns:

error any — The error raised by the function.

assertErrorMsgMatches ¶

MoonScriptLua

unitTest\assertErrorMsgMatches func, params, pattern

unitTest:assertErrorMsgMatches(func, params, pattern)

Fails the assertion if a function call doesn't raise an error message matching the specified pattern. Accepts a Lua string pattern or a compiled aegisub.re pattern object.

param	type	description
func	`function`	The function to be called.
params?	`table`	A table of arguments to be passed into the function (default {}).
pattern	`string`\|`userdata`	Lua pattern string or compiled aegisub.re pattern.

Class methods¶

equals ¶

MoonScriptLua

UnitTest.equals a, b, aType, bType

UnitTest.equals(a, b, aType, bType)

Compares equality of two specified arguments. Requirements for two values to be considered equal: [1] their types match [2] their metatables are equal [3] strings and numbers are compared by value; functions and cdata are compared by reference; tables must have equal values at identical indexes and are compared recursively (i.e. two table copies of {"a", {"b"}} are considered equal)

param	type	description
a	`any`	The first value.
b	`any`	The second value.
aType?	`string`	If already known, the type of the first value (small performance benefit).
bType?	`string`	The type of the second value.

Returns:

equal boolean — True if a and b are equal, otherwise false.

itemsEqual ¶

MoonScriptLua

UnitTest.itemsEqual a, b, onlyNumKeys, ignoreExtraAItems, requireIdenticalItems

UnitTest.itemsEqual(a, b, onlyNumKeys, ignoreExtraAItems, requireIdenticalItems)

Compares equality of two specified tables, ignoring table keys. Works much like UnitTest:equals, but doesn't require table keys to be equal between a and b: two tables are equal if an equal value is found in b for every value in a and vice versa. By default this only looks at numerical indexes, as this kind of comparison rarely makes sense for hash tables.

param	type	description
a	`table`	The first table.
b	`table`	The second table.
onlyNumKeys?	`boolean`	Disable to also compare items with non-numerical keys, at a performance cost (default true).
ignoreExtraAItems?	`boolean`	Make the comparison one-sided, ignoring items present in a but not in b (default false).
requireIdenticalItems?	`boolean`	Require table items to be identical (compared by reference) rather than equal (default false).

Returns:

equal boolean

Fields¶

field	type	description
msgs	`table`

UnitTestSetup ¶

A special case of the UnitTest class for a setup routine.

Instance methods¶

run ¶

MoonScriptLua

unitTestSetup\run!

unitTestSetup:run()

Runs the setup routine. Only the UnitTestSetup object is passed into the function. Values returned by the setup routine are stored to be passed into the test functions later.

Returns:

success boolean
retValsOrErr table|string — All returned values packed into a table on success, or the error message on failure.

UnitTestTeardown ¶

A special case of the UnitTest class for a teardown routine.

UnitTestClass ¶

Holds a unit test class, i.e. a group of unit tests with common setup and teardown routines.

Constructor ¶

MoonScriptLua

unitTestClass = UnitTestClass name, args, order, testSuite

local unitTestClass = UnitTestClass(name, args, order, testSuite)

Creates a new unit test class complete with a number of unit tests and optional setup and teardown. Instead of calling this constructor directly, prefer UnitTestSuite(), which takes a table of test functions and creates test classes automatically. * _setup: a UnitTestSetup routine * _teardown: a UnitTestTeardown routine * _order: alternative syntax to the order parameter * _condition: a predicate () -> boolean[, string reason] evaluated before the class runs; a falsy result skips the whole class (its tests are marked skipped, with the optional reason). Use it to gate environment-dependent tests, e.g. _condition: -> os.getenv("DEPCTRL_INTEGRATION") == "1".

param	type	description
name	`string`	A descriptive name for the test class.
args?	`table<string, function\|table>`	Test functions by name. Keys starting with "_" have special meaning and aren't added as regular tests:
order?	`string`[]	Test names in the desired execution order; only listed tests run when running the whole class. Unordered if omitted.
testSuite	UnitTestSuite	The suite this class belongs to.

Instance methods¶

run ¶

MoonScriptLua

unitTestClass\run abortOnFail, order

unitTestClass:run(abortOnFail, order)

Runs all tests in the unit test class in the specified order.

param	type	description
abortOnFail?	`boolean`	Stop testing once a test fails (default false).
order?	`string`[]	Overrides the default test order.

Returns:

success boolean
failed UnitTest[]|integer — On failure, the failed tests (or -1 when setup failed).

UnitTestSuiteControls ¶

A bundle of helper utilities handed to a suite's import function as its trailing argument.

Constructor ¶

MoonScriptLua

unitTestSuiteControls = UnitTestSuiteControls suite

local unitTestSuiteControls = UnitTestSuiteControls(suite)

param	type	description
suite	UnitTestSuite	The suite to expose controls for.

Instance methods¶

requireTest ¶

MoonScriptLua

unitTestSuiteControls\requireTest leaf

unitTestSuiteControls:requireTest(leaf)

Requires one of the suite's sibling test modules by its leaf name. Resolved against the test suite identifier, so the same call works for both the Aegisub-default and custom test locations (e.g. in CI environments).

param	type	description
leaf	`string`	The module name relative to the test root (e.g. "FileOps").

Returns:

module any — The loaded test module.

UnitTestSuite ¶

A DependencyControl unit test suite. Your test file/module must return a UnitTestSuite object in order to be recognized as a test suite.

Constructor ¶

MoonScriptLua

unitTestSuite = UnitTestSuite namespace, classes, order

local unitTestSuite = UnitTestSuite(namespace, classes, order)

Creates a complete unit test suite for a module or automation script. Using this constructor creates all test classes and tests automatically. * the subject under test: for a module its own ref; for an automation script a map of its registered macros keyed by name, each holding the macro's process/validate/isActive (populated as macros register, so read it inside test bodies, not while building test classes) * dependencies: a numerically keyed table of all modules required by the tested script/module (in order) * extras: any further arguments passed into register/registerMacros — a module's own table, or an automation script's testExports (the internals under test) * a UnitTestSuiteControls handed in as the final argument (e.g. for requireTest) Keys starting with "_" have special meaning and aren't added as regular tests (e.g. _order).

param	type	description
namespace	`string`	The namespace of the module or automation script to test.
classes	`table<string, table>\|fun(...): table`	The test classes by name, or a function that returns them. When a function, it receives:
order?	`string`[]	Test class names in the desired execution order; only listed classes run when running the whole suite. Unordered if omitted.

Instance methods¶

addClasses ¶

MoonScriptLua

unitTestSuite\addClasses classes

unitTestSuite:addClasses(classes)

Constructs test classes and adds them to the suite. Use this to add additional test classes to an existing UnitTestSuite object.

param	type	description
classes	`table<string, table>`	UnitTestClass constructor tables by name.

import ¶

MoonScriptLua

unitTestSuite\import ...

unitTestSuite:import(...)

Loads test classes from a function and adds them to the suite, passing in the specified arguments and a suite controller. Generally used for dependency injection (e.g. the DepCtrl runners pass in the module under test and its declared dependencies).

param	type	description
...	`any`	Arguments passed to the import function; a suite controls object is appended after them as its final argument.

Returns:

result false? — false when there was no import function to run, so nothing was loaded; nil once the classes have been imported.

registerMacros ¶

MoonScriptLua

unitTestSuite\registerMacros!

unitTestSuite:registerMacros()

Registers macros for running all or specific test classes of this suite. If the test script is placed in the appropriate directory (per the module/automation script namespace), DependencyControl handles this automatically.

run ¶

MoonScriptLua

unitTestSuite\run abortOnFail, order

unitTestSuite:run(abortOnFail, order)

Runs all test classes of this suite in the specified order.

param	type	description
abortOnFail?	`boolean`	Stop testing once a test fails (default false).
order?	`string`[]	Overrides the default test class order.

Returns:

success boolean
failed UnitTest[]? — The failed tests, or nil on success.

toCtrf ¶

MoonScriptLua

unitTestSuite\toCtrf!

unitTestSuite:toCtrf()

Builds a CTRF (Common Test Report Format) report of the most recent run. CTRF is a JSON test report schema understood by ready-made CI reporters (e.g. the ctrf-io/github-test-reporter action). See https://ctrf.io.

Returns:

report table — The CTRF report as a plain Lua table, ready to be JSON-encoded.

writeResults ¶

MoonScriptLua

unitTestSuite\writeResults path

unitTestSuite:writeResults(path)

Writes a CTRF JSON report of the most recent run to the given path. Any missing parent directories are created; Aegisub path tokens are expanded.

param	type	description
path	`string`	Destination file path.

Returns:

success boolean? — True on success, nil on failure.
err string? — An error message on failure.

Class methods¶

getDefaultTestSuiteRequireIdentifier ¶

MoonScriptLua

UnitTestSuite\getDefaultTestSuiteRequireIdentifier scriptType, namespace

UnitTestSuite:getDefaultTestSuiteRequireIdentifier(scriptType, namespace)

Returns the require specifier used to load DepCtrl test suites in Aegisub environments. In an Aegisub environment, test suites reside in '?user/automation/tests/DepUnit/(modules|macros)/.(moon|lua)'.

param	type	description
scriptType	ScriptType	A domain.ScriptType value (module or automation script).
namespace	`string`	The namespaced identifier of the package under test (e.g. 'l0.Functional').

Returns:

identifier string — The require specifier used to load the test suite.

getTestSuiteRequireIdentifier ¶

MoonScriptLua

UnitTestSuite\getTestSuiteRequireIdentifier scriptType, namespace

UnitTestSuite:getTestSuiteRequireIdentifier(scriptType, namespace)

Returns the require specifier used to load DepCtrl test suites in the current environment. Accepts a hook via the global variable DEPCTRL_UNIT_TEST_SUITE_REQUIRE_IDENTIFIER to be used by CLI/CI test runners loading the test suites from the source repo or other locations.

param	type	description
scriptType	ScriptType	A domain.ScriptType value (module or automation script).
namespace	`string`	The namespaced identifier of the package under test (e.g. 'l0.Functional').

Returns:

identifier string

require ¶

MoonScriptLua

UnitTestSuite\require suiteIdentifier

UnitTestSuite:require(suiteIdentifier)

Requires a test module or the entire test suite.

param	type	description
suiteIdentifier	`string`	The require specifier of the test suite to load. Use getTestSuiteRequireIdentifier to obtain it for Aegisub environments.

Returns:

test any — The loaded test suite module.

withTestExports ¶

MoonScriptLua

UnitTestSuite\withTestExports mod, exports

UnitTestSuite:withTestExports(mod, exports)

Reveals a module's private internals to its unit tests by storing them on the module's metatable.

param	type	description
mod	`T`	The module table (e.g. a class) to expose internals on.
exports	`table`	The internals to reveal to the module's tests.

Returns:

mod T — The module, unchanged apart from the hidden exports.

getTestExports ¶

MoonScriptLua

UnitTestSuite\getTestExports mod

UnitTestSuite:getTestExports(mod)

Returns the test exports attached to a module via withTestExports, or nil if it has none.

param	type	description
mod	`table`	The required module to read test exports from.

Returns:

exports table?

Fields¶

field	type	description
failures	`{ classname: string, name: string, error: string, isAssertion: boolean }[]`	The most recent run's failures as a flat list, each tagged as an assertion failure or an unexpected error (read-only).
UnitTest	UnitTest
UnitTestClass	UnitTestClass
UnitTestSuiteControls	UnitTestSuiteControls
Stub	Stub