recspecs: Expect Testing for Racket🔗ℹ

The expect form captures anything printed to the current output port while evaluating an expression and compares it to a string literal stored directly in the source file. Each use expands to a RackUnit test-case. When the environment variable RECSPECS_UPDATE is set and the expectation does not match, the file is rewritten with the new output instead of failing the test. When RECSPECS_UPDATE is not set and the expectation fails, a colorized diff is printed to help understand the mismatch. Updating can be restricted to a single test case by setting RECSPECS_UPDATE_TEST to the name shown for that case.

Verbose mode can be enabled by setting RECSPECS_VERBOSE or by parameterizing recspecs-verbose?. When enabled, captured output is echoed to the real output port as it is produced. For example:

For Emacs users, the accompanying "emacs/recspecs.el" file provides recspecs-update-at-point, which runs the current file under racket-test with those environment variables set for the expectation at the cursor position. After the test finishes the buffer is automatically reverted so that any updated expectations are reloaded from disk.

Use #:port 'stderr with expect, expect-file, expect-exn, or capture-output to record output written to the current error port instead of the output port. Pass 'both to capture from both ports simultaneously.

Output can be transformed before it is compared by parameterizing recspecs-output-filter. The parameter holds a procedure that receives the captured string and returns a new string used for the comparison and when updating:

The thunk that performs the test is executed via the procedure stored in recspecs-runner. The default simply calls the thunk, but it can be replaced to control the runtime context. For example, limit memory usage with a new custodian and redirect the error port:

(parameterize ([recspecs-runner

(lambda (th)

(call-in-nested-thread

(lambda ()

(custodian-limit-memory (current-custodian) (* 1024 1024))

(parameterize ([current-error-port (current-output-port)])

(th)))))])

(expect (begin

(display "oops" (current-error-port))

(make-bytes (* 2 1024 1024)))

"oops"))

(require recspecs)

(expect (displayln "hello") "hello\n")

It can be convenient to use at-exp for multi-line expectations:

#:lang at-exp racket

(require recspecs)

(expect (begin (displayln "hello") (displayln (+ 1 2)))

"hello""\n"

"3")

You can wrap any of the expectation forms with with-expectation and access the captured output with expectation-out:

(define log (make-expectation))

(with-expectation log

(expect (display "hi") "hi"))

(commit-expectation! log)

(displayln (expectation-out log))