The eos Reference Manual

Table of Contents

The eos Reference Manual

This is the eos Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Feb 19 20:27:20 2020 GMT+0.

1 Introduction

Eos was a unit testing library for Common Lisp.

It began as a fork of FiveAM; however, FiveAM development has continued, while that of Eos has not. Thus, Eos is now deprecated in favor of FiveAM.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 eos

Author

Adlai Chandrasekhar

License

MIT

Description

UNMAINTAINED fork of 5AM, a test framework

Source

eos.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 eos/src

Parent

eos (system)

Location

src/

Components

• package.lisp (file)
• utils.lisp (file)
• classes.lisp (file)
• check.lisp (file)
• test.lisp (file)
• explain.lisp (file)
• suite.lisp (file)
• run.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 eos.asd

Location

eos.asd

Systems

eos (system)

4.1.2 eos/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

eos

4.1.3 eos/src/utils.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/utils.lisp

Internal Definitions

• acond2 (macro)
• aif (macro)
• binding (function)
• collect (macro)
• ensure-list (function)
• find-vars (function)
• fun (macro)
• list-match (function)
• list-match-case (macro)
• varsymp (function)
• with-gensyms (macro)

4.1.4 eos/src/classes.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/classes.lisp

Internal Definitions

• depends-on (method)
• (setf depends-on) (method)
• description (method)
• (setf description) (method)
• detailed-text-explainer (class)
• explainer (class)
• name (method)
• (setf name) (method)
• runtime-package (method)
• (setf runtime-package) (method)
• simple-text-explainer (class)
• status (method)
• (setf status) (method)
• test-case (class)
• test-lambda (method)
• (setf test-lambda) (method)
• test-suite (class)
• testable-object (class)
• tests (method)
• (setf tests) (method)
• text-explainer (class)

4.1.5 eos/src/check.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/check.lisp

Exported Definitions

• *test-dribble* (special variable)
• fail (macro)
• finishes (macro)
• is (macro)
• is-false (macro)
• is-true (macro)
• pass (macro)
• signals (macro)
• skip (macro)

Internal Definitions

• actual-condition (method)
• (setf actual-condition) (method)
• add-result (function)
• bind-run-state (macro)
• check-failure (condition)
• process-failure (macro)
• reason (method)
• (setf reason) (method)
• reason (method)
• (setf reason) (method)
• test-case (method)
• (setf test-case) (method)
• test-case (method)
• (setf test-case) (method)
• test-expr (method)
• (setf test-expr) (method)
• test-expr (method)
• (setf test-expr) (method)
• test-failure (class)
• test-failure-p (generic function)
• test-failure-p (method)
• test-failure-p (method)
• test-passed (class)
• test-passed-p (generic function)
• test-passed-p (method)
• test-passed-p (method)
• test-result (class)
• test-skipped (class)
• test-skipped-p (generic function)
• test-skipped-p (method)
• test-skipped-p (method)
• unexpected-test-failure (class)
• with-*test-dribble* (macro)
• with-run-state (macro)

4.1.6 eos/src/test.lisp

Dependency

classes.lisp (file)

Parent

src (module)

Location

src/test.lisp

Exported Definitions

• *run-test-when-defined* (special variable)
• get-test (function)
• (setf get-test) (function)
• rem-test (function)
• test (macro)
• test-names (function)

Internal Definitions

*test* (special variable)

4.1.7 eos/src/explain.lisp

Dependencies

• classes.lisp (file)
• check.lisp (file)

Parent

src (module)

Location

src/explain.lisp

Exported Definitions

• *verbose-failures* (special variable)
• explain (generic function)
• explain (method)
• explain (method)

Internal Definitions

partition-results (function)

4.1.8 eos/src/suite.lisp

Dependencies

• test.lisp (file)
• utils.lisp (file)

Parent

src (module)

Location

src/suite.lisp

Exported Definitions

• def-suite (macro)
• in-suite (macro)
• in-suite* (macro)
• make-suite (function)

