Macro DEFTEST

deftest name (group &key after after-pass after-fail when unless priority) body => name

Arguments:

name—a symbol.

group—a symbol.

after—a symbol or a list.

after-pass—a symbol or a list.

after-fail—a symbol or a list

when—a Lisp form.

unless—a Lisp form.

priority—a fixnum.

body—Lisp forms; may include declarations and a docstring.

Description:

Defines a test with the given name to be a member of the named group. If the group isn't yet defined, this defines it. The body should perform the test and return T if it succeeds or NIL if it fails. Signalling an error is also a failure. The keyword arguments control the order and conditions under which the test is run: the after, after-pass, and after-fail arguments may be either the name of an individual test or a list of names. This test will run after the test(s) named; tests named in the after-pass argument must pass before this test will be allowed to run, and tests named in the after-fail argument must fail before this test will be allowed to run. The when and unless arguments are forms to be evaluated, which return a true value if the test is to be performed (for when) or skipped (for unless), and NIL otherwise. The priority argument is a number; tests with lower priority values run earlier than tests with higher priority values, subject to the after, after-pass and after-fail constraints. If priority is not supplied, and a test with the given name already exists, the priority is left unchanged; if the test does not already exist the priority defaults to the number of tests defined so far, so tests tend to run in the order they're defined.

DEFTEST defines a function named TEST-name/group, which can be called manually to run an individual test. RUN-TESTS is used to run all tests in a group.

Macro ENSURE

ensure form => value => boolean

ensure form signals condition => boolean

Arguments:

form—a Lisp form.

value—a Lisp form.

condition—a symbol naming a condition.

Description:

The first form ensures that form evaluates to value, printing a short report if the test fails. The test is done using EQUAL. The number of values returned is also checked.

The second form ensures that the form signals the named condition, printing a short report if the test fails.

The ENSURE macro is only available in the body of a DEFTEST form.

Function RUN-TESTS

run-tests group &key skip break-on-fail => boolean

Arguments:

group—a symbol naming a group of tests.

skip—a list.

break-on-fail—a (generalized) boolean

Description:

Runs all of the runnable tests in the group, printing a pass or fail message for each test, and the processor time used. A list of tests to be skipped can be supplied in the skip argument (any tests which depend on those tests will also be skipped, of course). If the break-on-fail argument is supplied non-nil, the failure of any test will cause a break, with restarts named TRY-AGAIN to retry the test and CONTINUE to accept the failure and continue with the next test. The default value for break-on-fail is given by the special variable *BREAK-ON-FAIL*.

The return value is NIL if any test failed, T otherwise. This allows test groups to be nested by simply writing a DEFTEST whose body runs the nested test group.

Variable *BREAK-ON-FAIL*

Value type: a (generalized) boolean

Initial value: NIL

Description:

The default value for the break-on-fail argument to RUN-TESTS.

Macro DEFINE-TEST-GROUP

define-test-group name &optional opts docstring => group

Arguments:

name—a symbol.

opts—a property list.

docstring—a string.

Description:

Defines a group of tests with the given name. opts may contain the keys :before and :after, whose values should be functions (or lambda expressions) to be called before and after all tests in the group have been run.

If the group already exists, the :before and :after functions are updated; the docstring and any tests already defined in the group are left unchanged.

Function ALL-TESTS

all-tests group => list

Arguments:

group—a symbol naming a group of tests.

Description:

Retrieve a list of the (names of) tests in the group, in the order in which they will run.