Types

Wisp's source is --!strict and ships a declaration module, so an LSP infers Suite and Assertion without annotations.

The file is src/types.d.luau. Requiring it at runtime returns an empty table — it exists only so the export type definitions are in scope. The internal modules consume it as local types = require("../types.d"); from a spec file, adjust the relative path to match your own layout.

At a glance

Type	Kind	Purpose
Action	record	One registered test.
AssertionFailure	record	One failure, as stored by the runner.
SuiteStats	record	Passed and failed names for one suite.
Suite	record + methods	A named group of actions.
Runner	record + methods	Collects suites, runs them, prints.
Assertion	record + methods	A chainable expectation.
Wisp	record + __call	The module you require.

Action

A registered test. A plain record — there is no Action class and no methods on it.

export type Action = {
    name: string,
    func: () -> (),
}

Field	Type	Contents
name	string	Printed in the report.
func	() -> ()	The test body, called with no arguments.

Stored in Suite._actions, in the order actions were added.

AssertionFailure

A single failure, as recorded by Runner:fail.

export type AssertionFailure = {
    name: string,
    message: string,
}

Field	Type	Contents
name	string	The action name.
message	string	The error text, tostringed and stored verbatim.

The message usually carries the position prefix the engine adds.

SuiteStats

The results for one suite.

export type SuiteStats = {
    passed: { string },
    failed: { AssertionFailure },
}

Field	Type	Contents
passed	{ string }	Passing action names, in run order.
failed	{ AssertionFailure }	Failures, in run order.

A suite counts as passed when #stats.failed == 0. Both arrays are always present, and empty for a registered suite with no results yet.

Suite

export type Suite = {
    _name: string,
    _actions: { Action },
    action: (Suite, string, () -> ()) -> Suite,
    run: (Suite, Runner) -> (),
}

Field	Type	Contents
_name	string	The suite name.
_actions	{ Action }	Registered actions, in insertion order.
action	(Suite, string, () -> ()) -> Suite	Appends an action, returns the suite.
run	(Suite, Runner) -> ()	Runs every action, reporting each result.

Underscore-prefixed fields are internal by convention. The run parameter is typed as Runner, but it only needs the reporter shape — anything with matching pass and fail works. See Suite:run.

Runner

export type Runner = {
    _suites: { Suite },
    _stats: { [string]: SuiteStats },
    registerSuite: (Runner, Suite) -> (),
    pass: (Runner, string, string) -> (),
    fail: (Runner, string, string, string) -> (),
    run: (Runner) -> ({number}, {number}),
    _report: (Runner, number) -> ({number}, {number}),
}

Field	Type	Contents
_suites	{ Suite }	Registered suites, in registration order.
_stats	{ [string]: SuiteStats }	One entry per registered suite name.
registerSuite	(Runner, Suite) -> ()	Registers a suite; ignored if the name is taken.
pass	(Runner, string, string) -> ()	suiteName, actionName.
fail	(Runner, string, string, string) -> ()	suiteName, actionName, message.
run	(Runner) -> ({number}, {number})	Runs all suites, prints, and returns the tallies.
_report	(Runner, number) -> ({number}, {number})	Prints the report and returns the tallies.

_report is internal. Both returns are the two-element tallies described in Return values. See Reading results for how to inspect _stats after a run.

Assertion

export type Assertion = {
    _expression: any,
    equalsTo: (Assertion, any) -> (),
    notEqualsTo: (Assertion, any) -> (),
    isTrue: (Assertion) -> (),
    isFalse: (Assertion) -> (),
    isNil: (Assertion) -> (),
    isNotNil: (Assertion) -> (),
    isNaN: (Assertion) -> (),
    isInf: (Assertion) -> (),
    isFinite: (Assertion) -> (),
    isType: (Assertion, string) -> (),
    throws: (Assertion) -> (),
    notThrows: (Assertion) -> (),
    contains: (Assertion, any) -> (),
    notContains: (Assertion, any) -> (),
}

Every method returns (), because a satisfied assertion returns nothing and a failed one raises. _expression is the wrapped value.

See Assertion for what each method asserts and its exact failure message.

Wisp

export type Wisp = {
    assume: (any) -> Assertion,
    suite: (string) -> Suite,
    __call: (Wisp) -> ({number}, {number}),
}

Field	Type	Contents
assume	(any) -> Assertion	Wraps a value in an Assertion.
suite	(string) -> Suite	Creates and registers a suite.
__call	(Wisp) -> ({number}, {number})	Runs the default runner, returning the tallies.

__call is why the module is callable: it is a table with a __call metamethod, and calling it delegates to Runner:run on the shared default runner, forwarding its return unchanged. The values are described in Return values. See The default runner.

Next

• API Reference — every page in one list.