Internal Definitions

• %in-suite (macro)
• *suite* (special variable)
• def-suite* (macro)

4.1.9 eos/src/run.lisp

Dependencies

• suite.lisp (file)
• check.lisp (file)

Parent

src (module)

Location

src/run.lisp

Exported Definitions

• ! (function)
• !! (function)
• !!! (function)
• *debug-on-error* (special variable)
• *debug-on-failure* (special variable)
• debug! (function)
• explain! (function)
• results-status (function)
• run (function)
• run! (function)

Internal Definitions

• %run (generic function)
• %run (method)
• %run (method)
• %run (method)
• %run (method)
• *!!!* (special variable)
• *!!* (special variable)
• *!* (special variable)
• *initial-!* (special variable)
• *run-queue* (special variable)
• circular-dependency (condition)
• import-testing-symbols (function)
• resolve-dependencies (generic function)
• resolve-dependencies (method)
• resolve-dependencies (method)
• return-result-list (function)
• run-resolving-dependencies (generic function)
• run-resolving-dependencies (method)
• run-test-lambda (generic function)
• run-test-lambda (method)

5 Packages

Packages are listed by definition order.

5.1 eos

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• ! (function)
• !! (function)
• !!! (function)
• *debug-on-error* (special variable)
• *debug-on-failure* (special variable)
• *run-test-when-defined* (special variable)
• *test-dribble* (special variable)
• *verbose-failures* (special variable)
• debug! (function)
• def-suite (macro)
• explain (generic function)
• explain (method)
• explain (method)
• explain! (function)
• fail (macro)
• finishes (macro)
• get-test (function)
• (setf get-test) (function)
• in-suite (macro)
• in-suite* (macro)
• is (macro)
• is-false (macro)
• is-true (macro)
• make-suite (function)
• pass (macro)
• rem-test (function)
• results-status (function)
• run (function)
• run! (function)
• signals (macro)
• skip (macro)
• test (macro)
• test-names (function)

Internal Definitions

• %in-suite (macro)
• %run (generic function)
• %run (method)
• %run (method)
• %run (method)
• %run (method)
• *!!!* (special variable)
• *!!* (special variable)
• *!* (special variable)
• *initial-!* (special variable)
• *run-queue* (special variable)
• *suite* (special variable)
• *test* (special variable)
• acond2 (macro)
• actual-condition (generic function)
• actual-condition (method)
• (setf actual-condition) (method)
• (setf actual-condition) (generic function)
• add-result (function)
• aif (macro)
• bind-run-state (macro)
• binding (function)
• check-failure (condition)
• circular-dependency (condition)
• collect (macro)
• def-suite* (macro)
• depends-on (generic function)
• depends-on (method)
• (setf depends-on) (method)
• (setf depends-on) (generic function)
• description (generic function)
• description (method)
• (setf description) (method)
• (setf description) (generic function)
• detailed-text-explainer (class)
• ensure-list (function)
• explainer (class)
• find-vars (function)
• fun (macro)
• import-testing-symbols (function)
• list-match (function)
• list-match-case (macro)
• name (generic function)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• partition-results (function)
• process-failure (macro)
• reason (generic function)
• reason (method)
• (setf reason) (method)
• reason (method)
• (setf reason) (method)
• (setf reason) (generic function)
• resolve-dependencies (generic function)
• resolve-dependencies (method)
• resolve-dependencies (method)
• return-result-list (function)
• run-resolving-dependencies (generic function)
• run-resolving-dependencies (method)
• run-test-lambda (generic function)
• run-test-lambda (method)
• runtime-package (generic function)
• runtime-package (method)
• (setf runtime-package) (method)
• (setf runtime-package) (generic function)
• simple-text-explainer (class)
• status (generic function)
• status (method)
• (setf status) (method)
• (setf status) (generic function)
• test-case (generic function)
• test-case (method)
• (setf test-case) (method)
• test-case (method)
• (setf test-case) (method)
• (setf test-case) (generic function)
• test-case (class)
• test-expr (generic function)
• test-expr (method)
• (setf test-expr) (method)
• test-expr (method)
• (setf test-expr) (method)
• (setf test-expr) (generic function)
• test-failure (class)
• test-failure-p (generic function)
• test-failure-p (method)
• test-failure-p (method)
• test-lambda (generic function)
• test-lambda (method)
• (setf test-lambda) (method)
• (setf test-lambda) (generic function)
• test-passed (class)
• test-passed-p (generic function)
• test-passed-p (method)
• test-passed-p (method)
• test-result (class)
• test-skipped (class)
• test-skipped-p (generic function)
• test-skipped-p (method)
• test-skipped-p (method)
• test-suite (class)
• testable-object (class)
• tests (generic function)
• tests (method)
• (setf tests) (method)
• (setf tests) (generic function)
• text-explainer (class)
• unexpected-test-failure (class)
• varsymp (function)
• with-*test-dribble* (macro)
• with-gensyms (macro)
• with-run-state (macro)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *debug-on-error*

