UP | HOME

FiveAM — Unit Testing for Common Lisp

Table of Contents

Definition

fiveam is a Common Lisp unit testing framework. It provides test suites, test cases, and assertion macros. Tolk uses it for all interpreter tests.

Online documentation: github.com/lispci/fiveam

Forms Used in Tolk

test — define a named test

(fiveam:test arith-parse
  (is (eqo (make-instance 'num :n 32) (parse 32)))
  (is (eqo (make-instance 'plus
             :l (make-instance 'num :n 3)
             :r (make-instance 'num :n 4))
           (parse '(+ 3 4)))))

is — assertion

(is (= 7 (execute '(+ 3 4))))
(is (eqo expected-ast (parse '(+ (* 1 2) (+ 2 3)))))

is checks that its argument is non-nil. Failure prints the form and expected vs. actual values.

Running tests

;; Run all tests in the system
(asdf:test-system :tolk)

;; Run a single named test suite
(fiveam:run! 'tolk/arith/tests::arith-parse)

;; Run with verbose output
(fiveam::explain! (fiveam:run 'tolk/arith/tests::arith-parse))

Test suites

tolk/test is the top-level test system. Individual sub-packages define their own tests using fiveam:test. fiveam:run-all-tests (called by the ASDF test-op perform method in tolk.asd) runs everything.

eqo — structural equality for AST nodes

Because make-instance always creates fresh objects, CL's eq and eql cannot compare AST nodes by value. Tolk defines eqo in tests/object-equality.lisp:

  • Two ast-node instances are eqo when they are of the same class and all corresponding slot values are eqo.
  • For non-AST values, eqo falls back to eql.

This is the only assertion predicate used for AST comparison in tolk tests.

Loading

(ql:quickload :fiveam)

Related

  • Tolk — uses fiveam for all tests
  • Tolk Arith — tests: 4/4 parse, 3/3 interpret, 4/4 execute