Skip to main content

core.test

Utility helpers for declaring, running and reporting tests.

local test = require "core.test"

core.test.context​

Represents the execution context passed to hooks and test callbacks.

file​

(field) file: string

Absolute path of the loaded test file.

relative_file​

(field) relative_file: string

Path relative to the root passed to test.run().

core.test.file_result​

Represents the aggregated results for a single test file.

failed​

(field) failed: integer

items​

(field) items: core.test.item_result[]

passed​

(field) passed: integer

path​

(field) path: string

Absolute path of the loaded test file.

relative_path​

(field) relative_path: string

Path relative to the root passed to test.run().

skipped​

(field) skipped: integer

total​

(field) total: integer

core.test.item_result​

Represents a single reported test result.

duration​

(field) duration: number

Test execution time in seconds.

full_name​

(field) full_name: string

Fully qualified test name including parent suites.

message​

(field) message: string?

Failure or skip message.

name​

(field) name: string

Test case name without parent suite names.

path​

(field) path: string

Absolute path of the loaded test file.

relative_path​

(field) relative_path: string

Path relative to the root passed to test.run().

status​

(field) status: "failed"|"passed"|"skipped"

core.test.report_options​

Options used when reporting test results.

colorize​

(field) colorize: (fun(text: string, color: string):string)?

force_quit​

(field) force_quit: boolean?

quit​

(field) quit: fun(force: boolean, exit_code?: integer)?

quit_on_finish​

(field) quit_on_finish: boolean?

show_items​

(field) show_items: boolean?

write​

(field) write: fun(message: string)?

core.test.results​

Represents the aggregated results for a test run.

duration​

(field) duration: number

Total execution time in seconds.

failed​

(field) failed: integer

files​

(field) files: core.test.file_result[]

items​

(field) items: core.test.item_result[]

passed​

(field) passed: integer

root​

(field) root: string

Root path that was discovered.

skipped​

(field) skipped: integer

total​

(field) total: integer

core.test.run_options​

Options used when running a test suite.

on_complete​

(field) on_complete: fun(results: core.test.results|nil, err: string|nil, runner: core.test.runner)?

on_result​

(field) on_result: fun(item: core.test.item_result, file_results: core.test.file_result)?

core.test.runner​

Represents an async test run started with test.run().

error​

(field) error: string?

path​

(field) path: string

results​

(field) results: (core.test.results)?

Represents the aggregated results for a test run.

status​

(field) status: "error"|"failed"|"passed"|"running"

thread​

(field) thread: thread

Provides threading capabilities.

core.test.status​

core.test.status:
    | "passed"
    | "failed"
    | "skipped"

after_each​

function core.test.after_each(fn: fun(context: core.test.context))

Register a hook executed after every test in the current suite.

After hooks execute in reverse registration order.

before_each​

function core.test.before_each(fn: fun(context: core.test.context))

Register a hook executed before every test in the current suite.

contains​

function core.test.contains(container: string|table, value: any, message?: string)

Assert that a string or table contains a value.

describe​

function core.test.describe(name: string, fn: fun())
  -> suite: table

Create a named suite and register all tests declared within its callback.

Nested suites inherit before_each() and after_each() hooks from their ancestors and contribute to the reported full test name.

discover​

function core.test.discover(path: string)
  -> files: string[]|nil
  2. errmsg: string?

Discover Lua test files inside the given path.

If path points to a file, it is returned when it has a .lua extension. Directories are walked recursively and sorted lexicographically.

equal​

function core.test.equal(actual: <T>, expected: <T>, message?: string)
  -> <T>

Assert that two values are equal using Lua's == operator.

error​

function core.test.error(fn: fun(), expected?: string|fun(err: any):boolean, message?: string)
  -> err: any

Assert that a function raises an error.

When expected is a string it must be contained in the error text. When it is a function it is called with the raised error and must return truthy.

fail​

function core.test.fail(message?: string, level?: integer)

Fail the current test.

is_nil​

function core.test.is_nil(value: any, message?: string)

Assert that a value is nil.

it​

function

load_file​

function core.test.load_file(path: string)
  -> root: table|nil
  2. errmsg: string?

Load a Lua test file and return its registered root suite.

match​

function core.test.match(value: string, pattern: string, message?: string, plain?: boolean)
  -> string

Assert that a string matches a pattern.

@param plain — Treat pattern as a plain substring.

near​

function core.test.near(actual: number, expected: number, delta?: number, message?: string)
  -> number

Assert that two numbers are within a given delta.

no_error​

function core.test.no_error(fn: fun():<T>, message?: string)
  -> <T>

Assert that a function completes without raising an error.

not_equal​

function core.test.not_equal(actual: any, expected: any, message?: string)

Assert that two values are not equal using Lua's == operator.

not_nil​

function core.test.not_nil(value: <T>, message?: string)
  -> <T>

Assert that a value is not nil.

not_ok​

function core.test.not_ok(value: any, message?: string)

Assert that a value is falsy.

ok​

function core.test.ok(value: <T>, message?: string)
  -> <T>

Assert that a value is truthy.

report​

function core.test.report(results: core.test.results, options?: core.test.report_options)
  -> success: boolean

Write a formatted report for a full test run.

report_item​

function core.test.report_item(item: core.test.item_result, options?: core.test.report_options)

Write a formatted line for a single test result item.

run​

function core.test.run(path: string, options?: core.test.run_options)
  -> runner: core.test.runner|nil
  2. errmsg: string?

Run the given test file or directory asynchronously.

The returned runner is updated as the background thread advances and the optional callbacks in options are invoked as items complete.

same​

function core.test.same(actual: <T>, expected: <T>, message?: string)
  -> <T>

Assert that two values are deeply equal.

skip​

function core.test.skip(name: string, reason?: string)
  -> case: table

Register a skipped test case in the current suite.

skip_if​

function core.test.skip_if(condition: any, reason?: string)

Skip the current test when the given condition is truthy.

skip_now​

function core.test.skip_now(reason?: string)

Skip the current test immediately.

test​

function core.test.test(name: string, fn: fun(context: core.test.context))
  -> case: table

Register a test case in the current suite.

type​

function core.test.type(value: any, expected_type: string, message?: string)
  -> string

Assert that a value has the expected Lua type.