T if we should drop into a debugger on error, NIL otherwise.

Package

eos

Source

run.lisp (file)

Special Variable: *debug-on-failure*

T if we should drop into a debugger on a failing check, NIL otherwise.

Package

eos

Source

run.lisp (file)

Special Variable: *run-test-when-defined*

When non-NIL tests are run as soon as they are defined.

Package

eos

Source

test.lisp (file)

Special Variable: *test-dribble*

Package

eos

Source

check.lisp (file)

Special Variable: *verbose-failures*

T if we should print the expression failing, NIL otherwise.

Package

eos

Source

explain.lisp (file)

6.1.2 Macros

Macro: def-suite NAME &key DESCRIPTION IN

Define a new test-suite named NAME.

IN (a symbol), if provided, causes this suite te be nested in the suite named by IN. NB: This macro is built on top of make-suite, as such it, like make-suite, will overrwrite any existing suite named NAME.

Package

eos

Source

suite.lisp (file)

Macro: fail &rest MESSAGE-ARGS

Simply generate a FAIL.

Package

eos

Source

check.lisp (file)

Macro: finishes &body BODY

Generates a pass if BODY executes to normal completion. In other words if body does signal, return-from or throw this test fails.

Package

eos

Source

check.lisp (file)

Macro: in-suite SUITE-NAME

Set the *suite* special variable so that all tests defined after the execution of this form are, unless specified otherwise, in the test-suite named SUITE-NAME.

See also: DEF-SUITE *SUITE*

Package

eos

Source

suite.lisp (file)

Macro: in-suite* SUITE-NAME &key IN

Just like in-suite, but silently creates missing suites.

Package

eos

Source

suite.lisp (file)

Macro: is TEST &rest REASON-ARGS

The DWIM checking operator.

If TEST returns a true value a test-passed result is generated, otherwise a test-failure result is generated. The reason, unless REASON-ARGS is provided, is generated based on the form of TEST:

(predicate expected actual) - Means that we want to check whether, according to PREDICATE, the ACTUAL value is
in fact what we EXPECTED.

(predicate value) - Means that we want to ensure that VALUE satisfies PREDICATE.

Wrapping the TEST form in a NOT simply preducse a negated reason string.

Package

eos

Source

check.lisp (file)

Macro: is-false CONDITION &rest REASON-ARGS

Generates a pass if CONDITION returns false, generates a failure otherwise. Like IS-TRUE, and unlike IS, IS-FALSE does not inspect CONDITION to determine what reason to give it case of test failure

Package

eos

Source

check.lisp (file)

Macro: is-true CONDITION &rest REASON-ARGS

Like IS this check generates a pass if CONDITION returns true and a failure if CONDITION returns false. Unlike IS this check does not inspect CONDITION to determine how to report the failure.

Package

eos

Source

check.lisp (file)

Macro: pass &rest MESSAGE-ARGS

Simply generate a PASS.

