Suite¶

A named group of actions. Suites are flat — there are no nested suites, no hooks, and no tags.

At a glance¶

Symbol	Kind	Signature	Description
`Suite.new`	function	`(name: string, runner: Runner) -> Suite`	Constructs a suite and registers it.
`Suite:action`	method	`(name: string, func: () -> ()) -> Suite`	Appends an action. Returns the suite.
`Suite:run`	method	`(reporter: Reporter) -> ()`	Runs every action, reporting each result.

Fields¶

Field	Type	Description
`_name`	`string`	The suite name, exactly as passed to the constructor.
`_actions`	`{ Action }`	Registered actions, in the order they were added.

Both are underscore-prefixed and internal by convention. _name is read by Runner:registerSuite, so any object passed to a runner as a suite must expose it.

`Suite.new(name, runner)`¶

Suite.new(name: string, runner: Runner): Suite

Constructs a suite and immediately registers it, by calling runner:registerSuite(self).

Parameter	Type	Description
`name`	`string`	Printed as the heading for this suite's actions.
`runner`	`Runner`	Anything with a `registerSuite` method.

Registration is a side effect of construction, so a nil runner raises on the first statement of the call.

The name is not validated. If runner already holds stats under this name, the registration is ignored — the suite object is still returned and still usable, but that runner will never run it. See Duplicate names.

`Suite:action`¶

Suite:action(name: string, func: () -> ()): Suite

Appends an action to _actions and returns the suite, which is what makes chaining work.

Parameter	Type	Description
`name`	`string`	Printed in the report.
`func`	`() -> ()`	The test body. Called with no arguments.

The return value is always the suite, never the action, so assigning the result to a variable yields a Suite.

Nothing is validated: a nil or non-function func is accepted at definition time and only fails when the action is run.

Actions run in the order they were added, and duplicate action names are allowed — both will run and both will be reported.

`Suite:run(reporter)`¶

Suite:run(reporter: Reporter): ()

Runs every action in order and reports each result. Returns nothing.

reporter is any table that responds to pass and fail with method syntax — it does not have to be a Runner. That is the extension point for custom output.

Reporter method	Signature	Called when
`pass`	`(self, suiteName: string, actionName: string)`	An action returned normally.
`fail`	`(self, suiteName: string, actionName: string, message: string)`	An action raised.

For each action, func is called inside a pcall. Because the loop has no early exit, a failure never stops the remaining actions.

The message passed to fail is tostring of whatever was raised, so it keeps the position prefix the engine adds, and is otherwise passed through verbatim without reformatting or truncation.

Both reporter methods are called as methods, so self is the reporter table.

Reporter errors are not caught

Only the action body is protected. A reporter that raises propagates straight out of Suite:run and aborts the remaining actions. Keep reporter code total.

Ordering¶

Suite:run iterates _actions in insertion order. Suites are run by Runner:run in registration order, so the full run order is every action of the first suite registered, then every action of the second, and so on.

Duplicate names¶

Because a runner keys its statistics by suite name, the first suite registered under a name wins. A second suite with the same name is silently skipped, its actions never run, and it never appears in the report. There is no warning.

Actions¶

An action is a plain record, not a class — there is no Action.new and no methods on it.

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

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

See Types for the exported definitions.

Next¶

Assertions — what you write inside an action.
Runner — the default reporter.