`nupp.test`

Assertions, for Nupp's own test runner and for project suites.

const test = nupp.test

test.equal(2 + 2, 4)
test.deepEqual({"ready", 200}, {"ready", 200})
test.matches(greeting, "^hello")
test.raises(function(): nil error("nope") end, "nope")

Every failure names the values that differed. An assertion returns the input it was given where that is useful, so one can narrow or validate a value in place rather than spelling it twice:

const name = test.assert(lookup(id), "no row for " .. id)

Module contents

Functions

Function	Kind	Description
`assert`	function	Requires a truthy value and returns its complete input pack.
`cases`	function	Builds ordinary named cases from a sequence of input rows.
`deepEqual`	function	Requires two values to be structurally equal and returns the actual value.
`equal`	function	Requires two values to be equal and returns the actual value.
`fact`	function	Attaches a structured fact to the current case result.
`fixture`	function	Resolves a content-addressed immutable fixture for the current case.
`isNotExecuted`	function	Returns whether a caught error marks a case as not executed.
`isSkip`	function	Returns whether a caught error is a skip raised by this module.
`matches`	function	Requires a string value containing a Lua pattern and returns the string.
`metric`	function	Adds a named measurement to the current case result.
`notEqual`	function	Requires two values to differ and returns the actual value.
`notExecuted`	function	Marks the current case as unavailable on this runtime.
`notExecutedReason`	function	Returns the reason carried by a not-executed error.
`raises`	function	Requires a callback to raise and returns its error value.
`requireCapability`	function	Requires a capability and records the evidence used to decide it.
`skip`	function	Skips the current test case with a reason.
`skipReason`	function	Returns the reason carried by a skip error.
`work`	function	Adds a deterministic integer work count to the current case result.

Functions#

`assert`function#

function assert(value: any, ...: any): any

Requires a truthy value and returns its complete input pack.

Arguments

Name	Type	Description
`value`	`any`
`...`	`any`

Returns

Type	Description
`any`

Raises

Type	Condition
`string`	when value is false or nil

`cases`function#

function cases(rows: {any}, name: function(any, integer): string, run: function(any, integer): any): any

Builds ordinary named cases from a sequence of input rows.

The returned table can be returned directly from a test suite or merged into a suite containing handwritten cases. Names must be stable and unique.

Arguments

Name	Type	Description
`rows`	`{any}`	the rows to expand
`name`	`function(any, integer): string`	returns the case name for a row
`run`	`function(any, integer): any`	runs a row

Returns

Type	Description
`any`	the named test cases

`deepEqual`function#

function deepEqual(actual: any, expected: any, message: string?): any

Requires two values to be structurally equal and returns the actual value.

Tables compare their own fields recursively. Keys must be booleans, numbers, or strings. Shared references do not have to use the same aliasing, and cycles compare by bisimulation. A shared __eq metamethod decides equality for its instances. Other leaves use native equality, so NaN differs from NaN and reference cdata compares by identity.

Arguments

Name	Type	Description
`actual`	`any`
`expected`	`any`
`message`	`string?`

Returns

Type	Description
`any`

Raises

Type	Condition
`string`	at the first differing path

`equal`function#

function equal(actual: any, expected: any, message: string?): any

Requires two values to be equal and returns the actual value.

Arguments

Name	Type	Description
`actual`	`any`
`expected`	`any`
`message`	`string?`

Returns

Type	Description
`any`

Raises

Type	Condition
`string`	when actual and expected differ

`fact`function#

function fact(name: string, value: any): nil

Attaches a structured fact to the current case result.

Arguments

Name	Type	Description
`name`	`string`	the fact kind
`value`	`any`	the JSON-compatible fact value

Returns

Type	Description
`nil`

`fixture`function#

function fixture(key: string, produce: function(string): any): string, any, boolean

Resolves a content-addressed immutable fixture for the current case.

The producer receives a private directory. Its JSON-compatible return value is published with that directory only when production succeeds.

Arguments

Name	Type	Description
`key`	`string`	the complete content key
`produce`	`function(string): any`	creates the fixture in a private directory

Returns

Type	Description
`string`	the published directory
`any`	the producer's persisted value
`boolean`	whether this call reused a previously published fixture