Package

eos

Source

check.lisp (file)

Macro: signals CONDITION-SPEC &body BODY

Generates a pass if BODY signals a condition of type CONDITION. BODY is evaluated in a block named NIL, CONDITION is not evaluated.

Package

eos

Source

check.lisp (file)

Macro: skip &rest REASON

Generates a TEST-SKIPPED result.

Package

eos

Source

check.lisp (file)

Macro: test NAME &body BODY

Create a test named NAME. If NAME is a list it must be of the form:

(name &key depends-on suite fixture compile-at)

NAME is the symbol which names the test.

DEPENDS-ON is a list of the form:

(AND . test-names) - This test is run only if all of the tests in TEST-NAMES have passed, otherwise a single test-skipped result is generated.

(OR . test-names) - If any of TEST-NAMES has passed this test is run, otherwise a test-skipped result is generated.

(NOT test-name) - This is test is run only if TEST-NAME failed.

AND, OR and NOT can be combined to produce complex dependencies.

If DEPENDS-ON is a symbol it is interpreted as ‘(AND ,depends-on), this is accomadate the common case of one test depending on another.

FIXTURE specifies a fixtrue to wrap the body in.

Package

eos

Source

test.lisp (file)

6.1.3 Functions

Function: ! ()

Rerun the most recently run test and explain the results.

Package

eos

Source

run.lisp (file)

Function: !! ()

Rerun the second most recently run test and explain the results.

Package

eos

Source

run.lisp (file)

Function: !!! ()

Rerun the third most recently run test and explain the results.

Package

eos

Source

run.lisp (file)

Function: debug! &optional TEST-SPEC

Calls (run! test-spec) but enters the debugger if any kind of error happens.

Package

eos

Source

run.lisp (file)

Function: explain! RESULT-LIST

Explain the results of RESULT-LIST using a detailed-text-explainer with output going to *test-dribble*

Package

eos

Source

run.lisp (file)

Function: get-test KEY &optional DEFAULT

Function: (setf get-test) VALUE KEY

Package

eos

Source

test.lisp (file)

Function: make-suite NAME &key DESCRIPTION IN

Create a new test suite object.

Overides any existing suite named NAME.

Package

eos

Source

suite.lisp (file)

Function: rem-test KEY

Package

eos

Source

test.lisp (file)

Function: results-status RESULT-LIST

Given a list of test results (generated while running a test) return true if all of the results are of type TEST-PASSED, faile otherwise.

Package

eos

Source

run.lisp (file)

Function: run TEST-SPEC

Run the test specified by TEST-SPEC.

TEST-SPEC can be either a symbol naming a test or test suite, or a testable-object object. This function changes the operations performed by the !, !! and !!! functions.

Package

eos

Source

run.lisp (file)

Function: run! &optional TEST-SPEC

Equivalent to (explain (run TEST-SPEC)).

Package

eos

Source

run.lisp (file)

Function: test-names ()

Package

eos

Source

test.lisp (file)

6.1.4 Generic functions

Generic Function: explain EXPLAINER RESULTS &optional STREAM RECURSIVE-DEPTH

Package

eos

Source

explain.lisp (file)

Methods

Method: explain (EXP detailed-text-explainer) RESULTS &optional STREAM RECURSIVE-DEPTH

Method: explain (EXP simple-text-explainer) RESULTS &optional STREAM RECURSIVE-DEPTH

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *!!!*

Package

eos

Source

run.lisp (file)

Special Variable: *!!*

Package

eos

Source

run.lisp (file)

Special Variable: *!*

Package

eos

Source

run.lisp (file)

Special Variable: *initial-!*

Package

eos

Source

run.lisp (file)

Special Variable: *run-queue*

List of test waiting to be run.

Package

eos

Source

run.lisp (file)

Special Variable: *suite*

The current test suite object

Package

eos

Source

suite.lisp (file)

Special Variable: *test*

Table containing all test and test suite objects.

Package

eos

Source

test.lisp (file)

