The should-test Reference Manual

This is the should-test Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:52:54 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 should-test

Minimal yet feature-rich Common Lisp test framework.

Maintainer

Vsevolod Dyomkin <>

Author

Vsevolod Dyomkin <>

License

MIT

Version

1.0.0

Dependencies
  • rutils (system).
  • local-time (system).
  • osicat (system).
  • cl-ppcre (system).
Source

should-test.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 should-test/should-test.asd

Source

should-test.asd.

Parent Component

should-test (system).

ASDF Systems

should-test.


3.1.2 should-test/should-test.lisp

Source

should-test.asd.

Parent Component

should-test (system).

Packages

should-test.

Public Interface
Internals

should-checked-rez (reader method).


3.1.3 should-test/self-test.lisp

Dependency

should-test.lisp (file).

Source

should-test.asd.

Parent Component

should-test (system).


3.1.4 should-test/xunit.lisp

Dependency

self-test.lisp (file).

Source

should-test.asd.

Parent Component

should-test (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 should-test

Source

should-test.lisp.

Nickname

st

Use List
  • common-lisp.
  • local-time.
  • rtl.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *test-output*

Stream to print test results.

Package

should-test.

Source

should-test.lisp.

Special Variable: *verbose*
Package

should-test.

Source

should-test.lisp.

Special Variable: *xml-output*
Package

should-test.

Source

xunit.lisp.


5.1.2 Macros

Macro: deftest (name () &body body)

Define a NAMEd test which is a function
that treats each form in its BODY as an assertion to be checked and prints some information to the output.
The result of this function is a boolean indicating
if any of the assertions has failed.
In case of failure second value is a list of failure descriptions, returned from assertions,
and the third value is a list of uncaught errors if any.

Package

should-test.

Source

should-test.lisp.

Macro: should (key test &rest expected-and-testee)

Define an individual test from:

- a comparison TEST
- EXPECTED values
- an operation that needs to be tested (TESTEE)

KEY is used to determine, which kind of results processing is needed (implemented by generic function SHOULD-CHECK methods).
The simplest key is BE that just checks for equality.
Another pre-defined key is SIGNAL, which intercepts conditions.

Package

should-test.

Source

should-test.lisp.


5.1.3 Ordinary functions

Function: test (&key package test failed)

Run a scpecific TEST or all tests defined in PACKAGE (defaults to current).

Returns T if all tests pass or 3 values:

- NIL
- a hash-table of failed tests with their failed assertions’ lists
- a hash-table of tests that have signalled uncaught errors with these errors

If FAILED is set reruns only tests failed at last run.

Package

should-test.

Source

should-test.lisp.

Function: test-for-xunit (out &rest args &key id package test)

Like TEST but writes xunit-style XML test report to OUT.

Package

should-test.

Source

xunit.lisp.

Function: undeftest (name)

Remove test from symbol NAME.

Package

should-test.

Source

should-test.lisp.


5.1.4 Generic functions

Generic Function: should-check (key test fn &rest expected)

Specific processing for SHOULD based on KEY.
FN’s output values are matched to EXPECTED values (if they are given). Up to 2 values are returned:

- if the test passed (T or NIL)
- in case of failure - actual result

Package

should-test.

Source

should-test.lisp.

Methods
Method: should-check ((key (eql :print-to)) stream-sym fn &rest expected)
Method: should-check ((key (eql :signal)) test fn &rest expected)
Method: should-check ((key (eql :be)) test fn &rest expected)
Generic Function: should-format (obj)

Format appropriately for test output.

Package

should-test.

Source

should-test.lisp.

Methods
Method: should-format :around (obj)
Method: should-format (obj)
Method: should-format ((obj hash-table))
Method: should-format ((obj list))

5.1.5 Conditions

Condition: should-checked
Package

should-test.

Source

should-test.lisp.

Direct superclasses

condition.

Direct subclasses
Direct methods

should-checked-rez.

Direct slots
Slot: rez
Initargs

:rez

Readers

should-checked-rez.

Writers

This slot is read-only.

Condition: should-erred
Package

should-test.

Source

should-test.lisp.

Direct superclasses

should-checked.

Condition: should-failed
Package

should-test.

Source

should-test.lisp.

Direct superclasses

should-checked.

Condition: should-test-error
Package

should-test.

Source

should-test.lisp.

Direct superclasses

simple-error.

Condition: should-test-redefinition-warning
Package

should-test.

Source

should-test.lisp.

Direct superclasses

style-warning.

Direct slots
Slot: name
Initargs

:name


5.2 Internals


5.2.1 Macros

Macro: xml (tag &rest attrs-&-body)
Package

should-test.

Source

xunit.lisp.


5.2.2 Ordinary functions

Function: xml-escape (value)
Package

should-test.

Source

xunit.lisp.


5.2.3 Generic functions

Generic Reader: should-checked-rez (condition)
Package

should-test.

Methods
Reader Method: should-checked-rez ((condition should-checked))
Source

should-test.lisp.

Target Slot

rez.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   D   F   G   M   S   T   U   X  
Index Entry  Section

D
deftest: Public macros

F
Function, test: Public ordinary functions
Function, test-for-xunit: Public ordinary functions
Function, undeftest: Public ordinary functions
Function, xml-escape: Private ordinary functions

G
Generic Function, should-check: Public generic functions
Generic Function, should-checked-rez: Private generic functions
Generic Function, should-format: Public generic functions

M
Macro, deftest: Public macros
Macro, should: Public macros
Macro, xml: Private macros
Method, should-check: Public generic functions
Method, should-check: Public generic functions
Method, should-check: Public generic functions
Method, should-checked-rez: Private generic functions
Method, should-format: Public generic functions
Method, should-format: Public generic functions
Method, should-format: Public generic functions
Method, should-format: Public generic functions

S
should: Public macros
should-check: Public generic functions
should-check: Public generic functions
should-check: Public generic functions
should-check: Public generic functions
should-checked-rez: Private generic functions
should-checked-rez: Private generic functions
should-format: Public generic functions
should-format: Public generic functions
should-format: Public generic functions
should-format: Public generic functions
should-format: Public generic functions

T
test: Public ordinary functions
test-for-xunit: Public ordinary functions

U
undeftest: Public ordinary functions

X
xml: Private macros
xml-escape: Private ordinary functions