Summary

Classes

Functions

API Reference

Classes

Suite

Properties

name: string

tests: { Test }

results: { TestResult }

beforeAll: ((() → ()))?

afterAll: ((() → ()))?

beforeEach: ((() → ()))?

afterEach: ((() → ()))?

Suite.new

Suite.new(name: string) → Suite

Suite:test

Register a test case.

Suite:test(name: string, runner: (() → ())) → ()

Suite:beforeAll

Run once before all tests in this suite.

Suite:beforeAll(fn: (() → ())) → ()

Suite:afterAll

Run once after all tests in this suite.

Suite:afterAll(fn: (() → ())) → ()

Suite:beforeEach

Run before each individual test.

Suite:beforeEach(fn: (() → ())) → ()

Suite:afterEach

Run after each individual test.

Suite:afterEach(fn: (() → ())) → ()

Suite:run

Execute all tests in the suite and print results.

Suite:run(filter: string?, compact: boolean?) → RunTotals

Parameters

filter: string?

Optional Lua pattern. When provided, only tests whose name matches the pattern are executed; the rest are skipped.

compact: boolean?

Print all tests on an accumulating single line

Returns

RunTotals

pass/fail/skip counts.

Functions

test.expect

test.expect(...: any) → Expecter

test.skip

Unconditionally skips the current test. Call at the top of a test body to mark it as not-yet-implemented or temporarily disabled.

suite:test("future feature", function()
    test.skip("not implemented yet")
end)

test.skip(reason: string?) → ()

Parameters

reason: string?

Optional human-readable reason shown in the test output.

test.skipIf

Conditionally skips the current test when condition is truthy. Use this for platform-specific tests, tests that require external services, or environment-dependent checks.

suite:test("unix permissions", function()
    test.skipIf(os.platform() == "windows", "unix-only test")
    -- ... test code ...
end)

test.skipIf(condition: any, reason: string?) → ()

Parameters

condition: any

When truthy, the test is skipped.

reason: string?

Optional reason shown in the test output.

test.runOne

Load and run a single .test.luau file.

test.runOne(path: string, options: RunOptions?) → RunTotals

Parameters

path: string

The path to the test file.

options: RunOptions?

Run options (exitOnFail, filter).

test.runAll

Walk path recursively for files matching *.test.luau. Each such file must return a Suite.

-- Run all tests:
test.runAll("tests/")

-- Run only tests with "crypto" in the name:
test.runAll("tests/", { filter = "crypto" })

test.runAll(path: string, options: RunOptions?) → ()

Parameters

path: string

The directory to search for test files.

options: RunOptions?

Run options (exitOnFail, filter).

Types

RunOptions

Options for runOne and runAll.

type RunOptions = { exitOnFail: boolean?, filter: string? }

exitOnFail: boolean?

Exit the process with code 1 when any test fails. Defaults to true.

filter: string?

Lua pattern matched against test names. Only matching tests run; the rest are skipped. Equivalent to Jest's -t / --testNamePattern.