Skip to content

std::assertions

Assertion failure values produced by assert, refute, and testing.check.

assert condition returns True when a Bool condition is True. When the condition is False, the runtime constructs an AssertionFailure and propagates it as Result.Err, the same way ? propagates an Err. refute condition returns False when the condition is False.

assert result requires Ok(_), while refute result requires Err(_). assert maybe requires Some(_), while refute maybe requires None. These forms return the original subject value; use assert Pattern = expr when you want to extract payloads.

testing.check(expr) builds the same success or failure as an ordinary Result<Subject, AssertionFailure> value instead of propagating.

Import with import std::assertions.

struct AssertionValue
    expression: String
    value: String
    pipeline: List<AssertionPipelineStage>
end

One observed value while evaluating an assertion expression.

impl Debug for AssertionValue

fn inspect(value: AssertionValue) -> String

impl Debug.inspect

struct AssertionPipelineStage
    expression: String
    value: String
end

One observed value in a pipeline expression.

impl Debug for AssertionPipelineStage

fn inspect(value: AssertionPipelineStage) -> String

impl Debug.inspect

struct AssertionBinding
    name: String
    expression: String
    value: String
    pipeline: List<AssertionPipelineStage>
end

Extra context for failures such as assert valid, where the asserted expression is a binding. expression is the source expression that produced the binding’s value.

impl Debug for AssertionBinding

fn inspect(value: AssertionBinding) -> String

impl Debug.inspect

struct AssertionDetail
    label: String
    value: String
end

One assertion-authored detail row.

impl Debug for AssertionDetail

fn inspect(value: AssertionDetail) -> String

impl Debug.inspect

struct AssertionDetails
    reason: String = "assertion failed"
    actual: Maybe<String> = None
    expected: Maybe<String> = None
    details: List<AssertionDetail> = []
end

Additional details supplied by custom assertion values.

Bool remains the ordinary assertion value: False becomes an assertion failure and True succeeds. Types that implement Assertable can supply richer failure details while the runtime still adds source location, expression text, binding context, and observed sub-expression values.

actual is shown as an actual: row. When expected is given too and differs from it, the report shows a line diff of the two instead, the one a failed == over multi-line Strings shows: - lines are only in expected, + lines only in actual.

impl Debug for AssertionDetails

fn inspect(value: AssertionDetails) -> String

impl Debug.inspect

interface Assertable
    fn failure(value: self) -> Maybe<AssertionDetails>
end

Custom values that can be used with assert, refute, and testing.check.

failure(value) returns None when the value passes, or Some(details) when it fails. The runtime wraps those details in an AssertionFailure.

fn failure(value: self) -> Maybe<AssertionDetails>

interface Assertable

struct AssertionFailure
    line: Int64
    keyword: String
    expression: String
    reason: String
    actual: Maybe<String>
    binding: Maybe<AssertionBinding>
    values: List<AssertionValue>
    details: List<AssertionDetail>
    subtests: List<SubtestFailure> = []
end

Structured failure produced by assert, refute, testing.check and subtests.

actual is present when the failure report should show the whole assertion subject value, such as a non-matching Result or Maybe shape. binding is present when the assertion was made against a bound name and the runtime can show where that value came from. values captures observed sub-expressions such as the left and right sides of a comparison, plus value-bearing arguments to predicate calls. details captures custom explanation rows supplied by an Assertable value. subtests holds the failing rows of a subtests statement, whose keyword is "subtests", and is empty for every other failure.

fn format(failure: AssertionFailure) -> String

type function on AssertionFailure

Render this failure the same way nomi test and nomi run report it.

failure = AssertionFailure{
    line:       7,
    keyword:    "assert",
    expression: "False",
    reason:     "expected truth",
    actual:     None,
    binding:    None,
    values:     [],
    details:    [],
}

assert String.contains(AssertionFailure.format(failure), "assert False")

impl Debug for AssertionFailure

fn inspect(value: AssertionFailure) -> String

impl Debug.inspect

struct SubtestFailure
    row: String
    failure: AssertionFailure
end

One failing row of a subtests statement: the row, rendered as a values: row renders a value, and the failure that ended it.

impl Debug for SubtestFailure

fn inspect(value: SubtestFailure) -> String

impl Debug.inspect