Once the programmer has defined what the tests are these need to be run and the expected effects should be compared with the actual effects. FiveAM provides the function RUN for this purpose, RUN executes a number of tests and collects the results of each individual check into a list which is then returned. There are three types of test results: passed, failed and skipped, these are represented by TEST-RESULT objects.
Generally running a test will return normally, but there are two exceptional situations which can occur:
- An exception is signaled while running the test. If the variable *debug-on-error* is T than FiveAM will enter the debugger, otherwise a test failure (of type unexpected-test-failure) is returned. When entering the debugger two restarts are made available, one simply reruns the current test and another signals a test-failure and continues with the remaining tests.
- A circular dependency is detected. An error is signaled and a restart is made available which signals a test-skipped and continues with the remaining tests. This restart also sets the dependency status of the test to nil, so any tests which depend on this one (even if the dependency is not circular) will be skipped.
The functions RUN!, !, !! and !!! are convenient wrappers around RUN and EXPLAIN.
(define-condition circular-dependency (error) ((test-case :initarg :test-case)) (:report (lambda (cd stream) (format stream "A circular dependency wes detected in ~S." (slot-value cd 'test-case)))) (:documentation "Condition signaled when a circular dependency between test-cases has been detected."))