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.

Expecter

Properties

values: { any }

Expecter.new

Expecter.new(...: any) → Expecter

Expecter:toBe

Assert that the returned values equal ... (via ==).

Expecter:toBe(...: any) → ()

Expecter:toNotBe

Assert that the first returned value does NOT equal value.

Expecter:toNotBe(value: any) → ()

Expecter:toExist

Assert that at least one value was returned.

Expecter:toExist() → ()

Expecter:toNotBeNil

Assert that the first returned value is not nil (and that something was returned).

Expecter:toNotBeNil() → ()

Expecter:toBeNil

Assert that the first returned value is nil.

Expecter:toBeNil() → ()

Expecter:toBeTrue

Assert that the first returned value is exactly true.

Expecter:toBeTrue() → ()

Expecter:toBeFalse

Assert that the first returned value is exactly false.

Expecter:toBeFalse() → ()

Expecter:toBeTruthy

Assert that the first returned value is truthy (not nil and not false).

Expecter:toBeTruthy() → ()

Expecter:toBeFalsy

Assert that the first returned value is falsy (nil or false).

Expecter:toBeFalsy() → ()

Expecter:toBeType

Assert that typeof(value) == expected.

Expecter:toBeType(expected: string) → ()

Expecter:toHaveLength

Assert that #value == length.

Expecter:toHaveLength(length: number) → ()

Expecter:toContain

Assert that a string contains item as a plain substring, or that a table contains item as a value.

Expecter:toContain(item: any) → ()

Expecter:toMatch

Assert that a string matches a Lua pattern.

Expecter:toMatch(pattern: string) → ()

Expecter:toBeGreaterThan

Expecter:toBeGreaterThan(n: number) → ()

Expecter:toBeLessThan

Expecter:toBeLessThan(n: number) → ()

Expecter:toBeGreaterThanOrEqual

Expecter:toBeGreaterThanOrEqual(n: number) → ()

Expecter:toBeLessThanOrEqual

Expecter:toBeLessThanOrEqual(n: number) → ()

Expecter:toBeCloseTo

Assert that two numbers are within epsilon of each other (default 1e-9).

Expecter:toBeCloseTo(expected: number, epsilon: number?) → ()

Expecter:toError

Assert that a function throws. If match is provided, the error message must match that Lua pattern.

Expecter:toError(match: string?) → ()

Expecter:toNotError

Assert that a function does NOT throw.

Expecter:toNotError() → ()

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

Run a single test-pass over one or more files and/or directories.

paths may be a single path or a list mixing files and directories. Directories are walked recursively for files matching *.test.luau; explicitly named files are run as-is (their suffix is not checked). Each test file must return a Suite. Results across every path are aggregated into one unified summary.

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

-- Run a mix of directories and individual files in one pass:
test.runAll({ "tests/", "src/foo.test.luau" })

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

test.runAll(paths: string | { string }, options: RunOptions?) → ()

Parameters

paths: string | { string }

A path, or a list of files/directories, to test.

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.