Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Modules and Contracts

Testing with rackunit

Write tests with rackunit: check-equal?, check-true, check-exn, test-case and test-suite, the test submodule and raco test, plus a runnable JavaScript mini test framework stand-in.

Contracts catch wrong kinds of values at boundaries. Tests catch wrong answers. Racket ships with rackunit, a small, friendly unit-testing library, and a command, raco test, that finds and runs tests in your modules. Together with submodules, they let you keep tests next to the code they check.

This lesson covers the common check- forms, grouping tests, the test submodule, and how a test framework works inside, with a JavaScript stand-in you can run.

rackunit and raco are not available on this site, so the Racket code is read-only and I do not print its output. The runnable block is a JavaScript stand-in implementing a minimal test runner.

Checks

A rackunit test is a call to a check- function. If the check passes, nothing happens; if it fails, you get a message with the expected and actual values and the source location.

RACKET
#lang racket
(require rackunit)

(define (square x) (* x x))

(check-equal? (square 4) 16)
(check-equal? (square -3) 9 "negatives square to positives")
(check-not-equal? (square 2) 5)
(check-true (even? (square 6)))
(check-false (string? (square 2)))
(check-pred number? (square 3))          ; predicate holds
(check-= (sqrt 2.0) 1.41421 0.0001)      ; within a tolerance
(check-exn exn:fail? (lambda () (/ 1 0)))  ; code must raise an error
(check-not-exn (lambda () (square 5)))

Most-used forms: check-equal? (uses equal?), check-eq?, check-true/check-false, check-pred, check-= for floating-point numbers, and check-exn which takes a predicate for the exception and a thunk (a function of no arguments) so the error can be caught. Wrapping the expression in (lambda () ...) is essential: if you wrote (check-exn exn:fail? (/ 1 0)), the division would fail before check-exn ran.

Always compare floating-point results with check-= and a tolerance, never check-equal?, since (+ 0.1 0.2) is not exactly 0.3.

Grouping: test-case and test-suite

For a test run with a summary, group checks:

RACKET
(require rackunit rackunit/text-ui)

(define square-tests
  (test-suite
   "square"
   (test-case "positive" (check-equal? (square 3) 9))
   (test-case "zero"     (check-equal? (square 0) 0))
   (test-case "negative" (check-equal? (square -4) 16))))

(run-tests square-tests)

A failure inside a test-case stops that case, but other cases still run, so you see all failing cases at once. Bare check- forms at the top of a module also report failures but do not stop the module.

The test submodule and raco test

The idiomatic setup places tests in a test submodule of the module being tested:

RACKET
#lang racket
(provide square)
(define (square x) (* x x))

(module+ test
  (require rackunit)
  (check-equal? (square 5) 25)
  (check-equal? (square -5) 25))

Running racket file.rkt does not execute the tests, but raco test file.rkt does. raco test . runs every test submodule and every file named like a test in a folder, and prints a summary such as the number of passed tests. This keeps tests in the same file, with access to private helpers (because module+ sees the enclosing module's definitions), and ships no test code with the program's normal run.

What good tests look like

  • One idea per test, with a name that says which.
  • Cover edges: empty list, one element, zero, negative numbers, very large input.
  • Test the failure path: that bad input raises the error you promised (check-exn).
  • No hidden state: each test sets up what it needs; avoid ordering dependencies.
  • Use before/after forms (before, after, around, or test-begin) for setup and cleanup when files or ports are involved.

Property-style testing is available too (rackcheck and the quickcheck family), which generates random inputs, but plain example tests cover most needs.

flowchart LR
  A["raco test file.rkt"] --> B["load module"]
  B --> C["run test submodule"]
  C --> D["each check passes or reports failure"]
  D --> E["summary and exit code"]

raco test returns a non-zero exit code on failure, which makes it easy to use in automation.

Stand-in: a mini test framework

This block implements checkEqual, checkExn and testCase, collecting results and printing a summary like a real runner would. It also shows the thunk rule for check-exn.

JS Stand-in: a tiny rackunit-style runner

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Two checks deliberately fail so you can see the report. The floating-point one fails because binary arithmetic cannot represent 0.1 + 0.2 exactly; that is why Racket provides check-= with a tolerance.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must check-exn receive a thunk such as (lambda () (/ 1 0))?

    An unwrapped expression is evaluated before check-exn runs, so the exception would escape the check.
  2. 2. Which check should you use to compare floating-point results?

    check-= accepts a tolerance, which avoids false failures from rounding error.
  3. 3. When does the code in (module+ test ...) run?

    The test submodule is skipped by a normal run and executed by raco test.
  4. 4. What is the benefit of test-case blocks?

    Each test case is isolated, so you see every failure in a single run.

Summary

  • rackunit provides check-equal?, check-true, check-pred, check-= and check-exn, among others.
  • Wrap code that should raise an error in a thunk for check-exn.
  • Group checks with test-case and test-suite for isolated, named results.
  • Put tests in (module+ test ...) and run them with raco test.
  • Compare floating-point numbers with a tolerance.

Next: Text Processing and Ports