1.7.1 Macros

Macro: evaluate-thunks-concurrently x ¶

Evaluate a list of thunks concurrently using Guile Fibers.

Each zero-argument procedure in the list thunks is spawned inside its own concurrent fiber thread. This macro blocks the execution of the calling fiber until all spawned thunks have reported their results back through a shared channel.

Exceptions raised within individual fibers are caught safely to avoid hanging or silent termination, returning a formatted error string instead.

Note: The output list order corresponds to the exact completion order of the fibers, meaning it is non-deterministic.

(evaluate-thunks-concurrently
 (list (lambda () (sleep 1) 'delayed)
       (lambda () 'instant)))
⇒ (instant delayed)

1.7.2 Procedures

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

Returns a function taking a VC (veritas-context) that returns an assertion checking that expect and got are approximately equal.

Two values are considered approximately equal if their difference is smaller than epsilon.

This is useful for floating-point computations.

(assert-approximate #:expect 3.14
                    #:got 3.141
                    #:epsilon 0.01)

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

Returns a function taking a VC (veritas-context) that returns an assertion checking that expect and got are structurally equal using equal? predicate.

This is the standard assertion for comparing lists, strings, vectors, and other compound data structures.

It is a convenience wrapper around assert.

expect

The expected value.

got

The value to compare against.

name

A string to identify the assertion in the logs.

(assert-equal #:expect '(1 2 3)
              #:got '(1 2 3)
              #:name "Lists should match")

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

Returns a function taking a VC (veritas-context) that returns an assertion checking that expect and got are equivalent using eqv? predicate.

This is useful for comparing numbers, characters, and symbols where value equivalence matters.

It is a convenience wrapper around assert.

expect

The expected value.

got

The value to compare against.

name

A string to identify the assertion in the logs.

(assert-eqv #:expect 42
            #:got (+ 40 2))

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

Returns a function taking a VC (veritas-context) that returns an assertion that checks that a thunk (a procedure with no arguments) raises an error when called.

This is a crucial function for testing error-handling logic. It attempts to execute the provided thunk. If an error is caught during its execution, the assertion passes. If the thunk completes without raising an error, the assertion fails.

thunk

A procedure of no arguments to be executed.

name

A string to identify the assertion in the logs.

(assert-error (lambda ()
                      (sum-list-elements '(1 2 "a" 4)))
                    #:name
                    "Should fail when list contains non-numbers")
⇒ #<procedure 8f58ec5ce390 at veritas/assert.scm:69:2 (vc)>

;; Upon applying vc to the procedure we will compute the assertion:
`((assertion-successful . #t)
  (assertion-name "Should fail when list contains non-numbers"))

Procedure: assert-false x KEY: #:name ¶

Returns a function taking a VC (veritas-context) that returns an assertion checking that x is #f.

This is a convenience wrapper for boolean falsehood assertions.

(assert-false (< 5 2)
              #:name "5 is not less than 2")

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

Returns a function taking a VC (veritas-context) that returns an assertion that checks that a thunk (a procedure with no arguments) does not raise an error when called.

This is a crucial function for testing error-handling logic. It attempts to execute the provided thunk. If no error is caught during its execution, the assertion passes. If the thunk raises an error, the assertion fails.

thunk

A procedure of no arguments to be executed.

name

A string to identify the assertion in the logs.

(assert-no-error (lambda ()
                      (sum-list-elements '(1 2 "a" 4))))
⇒ #<procedure 8f58ec5ce390 at veritas/assert.scm:69:2 (vc)>

;; Upon applying vc to the procedure we will compute the assertion:
`((assertion-successful . #f))

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

Returns a function taking a VC (veritas-context) that returns an assertion checking that expect and got are not approximately equal.

This assertion passes when the difference between the values is greater than or equal to epsilon.

It is the inverse of assert-approximate.

(assert-not-approximate #:expect 3.14
                        #:got 3.5
                        #:epsilon 0.01)

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

Returns a function taking a VC (veritas-context) that returns an assertion checking that expect and got are not identical using eq?.

This assertion passes when the two values do not share identity.

It is the inverse of assert-eq.

(assert-not-eq #:expect '(1 2)
               #:got '(1 2))

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

Returns a function taking a VC (veritas-context) that returns an assertion checking that expect and got are not structurally equal using equal?.

This assertion is useful when testing for inequality of compound values.

It is the inverse of assert-equal.

(assert-not-equal #:expect '(1 2 3)
                  #:got '(1 2 4))

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

Returns a function taking a VC (veritas-context) that returns an assertion checking that expect and got are not equivalent using eqv?.

This assertion is useful when values should differ in meaning or representation.

It is the inverse of assert-eqv.

(assert-not-eqv #:expect 1
                #:got 2)

Procedure: assert-true x KEY: #:name ¶

Returns a function taking a VC (veritas-context) that returns an assertion checking that x is #t.

This is a convenience wrapper for boolean truth assertions.

(assert-true (> 5 2)
             #:name "5 is greater than 2")

Procedure: benchmark KEY: #:skip? #:name #:runs #:thunk ¶

Register a micro-benchmarking task block to assess execution latency characteristics.

Accepts configuration settings:

• skip?: When true, prevents the execution loop of this benchmarking definition.
• name: Descriptive tracking label used for diagnostics reporting.
• runs: An integer count specifying how many consecutive times to invoke the execution routine.
• thunk: A zero-argument lambda wrap containing the code sequence targeted for optimization evaluation.

Utilizes Guile’s native statistical profiler engine (statprof) to capture performance statistics and call-stack diagnostics across loop evaluations. Returns a benchmark-result record mapping details for each index.

Procedure: collect-assertion-successful xs ¶

Collect and flatten all assertion success statuses found in xs.

Processes the arbitrary test result tree or list structure xs, extracts all underlying assertion outcomes, and returns a flat list containing only booleans indicating success (#t) or failure (#f).

(collect-assertion-successful my-test-suite-record)
⇒ (#t #t #f #t)

Procedure: do-if-string-contained KEY: #:name #:restriction #:result ¶

Execute filtering on name against an execution substring restriction.

Performs a case-insensitive validation check. If restriction is specified and matched anywhere inside name, returns result. If no restriction filter is configured (#f), bypasses checks and cleanly forwards result.

Otherwise, if a restriction is specified but not found inside the name string, returns #f.

(do-if-string-contained #:name "User Authentication Unit Spec"
                        #:restriction "Auth"
                        #:result 'run-me)
⇒ run-me

Procedure: fisher-yates-shuffle xs ¶

Return a new list containing the elements of xs in a randomized permutation.

Implements the modern Fisher–Yates (also known as the Knuth) shuffle algorithm. To ensure optimal performance, the input list xs is copied into an internal vector to leverage O(1) random access and mutation. The elements are shuffled in-place within the vector before being converted back into a standard Scheme list.

Every invocation automatically re-initializes Guile’s internal *random-state* variable using system entropy via random-state-from-platform to ensure high-quality pseudo-random distribution.

If xs is empty or contains only a single element, it is returned unmodified.

(fisher-yates-shuffle '(1 2 3 4 5))
⇒ (4 1 5 3 2)  ; Note: Output is randomized and non-deterministic

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

Returns #t if the absolute difference between a and b is smaller than epsilon.

This is useful for comparing floating-point values where exact equality may not be reliable.

a

The first numeric value.

b

The second numeric value.

epsilon

The maximum allowed difference.

(is-approximate? 3.14159 3.14160
                 #:epsilon 0.0001)
⇒ #t

Procedure: suite name KEY: #:debug? #:shuffle? #:skip? #:concurrent? #:before-all #:after-all . tests ¶

Aggregate multiple relevant test definitions inside a structured module container named name.

Supports high-level execution choreography parameters:

• debug?: Prints full suite compilation dumps directly to stdout when set to #t.
• shuffle?: Shuffles the sequential order of embedded child tests to isolate side effects.
• skip?: Inhibits execution of this suite block completely when evaluated as true.
• concurrent?: Controls concurrent scheduling. When #t, uses asynchronous Guile Fiber blocks to execute tests concurrently.
• before-all: A global hook procedure executed once prior to launching any child tests.
• after-all: A global hook procedure executed once following the completion of all nested tests.

Returns a composite function wrapper mapping across standard validation configurations. Captures and isolation-binds all textual test output streams inside a single consolidated suite-result signature record.

Procedure: test name KEY: #:debug? #:shuffle? #:skip? #:before #:after . cases ¶

Construct an isolated, executable unit test block named name.

Defines individual specification properties via keyword parameters:

• debug?: When #t, prints raw assertion results dump structures directly to standard out.
• shuffle?: Instigates randomized execution ordering of internal cases via Fisher-Yates shuffle hooks.
• skip?: Completely aborts blocks from running when set to true.
• before: A lifecycle function hook that accepts a validation client (vc) executed prior to evaluations.
• after: A lifecycle function hook that accepts a validation client (vc) executed post evaluations.

Returns an execution closure capturing the system context, which evaluates all internal assertion cases sequentially. Standard output written during assertion tracking is safely bound, captured, and returned inside an encapsulated pre-test-result data structure.

(test "Addition Validation"
      #:before (lambda (vc) (display "Initializing..."))
      (assert-equal #:expect 4 #:got (+ 2 2)))

Procedure: veritas-run KEY: #:shuffle? #:concurrent? #:debug? #:reporter #:with-coverage? . tasks ¶

Top-level execution runtime wrapper engine designed to orchestrate test execution runs.

Evaluates positional task variables sequentially or concurrently, providing orchestration hooks:

• shuffle?: Shuffles top-level block entry components randomly before runner routing.
• concurrent?: Runs distinct suite closures asynchronously using lightweight concurrent fibers.
• debug?: Provides developer trace visibility parameters to stdout streams.
• reporter: Selects the designated printing formatter design structure.
• with-coverage?: Whether to measure test code coverage and produce an LCOV report.