Package COM.INFORMATIMAGO.COMMON-LISP.CESARUM.SIMPLE-TEST

This package defines a simple test tool.

   (define-test <test-name> (<test-arguments>)
     (check = (fact 3) 6)
     (assert-true   <expr> (<place>…) "message ~A" <arguments>…)
     (assert-false  <expr> (<place>…) "message ~A" <arguments>…)
     (if <test>
        (progress-success)
        (progress-failure-message '<expr> "message ~A" <arguments>…)))


Tests can be run in the scope of a WITH-DEBUGGER-ON-ERROR or a
WITH-DEBUGGER-ON-FAILURE macro, to enter the debugger when an error is
signaled during the test, or if a test fails.  This may be useful to
debug the test or the failure.

    (with-debugger-on-failure
       (test/all))

    ;; single shot testing:
    (testing
       (check = (fact 3) 6))

License:

    AGPL3

    Copyright Pascal J. Bourguignon 2010 - 2015

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.
    If not, see <http://www.gnu.org/licenses/>

*debug-on-error*

variable

Whether an error in a test should go to the debugger.

Initial value: NIL

*debug-on-failure*

variable

Whether a failure in a test should go to the debugger.

Initial value: NIL

*TEST-OUTPUT*

*verbose-progress*

variable

Whether to display dots or exclamation points while testing.

Initial value: NIL

*verbose-tally*

variable

Whether to print the number of successful, failed and performed tests.

Initial value: T

(assert-false expression &optional places format-control &rest format-arguments)

macro

Evaluates a test EXPRESSION and check it returns NIL
EXAMPLE:  (assert-false (/= 2 (+ 1 1))))

(assert-true expression &optional places format-control &rest format-arguments)

macro

Evaluates a test EXPRESSION and check it returns true.
EXAMPLE:  (assert-true (= 2 (+ 1 1))))

(check compare expression expected &optional places format-control &rest format-arguments)

macro

Evaluates a test EXPRESSION and compare the result with EXPECTED (evaluated) using the COMPARE operator.
EXAMPLE:  (test equal (list 1 2 3) '(1 2 3))

(define-test name parameters &body body)

macro

Like DEFUN, but wraps the body in test reporting boilerplate.
cf. TESTING.

(expect-condition condition-class expression)

macro

Evaluates a test EXPRESSION and check that it signals a condition of the specified CONDITION-CLASS.
CONDITION-CLASS: evaluated to a class name.
EXAMPLE:        (expect-condition 'division-by-zero (/ 1 0))

(progress-failure compare expression expected-result result &optional places format-control &rest format-arguments)

function

Indicates one more failed test, reporting the expression, the
expected and actual results, and the relevant places, in addition to a
formatted message.

(progress-failure-message expression message &rest arguments)

function

Indicates one more failed test, with a formatted MESSAGE and ARGUMENTS.

(progress-start)

function

Resets the progress counters (success/failure counts).

(progress-success)

function

Indicate one more successful test.

(progress-tally success-count failure-count)

function

When testing verbosely, prints the test tally, SUCCESS-COUNT and
FAILURE-COUNT.

SLOW-TEST

(test compare expression expected &optional places format-control &rest format-arguments)

macro

Deprecated, use CHECK instead.

(test-message format-control &rest format-arguments)

function

Formats the parameters on the *TEST-OUTPUT* when running the test verbosely
cf. VERBOSE, *VERBOSE-PROGRESS*

(testing &body body)

macro

Evaluates the body while tallying test successes and failures.

The functions PROGRESS-SUCCESS, PROGRESS-FAILURE and
PROGRESS-FAILURE-MESSAGE (eg. thru the macros ASSERT-TRUE,
ASSERT-FALSE, EXPECT-CONDITION and TEST), should only be called in the
dynamic context established by this TESTING macro.

cf. DEFINE-TEST.

(with-debugger-on-error &body body)

macro

When running tests in the dynamic context established by this macro,
errors will invoke the debugger instead of failing the test immediately.

(with-debugger-on-failure &body body)

macro

When running tests in the dynamic context established by this macro,
failures will invoke the debugger instead of failing the test immediately.