veritas_assert (Untitled Document)

1.1 (veritas assert)

Assertions for Veritas. The core procedure is ‘assert’, which compares a value against an expected one using whatever predicate you give it. The assert-* procedures below are thin wrappers around it, together with a few helpers for checking error handling.

Every assertion also has a Latin alias, following the Latin naming already used by the BDD helpers (dato, quando, tunc, ...): (proba ...) is (assert ...), aequalis is assert-equal, verus is assert-true, continet is assert-contains, and so on. An alias is the exact same procedure object as its English name, so keyword arguments, semantics and reporting are identical. The complete mapping is documented in the README and repeated in the alias block at the end of this file.

Procedures

1.1.1 Procedures

Procedure: aequalis KEY: #:expect #:got #:name #:timeout ¶

Assert that got is equal? to expect.

The usual choice for lists, strings, vectors and other compound values.

Procedure: aequivalens KEY: #:expect #:got #:name #:timeout ¶

Assert that got is eqv? to expect.

Good for numbers, characters and symbols, where value equivalence is what matters.

Procedure: assert KEY: #:expect #:got #:compare #:name #:timeout ¶

Return an assertion comparing got with expect using compare, a two-argument predicate such as equal?.

The assert-* wrappers below are built on this one. got is usually a plain value, but a list starting with compute, comp or computare is evaluated when the assertion runs instead: (assert #:got '(comp (+ 1 1)) ...) compares against 2. Deferring work that way is what makes it something a timeout can actually catch.

name labels the assertion in the report. timeout caps it in seconds; #f, the default, means no deadline.

(assert #:expect 3
        #:got (+ 1 1 1)
        #:compare equal?
        #:name "Ensuring addition works")

Procedure: assert-approximate KEY: #:expect #:got #:name #:timeout #:epsilon ¶

Assert that got is within epsilon of expect.

The default epsilon is 1.0e-8.

Procedure: assert-contains KEY: #:expect #:got #:name #:timeout ¶

Assert that the container expect contains got.

Works for strings (substring), lists and vectors (membership) and hash tables (key membership).

(assert-contains #:expect '(1 2 3) #:got 2)
(assert-contains #:expect "hello world" #:got "world")

Procedure: assert-empty KEY: #:got #:name #:timeout ¶: Assert that got is an empty list, vector or string.

Procedure: assert-eq KEY: #:expect #:got #:name #:timeout ¶

Assert that got is eq? to expect.

The strictest of the equality assertions; use it for symbols, booleans and anything compared by identity.

Procedure: assert-equal KEY: #:expect #:got #:name #:timeout ¶

Assert that got is equal? to expect.

The usual choice for lists, strings, vectors and other compound values.

Procedure: assert-eqv KEY: #:expect #:got #:name #:timeout ¶

Assert that got is eqv? to expect.

Good for numbers, characters and symbols, where value equivalence is what matters.

Procedure: assert-error thunk KEY: #:name #:timeout ¶

Return an assertion that thunk raises.

It fails if thunk returns normally. name labels it in the report and timeout caps it in seconds, as in assert.

(assert-error (lambda () (sum-list-elements '(1 2 "a" 4)))
              #:name "Should fail when list contains non-numbers")

Procedure: assert-false x KEY: #:name #:timeout ¶: Assert that x is #f.

Procedure: assert-in-range KEY: #:min #:max #:got #:name #:timeout ¶: Assert that got is within the inclusive range min–max.

Procedure: assert-length KEY: #:expect #:got #:name #:timeout ¶: Assert that got has expect elements (list, vector or string length).

Procedure: assert-matches KEY: #:pattern #:got #:name #:timeout ¶

Assert that the string got matches pattern.

pattern is a string or a compiled regexp.

(assert-matches #:pattern "^veri.*s$" #:got "veritas")

Procedure: assert-no-error thunk KEY: #:name #:timeout ¶

Return an assertion that thunk does not raise.

It fails if thunk raises. name labels it in the report and timeout caps it in seconds, as in assert.

Procedure: assert-not-approximate KEY: #:expect #:got #:name #:timeout #:epsilon ¶

Assert that got differs from expect by at least epsilon.

Inverse of assert-approximate.

Procedure: assert-not-contains KEY: #:expect #:got #:name #:timeout ¶

Assert that the container expect does not contain got.

Inverse of assert-contains.

Procedure: assert-not-empty KEY: #:got #:name #:timeout ¶: Assert that got is a non-empty list, vector or string.

Procedure: assert-not-eq KEY: #:expect #:got #:name #:timeout ¶

Assert that got is not eq? to expect.

Inverse of assert-eq.

Procedure: assert-not-equal KEY: #:expect #:got #:name #:timeout ¶

Assert that got is not equal? to expect.

Inverse of assert-equal.

Procedure: assert-not-eqv KEY: #:expect #:got #:name #:timeout ¶

Assert that got is not eqv? to expect.

Inverse of assert-eqv.

Procedure: assert-not-matches KEY: #:pattern #:got #:name #:timeout ¶

Assert that string got does not match regular expression pattern.

Inverse of assert-matches.

Procedure: assert-one-of KEY: #:expect #:got #:name #:timeout ¶: Assert that got is equal? to one of the elements of list expect.

Procedure: assert-raises thunk KEY: #:on #:predicate #:name #:timeout ¶

Assert that calling thunk raises an error.

By default any error satisfies the assertion. Pass on to require a specific error key (for example 'wrong-type-arg), or predicate, a procedure of (key args) returning #t for the expected error.

(assert-raises (lambda () (/ 1 0)))
(assert-raises (lambda () (+ 1 'a)) #:on 'wrong-type-arg)

Procedure: assert-true x KEY: #:name #:timeout ¶: Assert that x is #t.

Procedure: congruit KEY: #:pattern #:got #:name #:timeout ¶

Assert that the string got matches pattern.

pattern is a string or a compiled regexp.

(assert-matches #:pattern "^veri.*s$" #:got "veritas")

Procedure: continet KEY: #:expect #:got #:name #:timeout ¶

Assert that the container expect contains got.

Works for strings (substring), lists and vectors (membership) and hash tables (key membership).

(assert-contains #:expect '(1 2 3) #:got 2)
(assert-contains #:expect "hello world" #:got "world")

Procedure: errat thunk KEY: #:name #:timeout ¶

Return an assertion that thunk raises.

It fails if thunk returns normally. name labels it in the report and timeout caps it in seconds, as in assert.

(assert-error (lambda () (sum-list-elements '(1 2 "a" 4)))
              #:name "Should fail when list contains non-numbers")

Procedure: falsus x KEY: #:name #:timeout ¶: Assert that x is #f.

Procedure: idem KEY: #:expect #:got #:name #:timeout ¶

Assert that got is eq? to expect.

The strictest of the equality assertions; use it for symbols, booleans and anything compared by identity.

Procedure: inanis KEY: #:got #:name #:timeout ¶: Assert that got is an empty list, vector or string.

Procedure: intra KEY: #:min #:max #:got #:name #:timeout ¶: Assert that got is within the inclusive range min–max.

Procedure: is-approximate? a b KEY: #:epsilon ¶

Return #t when a and b differ by less than epsilon.

Useful for floating point, where exact equality rarely holds.

Procedure: longitudo KEY: #:expect #:got #:name #:timeout ¶: Assert that got has expect elements (list, vector or string length).

Procedure: make-assertion assertion ¶

Return assertion, a procedure of one validation client, as a case to run.

The returned procedure is tagged so the runner can tell an assertion from a task, and it records having run, which is how an assertion the body itself consumes - with value or ok?, say - stays an input to another case instead of becoming a case of its own.

It is also registered with the collector of the body being evaluated, if there is one. That registration is what keeps a body form that builds several assertions, such as the body of a let, from contributing only the value of its last expression. Building an assertion outside any body - at load time, or inside an assertion that runs later - simply registers nothing.

Procedure: non-aequalis KEY: #:expect #:got #:name #:timeout ¶

Assert that got is not equal? to expect.

Inverse of assert-equal.

Procedure: non-aequivalens KEY: #:expect #:got #:name #:timeout ¶

Assert that got is not eqv? to expect.

Inverse of assert-eqv.

Procedure: non-congruit KEY: #:pattern #:got #:name #:timeout ¶

Assert that string got does not match regular expression pattern.

Inverse of assert-matches.

Procedure: non-continet KEY: #:expect #:got #:name #:timeout ¶

Assert that the container expect does not contain got.

Inverse of assert-contains.

Procedure: non-errat thunk KEY: #:name #:timeout ¶

Return an assertion that thunk does not raise.

It fails if thunk raises. name labels it in the report and timeout caps it in seconds, as in assert.

Procedure: non-idem KEY: #:expect #:got #:name #:timeout ¶

Assert that got is not eq? to expect.

Inverse of assert-eq.

Procedure: non-inanis KEY: #:got #:name #:timeout ¶: Assert that got is a non-empty list, vector or string.

Procedure: non-propinquus KEY: #:expect #:got #:name #:timeout #:epsilon ¶

Assert that got differs from expect by at least epsilon.

Inverse of assert-approximate.

Procedure: proba KEY: #:expect #:got #:compare #:name #:timeout ¶