`isNotExecuted`function#

function isNotExecuted(value: any): boolean

Returns whether a caught error marks a case as not executed.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`boolean`

`isSkip`function#

function isSkip(value: any): boolean

Returns whether a caught error is a skip raised by this module.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`boolean`

`matches`function#

function matches(value: any, pattern: string, message: string?): string

Requires a string value containing a Lua pattern and returns the string.

Arguments

Name	Type	Description
`value`	`any`
`pattern`	`string`
`message`	`string?`

Returns

Type	Description
`string`

Raises

Type	Condition
`string`	when value is not a string or does not contain pattern

`metric`function#

function metric(name: string, value: number, unit: string?): nil

Adds a named measurement to the current case result.

Arguments

Name	Type	Description
`name`	`string`	the metric name
`value`	`number`	the additive measurement
`unit`	`string?`	the measurement unit

Returns

Type	Description
`nil`

`notEqual`function#

function notEqual(actual: any, unwanted: any, message: string?): any

Requires two values to differ and returns the actual value.

Arguments

Name	Type	Description
`actual`	`any`
`unwanted`	`any`
`message`	`string?`

Returns

Type	Description
`any`

Raises

Type	Condition
`string`	when actual and unwanted are equal

`notExecuted`function#

function notExecuted(reason: string): never

Marks the current case as unavailable on this runtime.

Arguments

Name	Type	Description
`reason`	`string`	why the case could not execute

Returns

Type	Description
`never`

`notExecutedReason`function#

function notExecutedReason(value: any): string?

Returns the reason carried by a not-executed error.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`string?`

`raises`function#

function raises(fn: function(...: any): any, pattern: string?): any

Requires a callback to raise and returns its error value.

Arguments

Name	Type	Description
`fn`	`function(...: any): any`
`pattern`	`string?`

Returns

Type	Description
`any`

Raises

Type	Condition
`string`	when the callback returns, or its error does not match pattern

`requireCapability`function#

function requireCapability(name: string, available: boolean, evidence: any?): nil

Requires a capability and records the evidence used to decide it.

A false requirement reports the case as not executed rather than passed, skipped, or failed.

Arguments

Name	Type	Description
`name`	`string`	the stable capability name
`available`	`boolean`	whether the runtime proved the capability
`evidence`	`any?`	structured evidence supporting the decision

Returns

Type	Description
`nil`

`skip`function#

function skip(reason: string): never

Skips the current test case with a reason.

Arguments

Name	Type	Description
`reason`	`string`

Returns

Type	Description
`never`

`skipReason`function#

function skipReason(value: any): string?

Returns the reason carried by a skip error.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`string?`

`work`function#

function work(name: string, count: integer): nil

Adds a deterministic integer work count to the current case result.

Arguments

Name	Type	Description
`name`	`string`	the counter name
`count`	`integer`	the additive count

Returns

Type	Description
`nil`

nupp.test

Module contents

Functions

Functions#

assertfunction#

Arguments

Returns

Raises

casesfunction#

Arguments

Returns

deepEqualfunction#

Arguments

Returns

Raises

equalfunction#

Arguments

Returns

Raises

factfunction#

Arguments

Returns

fixturefunction#

Arguments

Returns

isNotExecutedfunction#

Arguments

Returns

isSkipfunction#

Arguments

Returns

matchesfunction#

Arguments

Returns

Raises

metricfunction#

Arguments

Returns

notEqualfunction#

Arguments

Returns

Raises

notExecutedfunction#

Arguments

Returns

notExecutedReasonfunction#

Arguments

Returns

raisesfunction#

Arguments

Returns

Raises

requireCapabilityfunction#

Arguments

Returns

skipfunction#

Arguments

Returns

skipReasonfunction#

Arguments

Returns

workfunction#

Arguments

Returns

`nupp.test`

`assert`function#

`cases`function#

`deepEqual`function#

`equal`function#

`fact`function#

`fixture`function#

`isNotExecuted`function#

`isSkip`function#

`matches`function#

`metric`function#

`notEqual`function#

`notExecuted`function#

`notExecutedReason`function#

`raises`function#

`requireCapability`function#

`skip`function#

`skipReason`function#

`work`function#