6.2.2 Macros

Macro: %in-suite SUITE-NAME &key FAIL-ON-ERROR IN

Package

eos

Source

suite.lisp (file)

Macro: acond2 &rest CLAUSES

Package

eos

Source

utils.lisp (file)

Macro: aif TEST TRUE &optional FALSE

Package

eos

Source

utils.lisp (file)

Macro: bind-run-state REQUESTED-VARS &body BODY

Package

eos

Source

check.lisp (file)

Macro: collect NAMES &body BODY

Package

eos

Source

utils.lisp (file)

Macro: def-suite* NAME &rest DEF-SUITE-ARGS

Package

eos

Source

suite.lisp (file)

Macro: fun &body BODY

Package

eos

Source

utils.lisp (file)

Macro: list-match-case TARGET &body CLAUSES

Package

eos

Source

utils.lisp (file)

Macro: process-failure &rest ARGS

Package

eos

Source

check.lisp (file)

Macro: with-*test-dribble* STREAM &body BODY

Package

eos

Source

check.lisp (file)

Macro: with-gensyms (&rest SYMS) &body BODY

This is a simple WITH-GENSYMS, similar to the one presented in PCL.

Package

eos

Source

utils.lisp (file)

Macro: with-run-state REQUESTED-VARS &body BODY

Package

eos

Source

check.lisp (file)

6.2.3 Functions

Function: add-result RESULT-TYPE &rest MAKE-INSTANCE-ARGS

Create a TEST-RESULT object of type RESULT-TYPE passing it the initialize args MAKE-INSTANCE-ARGS and adds the resulting object to the list of test results.

Package

eos

Source

check.lisp (file)

Function: binding X BINDS

Package

eos

Source

utils.lisp (file)

Function: ensure-list X

Package

eos

Source

utils.lisp (file)

Function: find-vars SPEC ACC

Package

eos

Source

utils.lisp (file)

Function: import-testing-symbols PACKAGE-DESIGNATOR

Package

eos

Source

run.lisp (file)

Function: list-match X Y &optional BINDS

Package

eos

Source

utils.lisp (file)

Function: partition-results RESULTS-LIST

Package

eos

Source

explain.lisp (file)

Function: return-result-list TEST-LAMBDA

Run the test function TEST-LAMBDA and return a list of all test results generated, does not modify the special environment variable RESULT-LIST.

Package

eos

Source

run.lisp (file)

Function: varsymp X

Package

eos

Source

utils.lisp (file)

6.2.4 Generic functions

Generic Function: %run TEST-SPEC

Internal method for running a test. Does not update
the status of the tests nor the special vairables !, !!, or !!!

Package

eos

Source

run.lisp (file)

Methods

Method: %run (TEST test-case)

Method: %run (TESTS list)

Method: %run (SUITE test-suite)

Method: %run (TEST-NAME symbol)

Generic Function: actual-condition OBJECT

Generic Function: (setf actual-condition) NEW-VALUE OBJECT

Package

eos

Methods

Method: actual-condition (UNEXPECTED-TEST-FAILURE unexpected-test-failure)

automatically generated reader method

Source

check.lisp (file)

Method: (setf actual-condition) NEW-VALUE (UNEXPECTED-TEST-FAILURE unexpected-test-failure)

automatically generated writer method

Source

check.lisp (file)

Generic Function: depends-on OBJECT

Generic Function: (setf depends-on) NEW-VALUE OBJECT

Package

eos

Methods

Method: depends-on (TESTABLE-OBJECT testable-object)

Method: (setf depends-on) NEW-VALUE (TESTABLE-OBJECT testable-object)

The list of AND, OR, NOT forms specifying when to run this test.

Source

classes.lisp (file)

Generic Function: description OBJECT

Generic Function: (setf description) NEW-VALUE OBJECT

Package

eos

Methods

Method: description (TESTABLE-OBJECT testable-object)

Method: (setf description) NEW-VALUE (TESTABLE-OBJECT testable-object)

