-
Notifications
You must be signed in to change notification settings - Fork 19
Reference
Functions and macros exported by lisp-unit are listed on this page.
*print-summary*
*print-failures*
*print-errors*All of the lisp-unit print parameters are NIL by default. When set
to true, *print-summary* will print a pass, fail, and error summary
for each individual test when the tests are run. Similarly, setting
*print-failures* and *print-errors* to true prints failures and
executions errors for each individual assertion, respectively. In
addition, if any of the print parameters are set equal to true, the
individual test summaries are printed.
(define-test name exp1 exp2 ...)This macro defines a test called name with the expressions
specified, in the package specified by the value of *package* in
effect when define-test is executed. The expressions are assembled
into runnable code whenever needed by run-tests. Hence you can
define or redefine macros without reloading tests using those macros.
(remove-tests '(name1 name2 ...) [package])
(remove-tests :all [package])This function removes the listed tests for the given package. All
tests are removed if the keyword :all is provided instead of a list
of names. If no package is given, the value of *package* is used.
(run-tests '(name1 name2 ...) [package])
(run-tests :all [package])This macro runs the listed tests and reports the a summary of the
results. All tests are run if the keyword :all is provided instead
of a list. The package used is the value of *package* in effect when
the macro is expanded. run-tests returns a test-results object
containing the detailed test results. Test results are described in
the next section.
(use-debugger [flag])By default, errors that occur while running tests are simply counted
and ignored. You can change this behavior by calling use-debugger
with one of three possible flag values: t (the default) means your
Lisp's normal error handling routines will be invoked when errors
occur; :ask means you will be asked what to do when an error occurs,
and nil means errors are counted and ignored, i.e., the standard
behavior.
Details of the unit tests are recorded in a test-results object.
These details can be retrieved using the following functions.
(test-names <test-results>)Return a list of the tests that were evaluated to generate the results.
(failed-tests <test-results>)Return a list of the tests that contained failed assertions. This
command can be combined with run-tests and *print-failures* to
examine only tests that contained failures.
(error-tests <test-results>)Return a list of the tests that contained assertions with execution
errors. This function can be combined with run-tests and
*print-errors* to examine only tests that contained execution
errors.
(missing-tests <test-results>)Return a list of the tests that were not found in the test database.
(summarize-results <test-results>)Print a summary of the results in the test-results object.
All of the assertion forms are macros. They tally a failure if the associated predication returns false. Assertions can be made about return values, printed output, macro expansions, and even expected errors. Assertion form arguments are evaluated in the local lexical environment.
All assertion forms allow you to include additional expressions at the end of the form. These expressions and their values will be printed only when the test fails.
Return values are unspecified for all assertion forms.
(assert-eq value form [form1 form2 ...])
(assert-eql value form [form1 form2 ...])
(assert-equal value form [form1 form2 ...])
(assert-equalp value form [form1 form2 ...])
(assert-equality predicate value form [form1 form2 ...])These macros tally a failure if value is not equal to the result
returned by form, using the specified equality predicate. In
general, assert-equal is used for most tests. Example use of
assert-equality:
(assert-equality #'set-equal '(a b c) (unique-atoms '((b c) a ((b a) c))))(assert-true test [form1 form2 ...])
(assert-false test [form1 form2 ...])assert-true tallies a failure if test returns false. assert-false
tallies a failure if test returns true.
(assert-prints "output" form [form1 form2 ...])This macro tallies a failure if form does not print to standard output stream output equal to the given string, ignoring differences in beginning and ending newlines.
(assert-expands expansion form [form1 form2 ...])This macro tallies a failure if (macroexpand-1 form) does not
produce a value equal to expansion.
(assert-error condition-type form [form1 form2 ...])This macro tallies a failure if form does not signal an error that is equal to or a subtype of condition-type. Use error to refer to any kind of error. See condition types in the Common Lisp Hyperspec for other possible names. For example,
(assert-error 'arithmetic-error (foo 0))would assert that foo is supposed to signal an arithmetic error when passed zero.
Several predicate functions are exported that are often useful in writing tests with assert-equality.
(logically-equal value1 value2)This predicate returns true of the two values are either both true, i.e., non-NIL, or both false.
(set-equal list1 list2 [:test])This predicate returns true the first list is a subset of the second
and vice versa. :test can be used to specify an equality predicate.
The default is eql.
The floating point extensions to lisp-unit are presented in this
section. The original lisp-unit has been extended with predicate
functions and assertions to support numerical testing. The predicates
can be used with assert-equality or with the corresponding
assertions. All extensions are implemented using generic functions and
consequently can be specialized for user classes.
The internal default value of epsilon is is twice the appropriate
float epsilon (i.e. 2*single-float-epsilon or
2*double-float-epsilon). Epsilon can be controlled at a lexical
level using the package variable *epsilon*. If *epsilon* is set to
nil, the internal epsilon values are used. This is the default value
of epsilon.
(float-equal data1 data2 [epsilon])
(assert-float-equal value form [form1 form2 ...])Return true if the relative error between data1 and data2 is less
than epsilon. The assertion tallies the failure if value is not
equal to the result returned from form, using float-equal.
(sigfig-equal float1 float2 [significant-figures])
(assert-sigfig-equal value form [form1 form2 ...])Return true if float1 and float2 are equal to the specified
significant-figures. The default value of significant figures is 4,
set by the global variable *significant-figures*. The test tallies
the failure if value is not equal to the result returned from form,
using sigfig-equal.
(norm-equal data1 data2 [epsilon] [measure])
(assert-norm-equal value form [form1 form2 ...])Return true if the relative error norm between data1 and data2 is
less than epsilon.
(number-equal number1 number2 [epsilon] [type-eq-p])
(assert-number-equal value form [form1 form2 ...])Return true if the error between number1 and number2 is less than
epsilon. The numbers must be the same type unless type-eq-p is
t. For the comparison, both numbers are coerced to (complex double-float) and passed to float-equal. The test tallies the
failure if value is not equal to the result returned from form, using
number-equal.
(numerical-equal result1 result2 [:test])
(assert-numerical-equal value form [form1 form2 ...])Return true if the numerical result1 is equal to result2 as
defined by :test. The results can be numbers, sequences, nested
sequences and arrays. The test tallies the failure if value is not
equal to the result returned from form, using numerical-equal. In
general, test must be a function that accepts 2 arguments and returns
true or false.
The floating point functions can be specialized for user data types and aid in writing user specific predicates.
(default-epsilon value)Return the default epsilon for value.
(relative-error exact approximate)Return the relative error.
(sumsq data)Return the scaling parameter and the sum of the squares of the data.
(sump data p)Return the scaling parameter and the sum of the powers of p of the data.
(norm data [measure])Return the element-wise norm of the data.
(relative-error-norm exact approximate [measure])Return the relative error norm.