This is the cardiogram Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 03:33:06 2024 GMT+0.
cardiogram/cardiogram.asdcardiogram/all/file-type.lispcardiogram/fixtures/file-type.lispcardiogram/toolkit/file-type.lispcardiogram/conditions/file-type.lispcardiogram/tests/file-type.lispcardiogram/valuations/file-type.lispcardiogram/introspection/file-type.lispcardiogram/annotations/file-type.lispThe main system appears first, followed by any subsystem dependency.
cardiogramcardiogram/allcardiogram/fixturescardiogram/toolkitcardiogram/conditionscardiogram/testscardiogram/valuationscardiogram/introspectioncardiogram/annotationscardiogramSimple test framework
Abraham Aguilar
Abraham Aguilar
MIT
# Cardiogram 🧡
A framework for impromptu testing in Common Lisp.
WARNING: Work in progress.
## Usage
The main objects in cardiogram are tests. To define a test use the
‘deftest‘ macro. It’s syntax is:
“‘
(deftest <name> (<options>*) <docstring>* <form>*)
<options> := | :before <symbol> | <list-of-symbols>
| :after <symbol> | <list-of-symbols>
| :around <symbol> | <list-of-symbols>
| :depends-on <dependency-c-d>
| :time-limit <number>
<dependency-c-d> := ([or and] [<symbol> <dependency-c-d>]+)
“‘
To run a test, call it by name. For example:
“‘common-lisp
(deftest myfunction-test ()
(true (myfunction))
(myfunction-test)
;=> FAILED - TRUE.
“‘
This will run the code inside the test, then save the result. The second time you call ‘(myfunction-test)‘ the
code won’t be run, rather the test result will be printed. To run the test again, call it with
the ‘:run‘ keyword like so:
“‘common-lisp
(redefine-myfunction)
(myfunction-test :run)
;=> PASSED - TRUE
“‘
#### Chaining tests
You can combine tests using the ‘:before‘, ‘:around‘, and ‘:after‘ options. For example:
“‘common-lisp
(deftest myotherfunction-test (:after myfunction-test)
(false (myotherfunction (myfunction)))
(deftest myvariable-test (:around (myfunction-test myotherfunction-test))
(of-type myvariable ’string))
(myfunction-test :run)
;=> Running test myvariable-test...
; Running test myfunction-test...
; Running test myvariable-test...
; Running test myotherfunction-test...
; Running test myvariable-test...
(myotherfunction-test :run)
;=> Running test myvariable-test...
; Running test myotherfunction-test...
; Running test myvariable-test...
(myvariable-test :run)
;=> Running test myvariable-test...
“‘
You can also tell a test to skip any test in it’s combination by specifying it’s name
when you call it:
“‘common-lisp
... FAILED - MYVARIABLE-TEST
(myfunction-test :run :skip ‘(myvariable-test))
;=> Running test myfunction-test...
; Running test myotherfunction-test...
“‘
#### Test dependencies
To define dependencies for a test, use the ‘:depends-on‘ option.
“‘common-lisp
(deftest myotherfunction-test (:after myfunction-test :depends-on (myvariable-test))
...)
(myfunction-test :run)
;=> Running test myvariable-test...
; Skipping myfunction-test. Failed dependencies.
“‘
Additionally you can use the ‘:dependency-of‘ option to add the test being defined to
another’s dependencies.
“‘common-lisp
(deftest myotherfunction-test (:dependency-of myfunction-test)
...)
(myfunction-test)
;=> Running test myotherfunction-test
; Test myotherfunction-test failed
; ... Dependency error... skipping test myfunction-test
“‘
Both ‘:dependency-of‘ and ‘:depends-on‘ accept dependency disjunctions and conjunctions
of the form:
“‘common-lisp
<dependency-expr> := (<operator-keyword> <symbol>* <dependency-expr>*)
<operator-keyword> := :and :or
“‘
Tests are funcallable, so you can programatically call tests with Lisp’s own ‘funcall‘. For example:
“‘common-lisp
(loop for sy being each symbol in *package* doing
(when (tboundp sy)
(funcall (symbol-test sy))))
“‘
Furthermore, tests will return ‘t‘ or ‘nil‘ whenever they pass or fail respectively.
“‘common-lisp
; silly example
(when (myfunction-test)
(asdf:make :mypackage))
“‘
#### Anonymous Tests
Sometimes you need to test something without being sure about how to test it.
The ‘test‘ macro is a ‘lambda‘ form analog that returns an anonymous test[^1]. Tests defined anonymously
can be used in combination with other named tests.
“‘common-lisp
(test (:after myfunction-test)
...)
(funcall *)
;=> Running test TEST872...
;
(myfunction-test)
;=> Running test MYFUNCTION-TEST...
; Running test TEST872...
(deftes myvar-test (:depends-on (test (:after myfunction-test) ...))
...)
“‘
#### Errors
A global variable called ‘*ignore-errors*‘ controls if a test invokes the debugger on error or not.
It’s set to ‘nil‘ by default. When set to ‘t‘, errors will be ignored but sill reported. A test
with an error is a failed test.
“‘common-lisp
(setf *ignore-errors* t)
(deftest a ()
(+ ’a 1))
(a)
;=> Running test A...
; Test A took 0.0s to run.
; Test A FAIL
;
; Value of ’A in (+ ’A 1) is A, not a NUMBER. ’A(+ ’A 1)NUMBER
; NIL
“‘
## Comparisons, valuations and formats.
Cardiogram provides the following valuations to be used inside a test’s forms.
“‘
(true form)
; Tests if form is true
(false form)
; Tests if form is false
(fail form)
; Will always fail form
(pass form)
; Will always pass form
(is form expected)
; To test if form is eql to expected
(isnt form expected)
; To test if form isn’t eql to expected
(is-values form expected)
; To test if the values of form are eql to the values of expected
(isnt-values form expected)
; Tests if the falues of form aren’t eql to de values of expected
(is-print form expected)
; Tests if form prints the same as expected
(eql-types form1 form2)
; Tests if form1 and form2 are of eql types
(of-type form expected)
; Tests if form is of type expected
(expands-1 form expected)
; Tests if form macroexpand-1s to expected
“‘
You can define new valuations by a two step process. First use the ‘define-valuation‘ macro. The body in
‘define-valuation‘ corresponds to the test used when calling a valuation. It should
return true or false.
“‘common-lisp
; (define-valuation valuation-name args &body body)
(define-valuation my-is (form expected)
(my-eql form expected))
“‘
Next you need to define a reporter function for your valuation. To do this, use the ‘define-format‘ macro.
The body in this macro should be either a string or the body of a function taking two arguments.
The first argument is a list of the arguments passed to the valuation. The second is the result of
the valuation. When defining a function. It should return a report string.
“‘common-lisp
; (define-format valuation-name format-name args &body body)
(define-format my-is simple (args result)
(with-output-to-string (s)
(destructuring-bind (form expected) args
(if result (princ form s) (princ "NOPE" s))))
“‘
The format ‘simple‘ is the default format in cardiogram and ‘binary‘ is the fall-back format.
You can define new formats by individually
adding your format to each valuation name. Then to use it do ‘(setf *default-format* ’myformat)‘.
“‘common-lisp
(ql:quickload :alexandria)
(ql:quickload :cl-yaml)
(define-format fail myformat (args result)
(declare (ignore args result))
(yaml:emit-to-string
(alexandria:alist-hash-table ’(("result" . "failed")
("reason" . "Always Fails"))))
“‘
Cardiogram outputs report strings to a stream called ‘*test-output*‘ which defaults to ‘*standard-output*‘.
You can change it to whatever stream you like.
## Fixes
Sometimes you need to run a test that changes an aspect of the environment. To fix the environment again,
cardiogram has a few macros wrapping ‘unwind-protect‘. The main one is ‘with-fixes‘.
“‘common-lisp
var1
;=> 4
var2
;=> 3
(with-fixes (var1 var2)
...
(setf var1 3)
(setf var2 4) ...)
var1
;=> 4
var2
;=> 3
“‘
#### Environments with automatic fixes
Also there are macros that automatically compute fixes for symbols whose ‘symbol-name‘
starts with ‘f!‘. They are ‘f!let‘, ‘f!let*‘, ‘f!block‘ and ‘f!labels‘
“‘common-lisp
*global-var*
;=> 4
(f!let (...)
(setf *global-var* ’symbol)
(setf f!*global-var* "something else"))
*global-var*
;=> 4º
“‘
Notice how preppending the variable name anywhere inside the ‘f!let‘ is sufficient.
You can define your own fixes with the ‘defix‘ macro.
“‘common-lisp
; (defix name args &body body)
; where args must be a list of 1 element
(defix my-symbol-p (s)
(when (my-symbol-p s)
(setf s 5))
“‘
[^1]: Or rather a test bound to a symbol.
0.1.0
cardiogram/all (system).
cardiogram/allAbraham Aguilar
Abraham Aguilar
MIT
cardiogram/fixtures (system).
cardiogram/conditions (system).
cardiogram/tests (system).
cardiogram/valuations (system).
cardiogram/introspection (system).
cardiogram/annotations (system).
cardiogram/fixturesAbraham Aguilar
Abraham Aguilar
MIT
closer-mop (system).
cardiogram/toolkit (system).
cardiogram/toolkitAbraham Aguilar
Abraham Aguilar
MIT
cardiogram/conditionsAbraham Aguilar
Abraham Aguilar
MIT
cardiogram/testsAbraham Aguilar
Abraham Aguilar
MIT
closer-mop (system).
cardiogram/toolkit (system).
cardiogram/conditions (system).
cardiogram/valuationsAbraham Aguilar
Abraham Aguilar
MIT
closer-mop (system).
cardiogram/tests (system).
cardiogram/toolkit (system).
cardiogram/introspectionAbraham Aguilar
Abraham Aguilar
MIT
closer-mop (system).
cardiogram/tests (system).
cardiogram/annotationsAbraham Aguilar
Abraham Aguilar
MIT
cl-annot (system).
cardiogram/toolkit (system).
Files are sorted by type and then listed depth-first from the systems components trees.
cardiogram/cardiogram.asdcardiogram/all/file-type.lispcardiogram/fixtures/file-type.lispcardiogram/toolkit/file-type.lispcardiogram/conditions/file-type.lispcardiogram/tests/file-type.lispcardiogram/valuations/file-type.lispcardiogram/introspection/file-type.lispcardiogram/annotations/file-type.lispcardiogram/fixtures/file-type.lispcardiogram/fixtures (system).
defix (macro).
f!block (macro).
f!labels (macro).
f!let (macro).
f!let* (macro).
fix-autop (reader method).
(setf fix-autop) (writer method).
symbol-fix (function).
(setf symbol-fix) (function).
with-fixes (macro).
*fixes* (special variable).
fix (class).
make-fixes (function).
specified-fixes (function).
cardiogram/toolkit/file-type.lispcardiogram/toolkit (system).
cardiogram/conditions/file-type.lispcardiogram/conditions (system).
*ignore-errors* (special variable).
*ignore-test-errors* (special variable).
combination-test-name (reader method).
(setf combination-test-name) (writer method).
dependency-name (reader method).
(setf dependency-name) (writer method).
test-dependencies-error (condition).
test-failure (condition).
undefined-test (condition).
undefined-test-in-combination (condition).
undefined-test-in-dependency-of (condition).
undefined-test-name (reader method).
(setf undefined-test-name) (writer method).
test-failure-test-name (reader method).
(setf test-failure-test-name) (writer method).
test-failure-test-results (reader method).
(setf test-failure-test-results) (writer method).
cardiogram/tests/file-type.lispcardiogram/tests (system).
*default-format* (special variable).
*test-output* (special variable).
check-dependencies (function).
deftest (macro).
ensure-test (function).
initialize-instance (method).
symbol-test (function).
(setf symbol-test) (function).
tboundp (function).
test (macro).
test (class).
test-after (reader method).
(setf test-after) (writer method).
test-around (reader method).
(setf test-around) (writer method).
test-before (reader method).
(setf test-before) (writer method).
test-body (reader method).
(setf test-body) (writer method).
test-dependencies (reader method).
(setf test-dependencies) (writer method).
test-forms (reader method).
(setf test-forms) (writer method).
test-name (reader method).
(setf test-name) (writer method).
test-options (reader method).
(setf test-options) (writer method).
test-passes-p (function).
test-results (reader method).
(setf test-results) (writer method).
test-status (reader method).
(setf test-status) (writer method).
test-time-limit (reader method).
(setf test-time-limit) (writer method).
compute-test-verdict-using-results (function).
ensure-dependency-expr (function).
ensure-test-status (function).
report-test (generic function).
resolve-dependency-of (function).
resolve-test-combination (function).
test-documentation (reader method).
(setf test-documentation) (writer method).
cardiogram/valuations/file-type.lispcardiogram/valuations (system).
define-valuation (macro).
eql-types (function).
expands-1 (function).
fail (function).
initialize-instance (method).
initialize-instance (method).
is (function).
is-false (function).
is-true (function).
is-values (macro).
isnt (function).
isnt-values (macro).
of-type (function).
pass (function).
prints (macro).
symbol-valuation (function).
(setf symbol-valuation) (function).
valuation-applicable-formats (reader method).
(setf valuation-applicable-formats) (writer method).
valuation-name (reader method).
(setf valuation-name) (writer method).
valuation-test (reader method).
(setf valuation-test) (writer method).
vboundp (function).
add-format-to-valuation (function).
define-format (macro).
delay (macro).
find-format-for-valuation (function).
force (function).
format-class (class).
format-formatter (reader method).
(setf format-formatter) (writer method).
format-name (reader method).
(setf format-name) (writer method).
is-values% (function).
isnt-values% (function).
prints% (function).
time-limit (macro).
time-limit% (function).
valuation (class).
cardiogram/introspection/file-type.lispcardiogram/introspection (system).
show-deftest (function).
cardiogram/annotations/file-type.lispcardiogram/annotations (system).
in (macro).
Packages are listed by definition order.
cardiogram/testscardiogram/introspectioncardiogram/toolkitcardiogram/annotationscardiogram/conditionscardiogram/valuationscardiogram/allcardiogram/fixturescardiogram/testscardiogram/conditions.
cardiogram/toolkit.
closer-mop.
common-lisp.
*default-format* (special variable).
*test-output* (special variable).
check-dependencies (function).
deftest (macro).
ensure-test (function).
symbol-test (function).
(setf symbol-test) (function).
tboundp (function).
test (macro).
test (class).
test (slot).
test-after (generic reader).
(setf test-after) (generic writer).
test-around (generic reader).
(setf test-around) (generic writer).
test-before (generic reader).
(setf test-before) (generic writer).
test-body (generic reader).
(setf test-body) (generic writer).
test-dependencies (generic reader).
(setf test-dependencies) (generic writer).
test-forms (generic reader).
(setf test-forms) (generic writer).
test-name (generic reader).
(setf test-name) (generic writer).
test-options (generic reader).
(setf test-options) (generic writer).
test-passes-p (function).
test-results (generic reader).
(setf test-results) (generic writer).
test-status (generic reader).
(setf test-status) (generic writer).
test-time-limit (generic reader).
(setf test-time-limit) (generic writer).
compute-test-verdict-using-results (function).
ensure-dependency-expr (function).
ensure-test-status (function).
report-test (generic function).
resolve-dependency-of (function).
resolve-test-combination (function).
test-documentation (generic reader).
(setf test-documentation) (generic writer).
cardiogram/introspectioncardiogram/tests.
closer-mop.
common-lisp.
show-deftest (function).
cardiogram/annotationscardiogram/toolkit.
cl-annot.
common-lisp.
in (macro).
cardiogram/conditionscommon-lisp.
*ignore-errors* (special variable).
*ignore-test-errors* (special variable).
combination-test-name (generic reader).
(setf combination-test-name) (generic writer).
dependency-name (generic reader).
(setf dependency-name) (generic writer).
test-dependencies-error (condition).
test-failure (condition).
undefined-test (condition).
undefined-test-in-combination (condition).
undefined-test-in-dependency-of (condition).
undefined-test-name (generic reader).
(setf undefined-test-name) (generic writer).
test-failure-test-name (generic reader).
(setf test-failure-test-name) (generic writer).
test-failure-test-results (generic reader).
(setf test-failure-test-results) (generic writer).
cardiogram/valuationscardiogram/tests.
cardiogram/toolkit.
closer-mop.
common-lisp.
define-valuation (macro).
eql-types (function).
expands-1 (function).
fail (function).
is (function).
is-false (function).
is-true (function).
is-values (macro).
isnt (function).
isnt-values (macro).
of-type (function).
pass (function).
prints (macro).
symbol-valuation (function).
(setf symbol-valuation) (function).
valuation-applicable-formats (generic reader).
(setf valuation-applicable-formats) (generic writer).
valuation-name (generic reader).
(setf valuation-name) (generic writer).
valuation-test (generic reader).
(setf valuation-test) (generic writer).
vboundp (function).
add-format-to-valuation (function).
define-format (macro).
delay (macro).
find-format-for-valuation (function).
force (function).
format-class (class).
format-formatter (generic reader).
(setf format-formatter) (generic writer).
format-name (generic reader).
(setf format-name) (generic writer).
is-values% (function).
isnt-values% (function).
prints% (function).
time-limit (macro).
time-limit% (function).
valuation (class).
cardiogram/fixturescardiofix
cardiogram/toolkit.
closer-mop.
common-lisp.
defix (macro).
f!block (macro).
f!labels (macro).
f!let (macro).
f!let* (macro).
fix-autop (generic reader).
(setf fix-autop) (generic writer).
symbol-fix (function).
(setf symbol-fix) (function).
with-fixes (macro).
*fixes* (special variable).
fix (class).
make-fixes (function).
specified-fixes (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Block that fixes the
Block that fixes the
Block that fixes the
Block that fixes the
Run the forms in BODY and fix the SYMBOLS
Returns (values body declarations docstring)
both body and declarations are returned as lists, docstring as a string
Build string PRINCing args. If at any point in the args
a string with the char ~ is found, this string is treated
as a FORMAT control string taking as many arguments from args
as ~’s are found in the control string
undefined-test-in-combination)) ¶undefined-test-in-combination)) ¶undefined-test-in-dependency-of)) ¶undefined-test-in-dependency-of)) ¶undefined-test)) ¶undefined-test)) ¶name.
format-class) &key) ¶To be signaled when checking dependencies
error.
:name
:combination-test
:dependency-name
funcallable-standard-object.
initialize-instance.
(setf test-after).
test-after.
(setf test-around).
test-around.
(setf test-before).
test-before.
(setf test-body).
test-body.
(setf test-dependencies).
test-dependencies.
(setf test-documentation).
test-documentation.
(setf test-forms).
test-forms.
(setf test-name).
test-name.
(setf test-options).
test-options.
(setf test-results).
test-results.
(setf test-status).
test-status.
(setf test-time-limit).
test-time-limit.
:forms
:body
:options
:name
:before
:after
:around
:dependencies
:results
:time-limit
common-lisp.
:documentation
format-class)) ¶automatically generated reader method
format-class)) ¶automatically generated writer method
format-class)) ¶automatically generated reader method
name.
format-class)) ¶automatically generated writer method
name.
test-failure)) ¶test-failure)) ¶name.
test-failure)) ¶test-failure)) ¶funcallable-standard-object.
:auto
| Jump to: | (
A C D E F G I K L M O P R S T U V W |
|---|
| Jump to: | (
A C D E F G I K L M O P R S T U V W |
|---|
| Jump to: | *
A B C D F N O R S T |
|---|
| Jump to: | *
A B C D F N O R S T |
|---|
| Jump to: | C F P S T U V |
|---|
| Jump to: | C F P S T U V |
|---|