The textual description of this test object.

Source

classes.lisp (file)

Generic Function: name OBJECT

Generic Function: (setf name) NEW-VALUE OBJECT

Package

eos

Methods

Method: name (TESTABLE-OBJECT testable-object)

Method: (setf name) NEW-VALUE (TESTABLE-OBJECT testable-object)

A symbol naming this test object.

Source

classes.lisp (file)

Generic Function: reason OBJECT

Generic Function: (setf reason) NEW-VALUE OBJECT

Package

eos

Methods

Method: reason (CONDITION check-failure)

Method: (setf reason) NEW-VALUE (CONDITION check-failure)

Source

check.lisp (file)

Method: reason (TEST-RESULT test-result)

automatically generated reader method

Source

check.lisp (file)

Method: (setf reason) NEW-VALUE (TEST-RESULT test-result)

automatically generated writer method

Source

check.lisp (file)

Generic Function: resolve-dependencies DEPENDS-ON

Package

eos

Source

run.lisp (file)

Methods

Method: resolve-dependencies (DEPENDS-ON symbol)

A test which depends on a symbol is interpreted as ‘(AND ,DEPENDS-ON).

Method: resolve-dependencies (DEPENDS-ON list)

Return true if the dependency spec DEPENDS-ON is satisfied,nil otherwise.

Generic Function: run-resolving-dependencies TEST

Given a dependency spec determine if the spec is
satisfied or not, this will generally involve running other tests. If the dependency spec can be satisfied the test is also run.

Package

eos

Source

run.lisp (file)

Methods

Method: run-resolving-dependencies (TEST test-case)

Return true if this test, and its dependencies, are satisfied, NIL otherwise.

Generic Function: run-test-lambda TEST

Package

eos

Source

run.lisp (file)

Methods

Method: run-test-lambda (TEST test-case)

Generic Function: runtime-package OBJECT

Generic Function: (setf runtime-package) NEW-VALUE OBJECT

Package

eos

Methods

Method: runtime-package (TEST-CASE test-case)

Method: (setf runtime-package) NEW-VALUE (TEST-CASE test-case)

By default it stores *package* from the time this test was defined (macroexpanded).

Source

classes.lisp (file)

Generic Function: status OBJECT

Generic Function: (setf status) NEW-VALUE OBJECT

Package

eos

Methods

Method: status (TESTABLE-OBJECT testable-object)

Method: (setf status) NEW-VALUE (TESTABLE-OBJECT testable-object)

