cl-unit-test
cl-unit-test bootstraps quality and it has been tested by itself with 100% test code coverage.

Introduction

cl-unit-test package is a simple unit testing utility. cl-unit-test is released under MIT license, see LICENSE file for details.

cl-unit-test can be used in many ways in development process. Each assert and test can be evaluated individually or whole test file can be loaded to run all tests in a file. Since 0.3 cl-unit-test can be easily integrated to asdf, too.

cl-unit-test concepts are asserts, tests and test files. Asserts are the simpliest forms of unit tests. Different kind of asserts exists for different purposes. In fact only one would be feasible but to make assert writing easier different asserts are provided for testing true/false values and equality (in its all lisp forms).

A test is thought as set of asserts to be all checked for one test.

A test file may contain assert(s) or test(s) but usually file contains set of named tests.

Using

Tests can be run in several ways. Each assert can be evaluated, each def-test can be evaluated, test file containing assertions or def-tests can be loaded, or file(s) can be loaded using test-runner.

The test output is controlled by unit-test:*show-details* parameter and unit test formatter. Currently three different kind of formatters are provided and more can be implemented if needed. A simple unit test formatter outputs test results to stream, list formatter formats lists to stream and silent formatter does not output anything.

The file example.lisp contains sample unit test definition. Here is a sample run with Emacs+Slime+SBCL.

CL-USER> unit-test:*show-details*
NIL
CL-USER> (unit-test:assert-eql 'foo 'foo)
T
CL-USER> (unit-test:assert-eql 'foo 'bar)
TEST: 'BAR => BAR                                 Expected: FOO             FAIL
NIL
CL-USER> (setq unit-test:*show-details* t)
T
CL-USER> (unit-test:assert-eql 'foo 'foo)
TEST: 'FOO => FOO                                                             OK
T
CL-USER> (unit-test:def-test (foo) (unit-test:assert-eql 'foo 'foo))
TEST: 'FOO => FOO                                                             OK
FOO: 1/1 assertions passed, 0 failed
NIL
CL-USER> (unit-test:def-test (foo) (unit-test:assert-eql 'foo 'bar))
TEST: 'BAR => BAR                                 Expected: FOO             FAIL
FOO: 0/1 assertions passed, 1 failed
NIL
CL-USER> (setq unit-test:*show-details* nil)
NIL
CL-USER> (load "example")
EXAMPLE-TEST-CASE: 5/5 assertions passed, 0 failed
SAMPLE-FAILURE: 0/1 assertions passed, 1 failed
TEST FAILURE: Sample test failure.
SAMPLE-FAIL: 0/1 assertions passed, 1 failed
; in: LAMBDA NIL
;     (+ 1 A)
; 
; caught WARNING:
;   undefined variable: A

; 
; caught WARNING:
;   This variable is undefined:
;     A
; 
; compilation unit finished
;   caught 2 WARNING conditions
TEST: (+ 1 A) => The variable A is unbound.                                ERROR
SAMPLE-ERROR: 0/1 assertions passed, 1 failed
T
CL-USER> (unit-test:test-runner (directory "test/*.lisp"))
-- /home/smo/lisp/unit-test/trunk/test/unit-test-test.lisp -- 
UNIT-TEST-TRACKER: 37/37 assertions passed, 0 failed
ASSERT-T: 8/8 assertions passed, 0 failed
ASSERT-NIL: 8/8 assertions passed, 0 failed
ASSERT-EQ: 8/8 assertions passed, 0 failed
ASSERT-EQL: 8/8 assertions passed, 0 failed
ASSERT-EQUAL: 8/8 assertions passed, 0 failed
ASSERT-EQUALP: 8/8 assertions passed, 0 failed
FAIL: 4/4 assertions passed, 0 failed
/home/smo/lisp/unit-test/trunk/test/unit-test-test.lisp: 8/8 tests passed, 0 failed
TOTAL FILES: 1, 8/8 TESTS PASSED, 0 FAILED
NIL
CL-USER> 

Using with ASDF

Append a new defsystem after your existing defsystem and make new system to depend on your system. New systems components is specified by unit-test:unit-test-files component. unit-test-files takes a file pattern parameter and all matching files are loaded as tests.

Here is an simple example. Assuming the system is called 'sample' and test files are located under 'test' directory with common '-test.lisp' file postfix.

(in-package :common-lisp-user)

(require 'unit-test)

(defpackage sample-system
  (:use :asdf :common-lisp))

(in-package :sample-system)

(defsystem sample
  :name "A sample system definition"
  :description "This is a sample."
  :author "Sami Makinen <sami.o.makinen@gmail.com>"
  :version "0.1"
  :components ((:file "package")
               (:file "main" :depends-on ("package"))))

(defsystem sample-tests
  :name "Tests for sample"
  :description "This is a sample asdf system for integrated tests."
  :author "Sami Makinen <sami.o.makinen@gmail.com>"
  :version "0.1"
  :components ((unit-test:unit-test-files "test/*-test.lisp"))
  :depends-on (:sample))

Now evaluating (asdf:operate 'asdf:load-op 'sample-tests) would first load sample system and then load tests associated with it.

Mock functions

with-mock-function(s) macro is an experimental utility to override existing defuns with a mock function within the macro scope.

Installing

cl-unit-test is available at https://sourceforge.net/projects/cl-unit-test/.

Package can installed with asdf-install:

(asdf-install:install 'cl-unit-test)

ASDF-install package (obsolete) http://sourceforge.net/projects/cl-unit-test/files/cl-unit-test_0.7.tgz


cl-unit-test is one of the many Test Frameworks.