Simplified Interface

The primary goal of lisp-unit is to be as simple as possible to use. The functions for managing tests are being simplified to further this goal starting in Version 0.9.0. The simplified interface is compared below with the original. The rationale for the change is also provided.

Original Lisp-Unit	Simplified Lisp-Unit
(define-test name exp1 exp2 ...)	(define-test name exp1 exp2 ...)
(get-tests [package])	(list-tests [package])
(get-test-code name [package])	(test-code name [package])
(remove-tests names [package])	(remove-tests names [package])
(remove-all-tests [package])	(remove-tests :all [package]) | (remove-tests)
(run-all-tests package)	(run-tests :all [package]) | (run-tests)
(run-tests name1 name2 ...)	(run-tests names [package])

The only substantial difference between the original and the simplified interface is how tests are run and removed. In the original interface, the argument signatures for running and removing tests were fundamentally different. This wasn't just a consequence of different lambda lists, remove-tests and remove-all-tests were functions while run-tests and run-all-tests were macros. In practice, these differences generated the following cases of conceptual dissonance.

• Specific tests were run by passing unquoted test names to run-tests as &REST arguments. This could only be done for the current package. Specific tests were removed by passing a list of test names to remove-tests for an optionally specified package. This was a consequence of both different lambda lists and the fact that run-tests was a macro and remove-tests was a function.

• The package argument was optional for remove-all-tests, but mandatory for run-all-tests. run-tests was used to run all tests in the current package. This was a consequence of different lambda lists.

To resolve this conceptual dissonance in the simplified interface, tests are run using a single function, run-tests, and removed using a single function, remove-tests.

(remove-tests '(name1 name2 ...) [package])
(remove-tests :all [package])
(remove-tests)

(run-tests '(name1 name2 ...) [package])
(run-tests :all [package])
(run-tests)

Simplifying the interface to accept lists of test names also facilitates use with the test report. The test report object collects the test names for each category in lists. These lists can then be passed directly to run-tests or remove-tests.

LISP-UNIT 5 > (run-tests :all)
Unit Test Summary
 | 9 assertions total
 | 4 passed
 | 5 failed
 | 1 execution errors
 | 0 missing tests

#<TEST-RESULTS Total(9) Passed(4) Failed(5) Errors(1)>

LISP-UNIT 6 > (let ((*print-failures* t))
                (run-tests (failed-tests *)))
 | Failed Form: (MY-SQRT (* I I))
 | Expected 1 but saw 1/2
 | I => 1
 |
 | Failed Form: (MY-SQRT (* I I))
 | Expected 3 but saw 9/2
 | I => 3
 |
 | Failed Form: (MY-SQRT (* I I))
 | Expected 4 but saw 8
 | I => 4
 |
MY-SQRT: 2 assertions passed, 3 failed.

 | Failed Form: (MY-MAX 2 5)
 | Expected 5 but saw 2
 |
 | Failed Form: (MY-MAX -5 0)
 | Expected 0 but saw -5
 |
TEST-MY-MAX: 2 assertions passed, 2 failed, 1 execution errors.

Unit Test Summary
 | 9 assertions total
 | 4 passed
 | 5 failed
 | 1 execution errors
 | 0 missing tests

#<TEST-RESULTS Total(9) Passed(4) Failed(5) Errors(1)>

LISP-UNIT 7 > 

See the reference for the full description of these functions.