A symbol specifying the current status
of this test. Either: T - this test (and all its dependencies, have passed. NIL - this test
failed (either it failed or its dependecies weren’t met. :circular this test has a circular dependency and was skipped. Or :depends-not-satisfied or :resolving

Source

classes.lisp (file)

Generic Function: test-case OBJECT

Generic Function: (setf test-case) NEW-VALUE OBJECT

Package

eos

Methods

Method: test-case (CONDITION check-failure)

Method: (setf test-case) NEW-VALUE (CONDITION check-failure)

Source

check.lisp (file)

Method: test-case (TEST-RESULT test-result)

automatically generated reader method

Source

check.lisp (file)

Method: (setf test-case) NEW-VALUE (TEST-RESULT test-result)

automatically generated writer method

Source

check.lisp (file)

Generic Function: test-expr OBJECT

Generic Function: (setf test-expr) NEW-VALUE OBJECT

Package

eos

Methods

Method: test-expr (CONDITION check-failure)

Method: (setf test-expr) NEW-VALUE (CONDITION check-failure)

Source

check.lisp (file)

Method: test-expr (TEST-RESULT test-result)

automatically generated reader method

Source

check.lisp (file)

Method: (setf test-expr) NEW-VALUE (TEST-RESULT test-result)

automatically generated writer method

Source

check.lisp (file)

Generic Function: test-failure-p OBJECT

Package

eos

Source

check.lisp (file)

Methods

Method: test-failure-p O

Method: test-failure-p (O test-failure)

Generic Function: test-lambda OBJECT

Generic Function: (setf test-lambda) NEW-VALUE OBJECT

Package

eos

Methods

Method: test-lambda (TEST-CASE test-case)

Method: (setf test-lambda) NEW-VALUE (TEST-CASE test-case)

The function to run.

Source

classes.lisp (file)

Generic Function: test-passed-p OBJECT

Package

eos

Source

check.lisp (file)

Methods

Method: test-passed-p O

Method: test-passed-p (O test-passed)

Generic Function: test-skipped-p OBJECT

Package

eos

Source

check.lisp (file)

Methods

Method: test-skipped-p O

Method: test-skipped-p (O test-skipped)

Generic Function: tests OBJECT

Generic Function: (setf tests) NEW-VALUE OBJECT

Package

eos

Methods

Method: tests (TEST-SUITE test-suite)

Method: (setf tests) NEW-VALUE (TEST-SUITE test-suite)

The hash table mapping names to test
objects in this suite. The values in this hash table can be either test-cases or other test-suites.

Source

classes.lisp (file)

6.2.5 Conditions

Condition: check-failure ()

Signaled when a check fails.

Package

eos

Source

check.lisp (file)

Direct superclasses

error (condition)

Direct methods

• test-expr (method)
• test-expr (method)
• test-case (method)
• test-case (method)
• reason (method)
• reason (method)

Direct slots

Slot: reason

Initargs

:reason

Initform

(quote "no reason given")

Readers

reason (generic function)

Writers

(setf reason) (generic function)

Slot: test-case

Initargs

:test-case

Readers

test-case (generic function)

Writers

(setf test-case) (generic function)

Slot: test-expr

Initargs

:test-expr

Readers

test-expr (generic function)

Writers

(setf test-expr) (generic function)

Condition: circular-dependency ()

Condition signaled when a circular dependency between test-cases has been detected.

Package

eos

Source

run.lisp (file)

Direct superclasses

error (condition)

Direct slots

Slot: test-case

Initargs

:test-case

6.2.6 Classes

Class: detailed-text-explainer ()

Package

eos

Source

classes.lisp (file)

Direct superclasses

text-explainer (class)

Direct methods

explain (method)

Class: explainer ()

Package

eos

Source

classes.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

text-explainer (class)

Class: simple-text-explainer ()

Package

eos

Source

classes.lisp (file)

Direct superclasses

text-explainer (class)

Direct methods

explain (method)

Class: test-case ()

A test case is a single, named, collection of
checks.

A test case is the smallest organizational element which can be run individually. Every test case has a name, which is a symbol, a description and a test lambda. The test lambda is a regular funcall’able function which should use the various checking macros to collect results.

Every test case is part of a suite, when a suite is not explicitly specified (either via the :SUITE parameter to the TEST macro or the global variable *SUITE*) the test is inserted into the global suite named NIL.

Sometimes we want to run a certain test only if another test has passed. FiveAM allows us to specify the ways in which one test is dependent on another.

- AND Run this test only if all the named tests passed.

- OR Run this test if at least one of the named tests passed.

- NOT Run this test only if another test has failed.

FiveAM considers a test to have passed if all the checks executed were successful, otherwise we consider the test a failure.

When a test is not run due to it’s dependencies having failed a test-skipped result is added to the results.

Package

eos

Source

classes.lisp (file)

Direct superclasses

testable-object (class)

Direct methods

• %run (method)
• run-test-lambda (method)
• run-resolving-dependencies (method)
• runtime-package (method)
• runtime-package (method)
• test-lambda (method)
• test-lambda (method)

Direct slots

Slot: test-lambda

The function to run.

Initargs

:test-lambda

Readers

test-lambda (generic function)

Writers

(setf test-lambda) (generic function)

Slot: runtime-package

By default it stores *package* from the time this test was defined (macroexpanded).

Initargs

:runtime-package

Readers

runtime-package (generic function)

Writers

(setf runtime-package) (generic function)

Class: test-failure ()

Class for unsuccessful checks.

Package

eos

Source

check.lisp (file)

Direct superclasses

test-result (class)

Direct subclasses

unexpected-test-failure (class)

Direct methods

test-failure-p (method)

Class: test-passed ()

Class for successful checks.

Package

eos

Source

check.lisp (file)

Direct superclasses

test-result (class)

Direct methods

test-passed-p (method)

Class: test-result ()

All checking macros will generate an object of type TEST-RESULT.

Package

eos

Source

check.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• test-passed (class)
• test-failure (class)
• test-skipped (class)

Direct methods

• test-expr (method)
• test-expr (method)
• test-case (method)
• test-case (method)
• reason (method)
• reason (method)

Direct slots

Slot: reason

Initargs

:reason

Initform

"no reason given"

Readers

reason (generic function)

Writers

(setf reason) (generic function)

Slot: test-case

Initargs

:test-case

Readers

test-case (generic function)

Writers

(setf test-case) (generic function)

Slot: test-expr

Initargs

:test-expr

Readers

test-expr (generic function)

Writers

(setf test-expr) (generic function)

Class: test-skipped ()

A test which was not run. Usually this is due
to unsatisfied dependencies, but users can decide to skip test when appropiate.

Package

eos

Source

check.lisp (file)

Direct superclasses

test-result (class)

Direct methods

test-skipped-p (method)

Class: test-suite ()

A test suite is a collection of tests or test suites.

Test suites serve to organize tests into groups so that the developer can chose to run some tests and not just one or all. Like tests test suites have a name and a description.

Test suites, like tests, can be part of other test suites, this allows the developer to create a hierarchy of tests where sub trees can be singularly run.

Running a test suite has the effect of running every test (or suite) in the suite.

Package

eos

Source

classes.lisp (file)

Direct superclasses

testable-object (class)

Direct methods

• %run (method)
• tests (method)
• tests (method)

Direct slots

Slot: tests

The hash table mapping names to test
objects in this suite. The values in this hash table can be either test-cases or other test-suites.

Initform

(make-hash-table :test (quote eql))

Readers

tests (generic function)

Writers

(setf tests) (generic function)

Class: testable-object ()

Package

eos

Source

classes.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• test-suite (class)
• test-case (class)

Direct methods

• print-object (method)
• status (method)
• status (method)
• depends-on (method)
• depends-on (method)
• description (method)
• description (method)
• name (method)
• name (method)

Direct slots

Slot: name

A symbol naming this test object.

Initargs

:name

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: description

The textual description of this test object.

Initargs

:description

Readers

description (generic function)

Writers

(setf description) (generic function)

Slot: depends-on

The list of AND, OR, NOT forms specifying when to run this test.

Initargs

:depends-on

Readers

depends-on (generic function)

Writers

(setf depends-on) (generic function)

Slot: status

A symbol specifying the current status
of this test. Either: T - this test (and all its dependencies, have passed. NIL - this test
failed (either it failed or its dependecies weren’t met. :circular this test has a circular dependency and was skipped. Or :depends-not-satisfied or :resolving

Initargs

:status

Initform

:unknown

Readers

status (generic function)

Writers

(setf status) (generic function)

Class: text-explainer ()

Package

eos

Source

classes.lisp (file)

Direct superclasses

explainer (class)

Direct subclasses

• simple-text-explainer (class)
• detailed-text-explainer (class)

Class: unexpected-test-failure ()

Represents the result of a test which neither
passed nor failed, but signaled an error we couldn’t deal with.

Note: This is very different than a SIGNALS check which instead creates a TEST-PASSED or TEST-FAILURE object.

Package

eos

Source

check.lisp (file)

Direct superclasses

test-failure (class)

Direct methods

• actual-condition (method)
• actual-condition (method)

Direct slots

Slot: actual-condition

Initargs

:condition

Readers

actual-condition (generic function)

Writers

(setf actual-condition) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables