This is the try Reference Manual, version 0.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:49:49 2024 GMT+0.
try/try.asd
try.asdf/try.asdf.asd
try/package.lisp
try/util.lisp
try/gray-stream.lisp
try/early.lisp
try/debug.lisp
try/events.lisp
try/outcome.lisp
try/result.lisp
try/is.lisp
try/checks.lisp
try/floats.lisp
try/trial-event.lisp
try/error.lisp
try/count.lisp
try/trial.lisp
try/test.lisp
try/testable.lisp
try/rerun.lisp
try/print.lisp
try/collect.lisp
try/try.lisp
try/replay.lisp
try/manual.lisp
try/doc.lisp
try.asdf/asdf.lisp
The main system appears first, followed by any subsystem dependency.
try
Try is an extensible test framework with equal support for interactive and non-interactive workflows.
Gábor Melis
(GIT https://github.com/melisgl/try.git)
MIT, see COPYING.
Try stays as close to normal Lisp evaluation
rules as possible. Tests are functions that record the checks they
perform as events. These events provide the means of customization
of what to debug, print, rerun. There is a single fundamental check,
the extensible IS macro. Everything else is built on top.
0.0.1
try.asdf
(system).
alexandria
(system).
cl-ppcre
(system).
closer-mop
(system).
ieee-floats
(system).
mgl-pax
(system).
trivial-gray-streams
(system).
uiop
(system).
package.lisp
(file).
util.lisp
(file).
gray-stream.lisp
(file).
early.lisp
(file).
debug.lisp
(file).
events.lisp
(file).
outcome.lisp
(file).
result.lisp
(file).
is.lisp
(file).
checks.lisp
(file).
floats.lisp
(file).
trial-event.lisp
(file).
error.lisp
(file).
count.lisp
(file).
trial.lisp
(file).
test.lisp
(file).
testable.lisp
(file).
rerun.lisp
(file).
print.lisp
(file).
collect.lisp
(file).
try.lisp
(file).
replay.lisp
(file).
manual.lisp
(file).
doc.lisp
(file).
Files are sorted by type and then listed depth-first from the systems components trees.
try/try.asd
try.asdf/try.asdf.asd
try/package.lisp
try/util.lisp
try/gray-stream.lisp
try/early.lisp
try/debug.lisp
try/events.lisp
try/outcome.lisp
try/result.lisp
try/is.lisp
try/checks.lisp
try/floats.lisp
try/trial-event.lisp
try/error.lisp
try/count.lisp
try/trial.lisp
try/test.lisp
try/testable.lisp
try/rerun.lisp
try/print.lisp
try/collect.lisp
try/try.lisp
try/replay.lisp
try/manual.lisp
try/doc.lisp
try.asdf/asdf.lisp
try/util.lisp
package.lisp
(file).
try
(system).
on-values
(macro).
print-object
(method).
%extract-options
(function).
%unwind-protect
(macro).
%wrap-restart-bind-binding-in-lambda
(function).
%wrap-restart-bind-option-in-lambda
(function).
%wrap-restart-case-binding-in-lambda
(function).
%wrap-restart-case-option-in-lambda
(function).
*dummy*
(special variable).
*start-time*
(special variable).
*testing-timing*
(special variable).
bool=
(function).
compiler-policy
(function).
compiler-policy-quantity
(function).
dummy-with-print-object
(class).
ensure-list
(function).
ensure-rest-arg
(function).
get-elapsed-seconds
(function).
intern-hyphenated
(function).
lambda-list-to-arglist-form
(function).
lambda-list-with-&rest-to-arglist-form
(function).
make-gensym
(function).
on-finish
(macro).
on-nlx
(macro).
on-return
(macro).
present-body
(function).
restart-bind
(macro).
restart-case
(macro).
safe-subtypep
(function).
safe-typep
(function).
shuffle
(function).
shuffle!
(function).
shuffle-vector!
(function).
subseq*
(function).
valid-type-specifier
(type).
valid-type-specifier-p
(function).
with-bindings
(macro).
with-circularity-detection
(macro).
with-debugger-hook
(macro).
with-debugger-hook-form
(macro).
with-gensyms
(macro).
with-retry/catch
(macro).
with-retry/go
(macro).
with-timing
(macro).
without-tail-call
(macro).
try/gray-stream.lisp
util.lisp
(file).
try
(system).
close
(method).
initialize-instance
(method).
stream-element-type
(method).
stream-line-column
(method).
stream-write-char
(method).
column
(reader method).
(setf column)
(writer method).
inner-stream
(reader method).
line
(reader method).
(setf line)
(writer method).
line/column-character-output-stream
(class).
stream-column
(generic function).
stream-line
(generic function).
stream-line-column*
(function).
sync-stream-line-column
(function).
wrapped-stream
(class).
try/early.lisp
gray-stream.lisp
(file).
try
(system).
*record-event*
(special variable).
*trial*
(special variable).
*try-id*
(special variable).
try/debug.lisp
early.lisp
(file).
try
(system).
*dbg*
(special variable).
*internal-error*
(special variable).
dbg
(macro).
nested-error
(reader method).
try-internal-error
(condition).
with-internal-errors
(macro).
try/events.lisp
debug.lisp
(file).
try
(system).
*categories*
(special variable).
*event-print-bindings*
(special variable).
abort*
(condition).
ascii-std-categories
(function).
dismissal
(condition).
event
(condition).
expected
(condition).
expected-failure
(type).
expected-success
(type).
fail
(type).
failure
(condition).
fancy-std-categories
(function).
leaf
(condition).
pass
(type).
print-object
(method).
record-event
(function).
success
(condition).
unexpected
(condition).
unexpected-failure
(type).
unexpected-success
(type).
@try/categories
(special variable).
@try/concrete-events
(special variable).
@try/event-glue
(special variable).
@try/event-restarts
(special variable).
@try/events
(special variable).
@try/middle-layer-of-events
(special variable).
@try/printing-events
(special variable).
category-marker
(function).
combine-superclasses
(function).
define-combi-event
(macro).
event-category
(function).
signal-with-record-event
(function).
write-event
(generic function).
try/outcome.lisp
events.lisp
(file).
try
(system).
abort-check
(function).
force-expected-failure
(function).
force-expected-success
(function).
force-unexpected-failure
(function).
force-unexpected-success
(function).
outcome
(condition).
retry-check
(function).
skip
(condition).
skip-check
(function).
with-expected-outcome
(macro).
with-failure-expected
(macro).
with-skip
(macro).
*expected-outcome*
(special variable).
*skip*
(special variable).
@try/check-restarts
(special variable).
@try/checks
(special variable).
@try/outcome-restarts
(special variable).
@try/outcomes
(special variable).
basic-outcome
(type).
determine-outcome-type
(function).
report-change-outcome-to
(function).
signal-outcome
(function).
try/result.lisp
outcome.lisp
(file).
try
(system).
expected-result-failure
(condition).
expected-result-success
(condition).
result
(condition).
result-abort*
(condition).
result-skip
(condition).
unexpected-result-failure
(condition).
unexpected-result-success
(condition).
%%write-result-msg
(function).
%frob-form-for-printing
(function).
%write-result
(function).
%write-result-captures
(function).
%write-result-ctx
(function).
%write-result-msg
(function).
captures
(reader method).
check
(reader method).
ctx
(reader method).
elapsed-seconds
(reader method).
msg
(reader method).
print-captures
(reader method).
print-form-memoization-data
(reader method).
(setf print-form-memoization-data)
(writer method).
result-failure
(condition).
result-success
(condition).
substitute-tilde-percent
(function).
write-event
(method).
try/is.lisp
result.lisp
(file).
try
(system).
*is-captures*
(special variable).
*is-form*
(special variable).
canonicalize-format-specifier-form
(function).
capture
(macro).
capture-values
(macro).
is
(macro).
make-sub
(function).
sub
(structure).
sub-new-form
(reader).
(setf sub-new-form)
(writer).
sub-subform
(reader).
(setf sub-subform)
(writer).
sub-valuesp
(reader).
(setf sub-valuesp)
(writer).
sub-var
(reader).
(setf sub-var)
(writer).
substitute-is-list-form
(generic function).
%subs-to-bindings
(function).
%subs-to-captures
(function).
@try/automatic-captures
(special variable).
@try/captures
(special variable).
@try/explicit-captures
(special variable).
@try/format-specifier-forms
(special variable).
@try/is
(special variable).
@try/writing-automatic-capture-rules
(special variable).
capture-explicitp
(function).
(setf capture-explicitp)
(function).
capture-subform
(function).
(setf capture-subform)
(function).
capture-value
(function).
(setf capture-value)
(function).
capture-valuesp
(function).
(setf capture-valuesp)
(function).
constantishp
(function).
copy-sub
(function).
define-macrolet
(macro).
macrolet-dref
(class).
make-capture
(function).
same-but-different-implicit-captures-p
(function).
scrub-captures
(function).
signal-is-outcome
(function).
strip-outer-%-and-%%-from-implicit-captures
(function).
sub-p
(function).
substitute-args
(function).
substitute-in-subs
(function).
substitute-is-form
(function).
try/checks.lisp
is.lisp
(file).
try
(system).
*best-matching-condition*
(special variable).
*condition-matched-p*
(special variable).
*in-time-elapsed-seconds*
(special variable).
different-elements
(function).
fails
(macro).
in-time
(macro).
invokes-debugger
(macro).
invokes-debugger-not
(macro).
match-values
(macro).
mismatch%
(function).
same-set-p
(function).
signals
(macro).
signals-not
(macro).
substitute-is-list-form
(method).
with-shuffling
(macro).
%describe-condition-for-matching
(function).
%match-condition
(function).
@try/check-library
(special variable).
@try/check-utilities
(special variable).
@try/checking-conditions
(special variable).
@try/misc-checks
(special variable).
check-fails
(function).
check-invokes-debugger
(function).
check-invokes-debugger-not
(function).
check-signals
(function).
check-signals-not
(function).
condition-match-checker
(macro).
invokes-debugger-default-ctx
(function).
invokes-debugger-default-msg
(function).
invokes-debugger-not-default-msg
(function).
match-values%
(macro).
with-condition-matching
(macro).
try/floats.lisp
checks.lisp
(file).
try
(system).
*max-diff-in-ulp*
(special variable).
*max-diff-in-value*
(special variable).
float-~<
(function).
float-~=
(function).
float-~>
(function).
@try/comparing-floats
(special variable).
double-float-~=
(function).
single-float-~=
(function).
try/trial-event.lisp
floats.lisp
(file).
try
(system).
expected-verdict-failure
(condition).
expected-verdict-success
(condition).
trial
(reader method).
trial-event
(condition).
trial-start
(condition).
unexpected-verdict-failure
(condition).
unexpected-verdict-success
(condition).
verdict
(condition).
verdict-abort*
(condition).
verdict-skip
(condition).
@try/trial-events
(special variable).
elapsed-seconds
(reader method).
verdict-failure
(condition).
verdict-success
(condition).
write-event
(method).
write-event
(method).
try/error.lisp
trial-event.lisp
(file).
try
(system).
*gather-backtrace*
(special variable).
backtrace-of
(reader method).
debugger-invoked-p
(reader method).
error*
(condition).
nested-condition
(reader method).
nlx
(condition).
test-name
(reader method).
unhandled-error
(condition).
*print-backtrace*
(special variable).
@try/errors
(special variable).
basic-error*-outcome
(type).
describe-condition
(function).
extra-message
(reader method).
maybe-backtrace
(function).
signal-error*
(function).
write-event
(method).
write-event
(method).
try/count.lisp
error.lisp
(file).
try
(system).
%make-counter
(function).
@try/count
(special variable).
add-to-counter
(function).
bump-counter
(function).
copy-counter
(function).
counter
(structure).
counter-categories
(reader).
(setf counter-categories)
(writer).
counter-counts
(reader).
(setf counter-counts)
(writer).
counter-p
(function).
make-counter
(function).
reset-counter
(function).
try/trial.lisp
count.lisp
(file).
try
(system).
abort-trial
(function).
children
(reader method).
current-trial
(function).
failedp
(function).
initialize-instance
(method).
n-retries
(reader method).
passedp
(function).
print-object
(method).
retry-trial
(function).
runningp
(function).
skip-trial
(function).
test-name
(reader method).
trial
(class).
trial-start
(reader method).
verdict
(reader method).
%trial-basic-verdict
(function).
@try/trial-restarts
(special variable).
@try/trial-verdicts
(special variable).
@try/trials
(special variable).
abort-restart
(reader method).
(setf abort-restart)
(writer method).
categories
(reader method).
cform
(reader method).
check-trial-running
(function).
clean-up-cancelled-nlx-of-retry-for-end-trial
(function).
clear-trial-restarts
(function).
count-of
(reader method).
counter
(reader method).
depth
(reader method).
elapsed-seconds
(reader method).
end-trial
(function).
has-non-collected-failed-child-p
(reader method).
how-it-ended
(reader method).
how-to-end
(reader method).
(setf how-to-end)
(writer method).
lambda-trial-p
(function).
named-trial-p
(function).
non-collected-counter
(reader method).
parent
(reader method).
retry-restart
(reader method).
(setf retry-restart)
(writer method).
say-how-to-end
(function).
set-up-trial-restarts
(function).
skip-restart
(reader method).
(setf skip-restart)
(writer method).
start-retry-for-trial
(function).
start-trial
(function).
trialp
(function).
try-trial-p
(function).
try-trial-testable
(function).
verdict-for-trial-p
(function).
with-error*-handled
(macro).
with-trial
(macro).
with-trial-restarts
(macro).
try/test.lisp
trial.lisp
(file).
try
(system).
*run-deftest-when*
(special variable).
deftest
(macro).
list-package-tests
(function).
test-bound-p
(function).
warn-on-tests-not-run
(macro).
with-test
(macro).
with-tests-run
(macro).
*call-test*
(special variable).
*call-test-fn*
(special variable).
*tests-run*
(special variable).
*trial-initargs*
(special variable).
@try/tests
(special variable).
call-test
(function).
deftest-registry-var-name
(function).
ensure-deftest-registry
(function).
expand-with-trial-in-deftest-p
(function).
get-deftest-registry
(function).
invoke-test-interactively
(function).
make-trial
(function).
maybe-mark-test-run
(function).
read-argument-list
(function).
register-deftest
(function).
wrap-trial-body-for-return
(macro).
try/testable.lisp
test.lisp
(file).
try
(system).
@try/testables
(special variable).
call-testable
(function).
call-with-wrapper
(function).
list-function-designators
(function).
try/rerun.lisp
testable.lisp
(file).
try
(system).
%make-rerun-trial-event-handler
(function).
@try/rerun
(special variable).
call-lambda-trial
(function).
call-named-trial
(function).
call-trial
(function).
call-try-trial
(function).
child-trials
(function).
trial-call-=
(function).
trial-has-event-of-type-p
(function).
try/print.lisp
rerun.lisp
(file).
try
(system).
*defer-describe*
(special variable).
*print-compactly*
(special variable).
*print-duration*
(special variable).
*print-indentation*
(special variable).
*print-parent*
(special variable).
initialize-instance
(method).
tree-printer
(class).
%ensure-new-line
(function).
%ensure-trial-printed
(function).
%make-indent
(function).
%print-event
(function).
%print-indent-for
(function).
%print-leaf
(function).
%print-verdict
(function).
@try/print
(special variable).
ancestor-trial-names
(function).
ancestors-from-oldest
(function).
copy-print-state
(function).
defer-describe
(reader method).
describe-leaf
(generic function).
describe-to-be-described
(function).
describe-type
(reader method).
event-print-depth
(function).
finish-printing
(generic function).
indentation
(reader method).
make-print-state
(function).
print-compactly
(reader method).
print-duration
(function).
print-duration-p
(reader method).
print-event
(generic function).
print-event-header
(function).
print-parent
(reader method).
print-state
(structure).
print-state-first-line-and-column
(reader).
(setf print-state-first-line-and-column)
(writer).
print-state-n-retries
(reader).
(setf print-state-n-retries)
(writer).
print-state-p
(function).
print-state-trial
(reader).
(setf print-state-trial)
(writer).
print-state-trial-printed-p
(function).
print-type
(reader method).
printer
(class).
printer-depth
(function).
stream-of
(reader method).
to-be-described
(reader method).
(setf to-be-described)
(writer method).
trial-print-states
(reader method).
trial-printed-p
(function).
write-trial-counts
(function).
try/collect.lisp
print.lisp
(file).
try
(system).
%collector
(structure).
%collector-collect-type
(reader).
(setf %collector-collect-type)
(writer).
%collector-count-type
(reader).
(setf %collector-count-type)
(writer).
%collector-p
(function).
%count-and-collect-event
(function).
@try/collect
(special variable).
copy-%collector
(function).
count-and-collect-leaf
(function).
count-and-collect-verdict
(function).
count-collected-leaf
(function).
count-collected-verdict
(function).
count-non-collected-leaf
(function).
count-non-collected-verdict
(function).
count-trial-start
(function).
make-%collector
(function).
try/try.lisp
collect.lisp
(file).
try
(system).
!
(special variable).
!!
(special variable).
!!!
(special variable).
*collect*
(special variable).
*count*
(special variable).
*debug*
(special variable).
*describe*
(special variable).
*n-recent-trials*
(special variable).
*print*
(special variable).
*printer*
(special variable).
*rerun*
(special variable).
*stream*
(special variable).
*try-collect*
(special variable).
*try-count*
(special variable).
*try-debug*
(special variable).
*try-describe*
(special variable).
*try-print*
(special variable).
*try-printer*
(special variable).
*try-rerun*
(special variable).
*try-stream*
(special variable).
recent-trial
(function).
set-try-debug
(function).
try
(function).
%maybe-invoke-debugger
(function).
*invoking-debugger*
(special variable).
*recent-trials*
(special variable).
@try/explicit-try
(special variable).
@try/implicit-try
(special variable).
@try/implicit-try-implementation
(special variable).
add-to-recent-trials
(function).
check-event-type
(function).
check-printer-arg
(function).
read-try-debug
(function).
remembering-most-recent-trials
(macro).
try-default-unspecified-args
(macro).
try-for-emacs
(function).
try/implicit
(function).
with-current-debug
(macro).
with-try-context
(macro).
try/replay.lisp
try.lisp
(file).
try
(system).
replay-events
(function).
%replay-events
(function).
%replay-trial-initargs
(function).
@try/replay
(special variable).
try/manual.lisp
replay.lisp
(file).
try
(system).
install-try-elisp
(function).
@cancelled-nlx
(special variable).
@funcallable-instance
(special variable).
@try-manual
(special variable).
@try/emacs
(special variable).
@try/emacs-setup
(special variable).
@try/glossary
(special variable).
@try/implementation-notes
(special variable).
@try/links
(special variable).
@try/tutorial
(special variable).
try/doc.lisp
manual.lisp
(file).
try
(system).
pax-pages
(function).
pax-sections
(function).
try-transcript
(function).
try-transcript-normalize-output
(function).
try-transcript-normalize-unreadable
(function).
try-transcript-output=
(function).
try-transcript-unreadable=
(function).
try-transcript-upcase-trial
(function).
try.asdf/asdf.lisp
try.asdf
(system).
compile-wrapper
(function).
Packages are listed by definition order.
try
See TRY::@TRY-MANUAL.
common-lisp
.
editor-hints.named-readtables
.
mgl-pax
.
pythonic-string-reader
.
!
(special variable).
!!
(special variable).
!!!
(special variable).
*best-matching-condition*
(special variable).
*categories*
(special variable).
*collect*
(special variable).
*condition-matched-p*
(special variable).
*count*
(special variable).
*debug*
(special variable).
*defer-describe*
(special variable).
*describe*
(special variable).
*event-print-bindings*
(special variable).
*gather-backtrace*
(special variable).
*in-time-elapsed-seconds*
(special variable).
*is-captures*
(special variable).
*is-form*
(special variable).
*max-diff-in-ulp*
(special variable).
*max-diff-in-value*
(special variable).
*n-recent-trials*
(special variable).
*print*
(special variable).
*print-compactly*
(special variable).
*print-duration*
(special variable).
*print-indentation*
(special variable).
*print-parent*
(special variable).
*printer*
(special variable).
*rerun*
(special variable).
*run-deftest-when*
(special variable).
*stream*
(special variable).
*try-collect*
(special variable).
*try-count*
(special variable).
*try-debug*
(special variable).
*try-describe*
(special variable).
*try-print*
(special variable).
*try-printer*
(special variable).
*try-rerun*
(special variable).
*try-stream*
(special variable).
abort*
(condition).
abort-check
(function).
abort-trial
(function).
ascii-std-categories
(function).
backtrace-of
(generic reader).
canonicalize-format-specifier-form
(function).
capture
(macro).
capture-values
(macro).
children
(generic reader).
current-trial
(function).
debugger-invoked-p
(generic reader).
deftest
(macro).
different-elements
(function).
dismissal
(condition).
error*
(condition).
event
(condition).
expected
(condition).
expected-failure
(type).
expected-result-failure
(condition).
expected-result-success
(condition).
expected-success
(type).
expected-verdict-failure
(condition).
expected-verdict-success
(condition).
fail
(type).
failedp
(function).
fails
(macro).
failure
(condition).
fancy-std-categories
(function).
float-~<
(function).
float-~=
(function).
float-~>
(function).
force-expected-failure
(function).
force-expected-success
(function).
force-unexpected-failure
(function).
force-unexpected-success
(function).
in-time
(macro).
install-try-elisp
(function).
invokes-debugger
(macro).
invokes-debugger-not
(macro).
is
(macro).
leaf
(condition).
list-package-tests
(function).
make-sub
(function).
match-values
(macro).
mismatch%
(function).
n-retries
(generic reader).
nested-condition
(generic reader).
nlx
(condition).
on-values
(macro).
outcome
(condition).
pass
(type).
passedp
(function).
recent-trial
(function).
record-event
(function).
replay-events
(function).
result
(condition).
result-abort*
(condition).
result-skip
(condition).
retry-check
(function).
retry-trial
(function).
runningp
(function).
same-set-p
(function).
set-try-debug
(function).
signals
(macro).
signals-not
(macro).
skip
(condition).
skip-check
(function).
skip-trial
(function).
sub
(structure).
sub-new-form
(reader).
(setf sub-new-form)
(writer).
sub-subform
(reader).
(setf sub-subform)
(writer).
sub-valuesp
(reader).
(setf sub-valuesp)
(writer).
sub-var
(reader).
(setf sub-var)
(writer).
substitute-is-list-form
(generic function).
success
(condition).
test-bound-p
(function).
test-name
(generic reader).
tree-printer
(class).
trial
(generic reader).
trial
(class).
trial-event
(condition).
trial-start
(generic reader).
trial-start
(condition).
try
(function).
unexpected
(condition).
unexpected-failure
(type).
unexpected-result-failure
(condition).
unexpected-result-success
(condition).
unexpected-success
(type).
unexpected-verdict-failure
(condition).
unexpected-verdict-success
(condition).
unhandled-error
(condition).
verdict
(generic reader).
verdict
(condition).
verdict-abort*
(condition).
verdict-skip
(condition).
warn-on-tests-not-run
(macro).
with-expected-outcome
(macro).
with-failure-expected
(macro).
with-shuffling
(macro).
with-skip
(macro).
with-test
(macro).
with-tests-run
(macro).
%%write-result-msg
(function).
%collector
(structure).
%collector-collect-type
(reader).
(setf %collector-collect-type)
(writer).
%collector-count-type
(reader).
(setf %collector-count-type)
(writer).
%collector-p
(function).
%count-and-collect-event
(function).
%describe-condition-for-matching
(function).
%ensure-new-line
(function).
%ensure-trial-printed
(function).
%extract-options
(function).
%frob-form-for-printing
(function).
%make-counter
(function).
%make-indent
(function).
%make-rerun-trial-event-handler
(function).
%match-condition
(function).
%maybe-invoke-debugger
(function).
%print-event
(function).
%print-indent-for
(function).
%print-leaf
(function).
%print-verdict
(function).
%replay-events
(function).
%replay-trial-initargs
(function).
%subs-to-bindings
(function).
%subs-to-captures
(function).
%trial-basic-verdict
(function).
%unwind-protect
(macro).
%wrap-restart-bind-binding-in-lambda
(function).
%wrap-restart-bind-option-in-lambda
(function).
%wrap-restart-case-binding-in-lambda
(function).
%wrap-restart-case-option-in-lambda
(function).
%write-result
(function).
%write-result-captures
(function).
%write-result-ctx
(function).
%write-result-msg
(function).
*call-test*
(special variable).
*call-test-fn*
(special variable).
*dbg*
(special variable).
*dummy*
(special variable).
*expected-outcome*
(special variable).
*internal-error*
(special variable).
*invoking-debugger*
(special variable).
*print-backtrace*
(special variable).
*recent-trials*
(special variable).
*record-event*
(special variable).
*skip*
(special variable).
*start-time*
(special variable).
*testing-timing*
(special variable).
*tests-run*
(special variable).
*trial*
(special variable).
*trial-initargs*
(special variable).
*try-id*
(special variable).
@cancelled-nlx
(special variable).
@funcallable-instance
(special variable).
@try-manual
(special variable).
@try/automatic-captures
(special variable).
@try/captures
(special variable).
@try/categories
(special variable).
@try/check-library
(special variable).
@try/check-restarts
(special variable).
@try/check-utilities
(special variable).
@try/checking-conditions
(special variable).
@try/checks
(special variable).
@try/collect
(special variable).
@try/comparing-floats
(special variable).
@try/concrete-events
(special variable).
@try/count
(special variable).
@try/emacs
(special variable).
@try/emacs-setup
(special variable).
@try/errors
(special variable).
@try/event-glue
(special variable).
@try/event-restarts
(special variable).
@try/events
(special variable).
@try/explicit-captures
(special variable).
@try/explicit-try
(special variable).
@try/format-specifier-forms
(special variable).
@try/glossary
(special variable).
@try/implementation-notes
(special variable).
@try/implicit-try
(special variable).
@try/implicit-try-implementation
(special variable).
@try/is
(special variable).
@try/links
(special variable).
@try/middle-layer-of-events
(special variable).
@try/misc-checks
(special variable).
@try/outcome-restarts
(special variable).
@try/outcomes
(special variable).
@try/print
(special variable).
@try/printing-events
(special variable).
@try/replay
(special variable).
@try/rerun
(special variable).
@try/testables
(special variable).
@try/tests
(special variable).
@try/trial-events
(special variable).
@try/trial-restarts
(special variable).
@try/trial-verdicts
(special variable).
@try/trials
(special variable).
@try/tutorial
(special variable).
@try/writing-automatic-capture-rules
(special variable).
abort-restart
(generic reader).
(setf abort-restart)
(generic writer).
add-to-counter
(function).
add-to-recent-trials
(function).
ancestor-trial-names
(function).
ancestors-from-oldest
(function).
basic-error*-outcome
(type).
basic-outcome
(type).
bool=
(function).
bump-counter
(function).
call-lambda-trial
(function).
call-named-trial
(function).
call-test
(function).
call-testable
(function).
call-trial
(function).
call-try-trial
(function).
call-with-wrapper
(function).
capture-explicitp
(function).
(setf capture-explicitp)
(function).
capture-subform
(function).
(setf capture-subform)
(function).
capture-value
(function).
(setf capture-value)
(function).
capture-valuesp
(function).
(setf capture-valuesp)
(function).
captures
(generic reader).
categories
(generic reader).
category-marker
(function).
cform
(generic reader).
check
(generic reader).
check-event-type
(function).
check-fails
(function).
check-invokes-debugger
(function).
check-invokes-debugger-not
(function).
check-printer-arg
(function).
check-signals
(function).
check-signals-not
(function).
check-trial-running
(function).
child-trials
(function).
clean-up-cancelled-nlx-of-retry-for-end-trial
(function).
clear-trial-restarts
(function).
column
(generic reader).
(setf column)
(generic writer).
combine-superclasses
(function).
compiler-policy
(function).
compiler-policy-quantity
(function).
condition-match-checker
(macro).
constantishp
(function).
copy-%collector
(function).
copy-capture
(function).
copy-counter
(function).
copy-print-state
(function).
copy-sub
(function).
count-and-collect-leaf
(function).
count-and-collect-verdict
(function).
count-collected-leaf
(function).
count-collected-verdict
(function).
count-non-collected-leaf
(function).
count-non-collected-verdict
(function).
count-of
(generic reader).
count-trial-start
(function).
counter
(generic reader).
counter
(structure).
counter-categories
(reader).
(setf counter-categories)
(writer).
counter-counts
(reader).
(setf counter-counts)
(writer).
counter-p
(function).
ctx
(generic reader).
dbg
(macro).
defer-describe
(generic reader).
define-combi-event
(macro).
define-macrolet
(macro).
deftest-registry-var-name
(function).
depth
(generic reader).
describe-condition
(function).
describe-leaf
(generic function).
describe-to-be-described
(function).
describe-type
(generic reader).
determine-outcome-type
(function).
double-float-~=
(function).
dummy-with-print-object
(class).
elapsed-seconds
(generic reader).
end-trial
(function).
ensure-deftest-registry
(function).
ensure-list
(function).
ensure-rest-arg
(function).
event-category
(function).
event-print-depth
(function).
expand-with-trial-in-deftest-p
(function).
extra-message
(generic reader).
finish-printing
(generic function).
get-deftest-registry
(function).
get-elapsed-seconds
(function).
has-non-collected-failed-child-p
(generic reader).
how-it-ended
(generic reader).
how-to-end
(generic reader).
(setf how-to-end)
(generic writer).
indentation
(generic reader).
inner-stream
(generic reader).
intern-hyphenated
(function).
invoke-test-interactively
(function).
invokes-debugger-default-ctx
(function).
invokes-debugger-default-msg
(function).
invokes-debugger-not-default-msg
(function).
lambda-list-to-arglist-form
(function).
lambda-list-with-&rest-to-arglist-form
(function).
lambda-trial-p
(function).
line
(generic reader).
(setf line)
(generic writer).
line/column-character-output-stream
(class).
list-function-designators
(function).
macrolet-dref
(class).
make-%collector
(function).
make-capture
(function).
make-counter
(function).
make-gensym
(function).
make-print-state
(function).
make-trial
(function).
match-values%
(macro).
maybe-backtrace
(function).
maybe-mark-test-run
(function).
msg
(generic reader).
named-trial-p
(function).
nested-error
(generic reader).
non-collected-counter
(generic reader).
on-finish
(macro).
on-nlx
(macro).
on-return
(macro).
parent
(generic reader).
pax-pages
(function).
pax-sections
(function).
present-body
(function).
print-captures
(generic reader).
print-compactly
(generic reader).
print-duration
(function).
print-duration-p
(generic reader).
print-event
(generic function).
print-event-header
(function).
print-form-memoization-data
(generic reader).
(setf print-form-memoization-data)
(generic writer).
print-parent
(generic reader).
print-state
(structure).
print-state-first-line-and-column
(reader).
(setf print-state-first-line-and-column)
(writer).
print-state-n-retries
(reader).
(setf print-state-n-retries)
(writer).
print-state-p
(function).
print-state-trial
(reader).
(setf print-state-trial)
(writer).
print-state-trial-printed-p
(function).
print-type
(generic reader).
printer
(class).
printer-depth
(function).
read-argument-list
(function).
read-try-debug
(function).
register-deftest
(function).
remembering-most-recent-trials
(macro).
report-change-outcome-to
(function).
reset-counter
(function).
restart-bind
(macro).
restart-case
(macro).
result-failure
(condition).
result-success
(condition).
retry-restart
(generic reader).
(setf retry-restart)
(generic writer).
safe-subtypep
(function).
safe-typep
(function).
same-but-different-implicit-captures-p
(function).
say-how-to-end
(function).
scrub-captures
(function).
set-up-trial-restarts
(function).
shuffle
(function).
shuffle!
(function).
shuffle-vector!
(function).
signal-error*
(function).
signal-is-outcome
(function).
signal-outcome
(function).
signal-with-record-event
(function).
single-float-~=
(function).
skip-restart
(generic reader).
(setf skip-restart)
(generic writer).
start-retry-for-trial
(function).
start-trial
(function).
stream-column
(generic function).
stream-line
(generic function).
stream-line-column*
(function).
stream-of
(generic reader).
strip-outer-%-and-%%-from-implicit-captures
(function).
sub-p
(function).
subseq*
(function).
substitute-args
(function).
substitute-in-subs
(function).
substitute-is-form
(function).
substitute-tilde-percent
(function).
sync-stream-line-column
(function).
to-be-described
(generic reader).
(setf to-be-described)
(generic writer).
trial-call-=
(function).
trial-has-event-of-type-p
(function).
trial-print-states
(generic reader).
trial-printed-p
(function).
trialp
(function).
try-default-unspecified-args
(macro).
try-for-emacs
(function).
try-internal-error
(condition).
try-transcript
(function).
try-transcript-normalize-output
(function).
try-transcript-normalize-unreadable
(function).
try-transcript-output=
(function).
try-transcript-unreadable=
(function).
try-transcript-upcase-trial
(function).
try-trial-p
(function).
try-trial-testable
(function).
try/implicit
(function).
valid-type-specifier
(type).
valid-type-specifier-p
(function).
verdict-failure
(condition).
verdict-for-trial-p
(function).
verdict-success
(condition).
with-bindings
(macro).
with-circularity-detection
(macro).
with-condition-matching
(macro).
with-current-debug
(macro).
with-debugger-hook
(macro).
with-debugger-hook-form
(macro).
with-error*-handled
(macro).
with-gensyms
(macro).
with-internal-errors
(macro).
with-retry/catch
(macro).
with-retry/go
(macro).
with-timing
(macro).
with-trial
(macro).
with-trial-restarts
(macro).
with-try-context
(macro).
without-tail-call
(macro).
wrap-trial-body-for-return
(macro).
wrapped-stream
(class).
write-event
(generic function).
write-trial-counts
(function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
The most recent trial. Equivalent to ‘(RECENT-TRIAL 0)‘.
Bound when a check described in @TRY/CHECKING-CONDITIONS
signals its OUTCOME. If *CONDITION-MATCHED-P*, then it is the
most recent condition that matched both CONDITION-TYPE and PRED.
Else, it is the most recent condition that matched
CONDITION-TYPE or NIL if no such conditions were detected.
try
.
A list of of elements like ‘(TYPE &KEY MARKER)‘.
When @TRY/PRINT, @TRY/CONCRETE-EVENTS are printed with the marker of
the first matching type. When @TRY/COUNT, the counts associated with
all matching types are incremented.
try
.
To save memory, only the UNEXPECTED are collected by default. See @TRY/COLLECT.
When a check described in @TRY/CHECKING-CONDITIONS signals its OUTCOME, this variable is bound to a boolean value to indicate whether a condition that matched CONDITION-TYPE and PRED was found.
try
.
Although the default value of *CATEGORIES* lumps RESULTs and VERDICTs together, with the default of LEAF, VERDICTs are not counted. See @TRY/COUNT.
The default value makes TRY invoke the debugger on UNHANDLED-ERROR, RESULT-ABORT*, UNEXPECTED-RESULT-FAILURE, and UNEXPECTED-RESULT-SUCCESS. NLX is excluded because it is caught as the test function is being exited, but by that time the dynamic environment of the actual cause is likely gone. VERDICT is excluded because it is a consequence of its child outcomes.
When an EVENT is to be ‘*DESCRIBE*‘d and its type matches
*DEFER-DESCRIBE*, then instead of printing the often longish context
information in the tree of events, it is deferred until after TRY
has finished. The following example only prints LEAF events (due to
*PRINT* and *PRINT-PARENT*) and in compact form (see
*PRINT-COMPACTLY*), deferring description of events matching
*DESCRIBE* until the end.
“‘cl-transcript (:dynenv try-transcript)
(let ((*print* ’leaf)
(*print-parent* nil)
(*print-compactly* t)
(*defer-describe* t)
(*debug* nil))
(with-test (outer)
(loop repeat 10 do (is t))
(with-test (inner)
(is (= (1+ 5) 7)))))
.. â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…âŠ
..
.. ;; UNEXPECTED-RESULT-FAILURE (⊠) in OUTER INNER:
.. (IS (= #1=(1+ 5) 7))
.. where
.. #1# = 6
..
==> #<TRIAL (WITH-TEST (OUTER)) UNEXPECTED-FAILURE 0.000s ⊠1 ⋅10>
“‘
try
.
By default, the context (e.g. @TRY/CAPTURES, and the CTX argument of is and other checks) of UNEXPECTED events is described. See @TRY/PRINT.
EVENTs are conditions signalled in code that may change printer
variables such as *PRINT-CIRCLE*, *PRINT-LENGTH*, etc. To control
how events are printed, the list of variable bindings in
*EVENT-PRINT-BINDINGS* is established whenever an EVENT is printed
as if with:
“‘
(progv (mapcar #’first *event-print-bindings*)
(mapcar #’second *event-print-bindings*)
...)
“‘
The default value ensures that shared structure is recognized (see @TRY/CAPTURES). If the ‘#N#‘ syntax feels cumbersome, then change this variable.
try
.
Capturing the backtrace can be expensive. *GATHER-BACKTRACE* controls whether UNHANDLED-ERRORs shall have their BACKTRACE-OF populated.
try
.
Bound to the number of seconds passed during the evaluation of BODY when IN-TIME signals its OUTCOME.
try
.
Captures made during an IS evaluation are made available for CTX via *IS-CAPTURES*.
IS binds this to its FORM argument for CTX and MSG.
The default value of the MAX-DIFF-IN-ULP argument of FLOAT-~=.
try
.
The default value of the MAX-DIFF-IN-VALUE argument of FLOAT-~=.
try
.
With the default of LEAF combined with the default *PRINT-PARENT* T, only TRIALs with checks or ERROR* in them are printed. If UNEXPECTED, only the interesting things are printed. See @TRY/PRINT.
EVENTs whose type matches *PRINT-COMPACTLY* are printed less
verbosely. LEAF events are printed only with their marker, and
VERDICTs of trials without printed child trials are printed with ‘=>
<MARKER>‘ (see *CATEGORIES*).
“‘cl-transcript (:dynenv try-transcript)
(let ((*print-compactly* t)
(*debug* nil)
(*describe* nil))
(with-test (outer)
(loop repeat 10 do (is t))
(with-test (inner)
(is t)
(is nil)
(error "xxx"))
(loop repeat 10 do (is t))))
.. OUTER â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…
.. INNER ⋅⊠⊟ => ⊟
.. â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…â‹…
.. ⊠OUTER ⊟1 ⊠1 ⋅21
..
==> #<TRIAL (WITH-TEST (OUTER)) UNEXPECTED-FAILURE 0.000s ⊟1 ⊠1 ⋅21>
“‘
*PRINT-COMPACTLY* has no effect on events being ‘DESCRIBE‘d.
try
.
If true, the number of seconds spent during execution is printed.
“‘cl-transcript (:check-consistency nil)
(let ((*print-duration* t)
(*debug* nil)
(*describe* nil))
(with-test (timed)
(is (progn (sleep 0.3) t))
(is (progn (sleep 0.2) t))
(error "xxx")))
.. TIMED
.. 0.300 â‹… (IS (PROGN (SLEEP 0.3) T))
.. 0.200 â‹… (IS (PROGN (SLEEP 0.2) T))
.. ⊟ ""xxx (SIMPLE-ERROR)
.. 0.504 ⊟ TIMED ⊟1 ⋅2
..
==> #<TRIAL (WITH-TEST (TIMED)) ABORT* 0.504s ⊟1 ⋅2>
“‘
Timing is available for all OUTCOMEs (i.e. for @TRY/CHECKS and
TRIALs). Checks generally measure the time spent during evaluation
the form they are wrapping. Trials measure the time between
TRIAL-START and the VERDICT.
Timing information is not available for TRIAL-START and ERROR*
events.
try
.
The number of spaces each printed TRIAL increases the indentation of its children.
try
.
When an EVENT is signalled and its parent TRIAL’s type matches
*PRINT-PARENT*, the trial is printed as if its TRIAL-START matched
the PRINT argument of TRY.
“‘cl-transcript (:dynenv try-transcript)
(let ((*print* ’leaf)
(*print-parent* t))
(with-test (t0)
(is t)
(is t)))
.. T0
.. â‹… (IS T)
.. â‹… (IS T)
.. â‹… T0 â‹…2
..
==> #<TRIAL (WITH-TEST (T0)) EXPECTED-SUCCESS 0.000s â‹…2>
“‘
“‘cl-transcript (:dynenv try-transcript)
(let ((*print* ’leaf)
(*print-parent* nil))
(with-test (t0)
(is t)
(is t)))
.. â‹… (IS T)
.. â‹… (IS T)
..
==> #<TRIAL (WITH-TEST (T0)) EXPECTED-SUCCESS 0.000s â‹…2>
“‘
*PRINT-PARENT* NIL combined with printing VERDICTs results in a flat
output:
“‘cl-transcript (:dynenv try-transcript)
(let ((*print* ’(or leaf verdict))
(*print-parent* nil))
(with-test (outer)
(with-test (inner)
(is t :msg "inner-t"))
(is t :msg "outer-t")))
.. â‹… inner-t
.. â‹… INNER â‹…1
.. â‹… outer-t
.. â‹… OUTER â‹…2
..
==> #<TRIAL (WITH-TEST (OUTER)) EXPECTED-SUCCESS 0.000s â‹…2>
“‘
try
.
The default matches that of *COLLECT*. See @TRY/RERUN.
This may be any of :COMPILE-TOPLEVEL, :LOAD-TOPLEVEL, :EXECUTE, or
a list thereof. The value of *RUN-DEFTEST-WHEN* determines in what
EVAL-WHEN situation to call the test function immediately after it
has been defined with DEFTEST.
For interactive development, it may be convenient to set it to
:EXECUTE and have the test run when the DEFTEST is evaluated (maybe
with Slime ‘C-M-x‘, ‘slime-eval-defun‘). Or set it to
:COMPILE-TOPLEVEL, and have it rerun on Slime ‘C-c C-c‘,
‘slime-compile-defun‘.
If the test has required arguments, an argument list is prompted for and read from *QUERY-IO*.
The default value for TRY’s :COLLECT argument. If :UNSPECIFIED, then the value of *COLLECT* is used instead.
The default value for TRY’s :COUNT argument. If :UNSPECIFIED, then the value of *COUNT* is used instead.
The default value for TRY’s :DEBUG argument. If :UNSPECIFIED, then the value of *DEBUG* is used instead.
The default value for TRY’s :DESCRIBE argument. If :UNSPECIFIED, then the value of *DESCRIBE* is used instead.
The default value for TRY’s :PRINT argument. If :UNSPECIFIED, then the value of *PRINT* is used instead.
The default value for TRY’s :PRINTER argument. If :UNSPECIFIED, then the value of *PRINTER* is used instead.
The default value for TRY’s :RERUN argument. If :UNSPECIFIED, then the value of *RERUN* is used instead.
The default value for TRY’s :STREAM argument. If :UNSPECIFIED, then the value of *STREAM* is used instead.
Evaluate FORM, record its primary return value if within the dynamic extent of an IS evaluation, and finally return that value. If CAPTURE is used within the lexical scope of IS, then CAPTURE itself will show up in the form that the default MSG prints. Thus it is recommended to use the equivalent MACROLET ‘%‘ in the lexical scope as ‘%‘ is removed before printing.
Like CAPTURE-VALUES, but record and return all values returned by FORM. It is recommended to use the equivalent MACROLET ‘%%‘ in the lexical scope as ‘%%‘ is removed before printing.
DEFTEST is a wrapper around DEFUN to define global test functions.
See DEFUN for a description of NAME, LAMBDA-LIST, and BODY. The
behaviour common with WITH-TEST is described in @TRY/TESTS.
“‘cl-transcript (:dynenv try-transcript)
(deftest my-test ()
(write-string "hey"))
=> MY-TEST
(test-bound-p ’my-test)
=> T
(my-test)
.. hey
==> #<TRIAL (MY-TEST) EXPECTED-SUCCESS 0.000s>
“‘
Although the common case is for tests to have no arguments, DEFTEST
supports general function lambda lists. Within a global test,
- NAME is bound to the TRIAL object
- the first return value is the trial
- values are not returned implicitly
- values returned with an explicit RETURN-FROM are returned as
values after the trial
“‘cl-transcript (:dynenv try-transcript)
(deftest my-test ()
(prin1 my-test)
(return-from my-test (values 2 3)))
(my-test)
.. #<TRIAL (MY-TEST) RUNNING>
==> #<TRIAL (MY-TEST) EXPECTED-SUCCESS 0.000s>
=> 2
=> 3
“‘
Check that BODY performs a [non-local exit][clhs] but do not
cancel it (see @CANCELLED-NLX). See @TRY/CHECK-LIBRARY for the
descriptions of the other arguments.
In the following example, FAILS signals a SUCCESS.
“‘cl-transcript (:dynenv try-transcript)
(catch ’foo
(fails ()
(throw ’foo 7)))
=> 7
“‘
Next, FAILS signals an UNEXPECTED-FAILURE because BODY returns
normally.
“‘cl-transcript (:dynenv try-transcript)
(fails ()
(print ’hey))
..
.. HEY
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. (PRINT ’HEY) does not return normally.
“‘
Note that there is no ‘FAILS-NOT‘ as WITH-TEST fills that role.
try
.
Check that BODY finishes in SECONDS. See @TRY/CHECK-LIBRARY for
the descriptions of the other arguments.
“‘
(in-time (1)
(sleep 2))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. (SLEEP 2) finishes within 1s.
.. Took 2.000s.
“‘
RETRY-CHECK restarts timing.
try
.
Check that BODY enters the debugger with a CONDITION of
CONDITION-TYPE (not evaluated) that matches PRED. To detect matching
conditions, INVOKES-DEBUGGER sets up a *DEBUGGER-HOOK*. Thus, if
*DEBUGGER-HOOK* is changed by BODY, it may not detect the condition.
The arguments are described in @TRY/CHECKING-CONDITIONS.
Note that in a trial (see CURRENT-TRIAL), all ERRORs are handled,
and a *DEBUGGER-HOOK* is set up (see UNHANDLED-ERROR). Thus,
invoking debugger would normally cause the trial to abort.
“‘cl-transcript (:dynenv try-transcript)
(invokes-debugger (error :pred "xxx")
(handler-bind ((error #’invoke-debugger))
(error "xxx")))
=> NIL
“‘
try
.
Check that BODY does not enter the debugger with a CONDITION of CONDITION-TYPE (not evaluated) that matches PRED. To detect matching conditions, INVOKES-DEBUGGER-NOT sets up a *DEBUGGER-HOOK*. Thus, if *DEBUGGER-HOOK* is changed by BODY, it may not detect the condition. The arguments are described in @TRY/CHECKING-CONDITIONS.
try
.
Evaluate FORM and signal a RESULT SUCCESS if its first return
value is not NIL, else signal a RESULT FAILURE (see @TRY/OUTCOMES).
IS returns normally if
- the RECORD-EVENT restart is invoked (available when running in a
trial), or
- the CONTINUE restart is invoked (available when not running in a
trial), or
- the signalled RESULT condition is not handled (possible only when
not running in a trial, and the result is a PASS).
The return value of IS is T if the last condition signalled is a
SUCCESS, and NIL otherwise.
MSG and CTX are @TRY/FORMAT-SPECIFIER-FORMS. MSG prints a
description of the check being made, which is by default the whole
IS form. Due to how conditions are printed, MSG says what the
desired outcome is, and CTX provides information about the
evaluation.
“‘cl-transcript (:check-consistency #+sbcl t #-sbcl nil)
(is (equal (prin1-to-string ’hello) "hello")
:msg "Symbols are replacements for strings."
:ctx ("*PACKAGE* is ~S and *PRINT-CASE* is ~S~%"
*package* *print-case*))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. Symbols are replacements for strings.
.. where
.. (PRIN1-TO-STRING ’HELLO) = "HELLO"
.. *PACKAGE* is #<PACKAGE "TRY"> and *PRINT-CASE* is :UPCASE
..
“‘
If CAPTURE is true, the value(s) of some subforms of FORM may be
automatically recorded in the condition and also made available for
CTX via *IS-CAPTURES*. See @TRY/CAPTURES for more.
If PRINT-CAPTURES is true, the captures made are printed when the
RESULT condition is displayed in the debugger or ‘*DESCRIBE*‘d (see
@TRY/PRINT). This is the ‘where (PRIN1-TO-STRING ’HELLO) ="HELLO"‘
part above. If PRINT-CAPTURES is NIL, the captures are still
available in *IS-CAPTURES* for writing custom CTX messages.
If RETRY is true, then the RETRY-CHECK restart evaluates FORM again and signals a new RESULT. If RETRY is NIL, then the RETRY-CHECK restart returns :RETRY, which allows complex checks such as SIGNALS to implement their own retry mechanism.
MATCH-VALUES returns true iff all return values of FORM satisfy
the predicates given by BODY, which are described in ON-VALUES. The
:TRUNCATE option of ON-VALUES is supported, but :ON-LENGTH-MISMATCH
always returns NIL.
“‘cl-transcript (:dynenv try-transcript)
;; no values
(is (match-values (values)))
;; single value success
(is (match-values 1
(= * 1)))
;; success with different types
(is (match-values (values 1 "sdf")
(= * 1)
(string= * "sdf")))
;; too few values
(is (not (match-values 1
(= * 1)
(string= * "sdf"))))
;; too many values
(is (not (match-values (values 1 "sdf" 3)
(= * 1)
(string= * "sdf"))))
;; too many values, but truncated
(is (match-values (values 1 "sdf" 3)
(:truncate t)
(= * 1)
(string= * "sdf")))
“‘
try
.
ON-VALUES evaluates FORM and transforms its return values one by
one based on forms in BODY. The Nth value is replaced by the return
value of the Nth form of BODY evaluated with [‘*‘][dislocated] bound
to the Nth value. If the number of values exceeds the number of
transformation forms in BODY then the excess values are returned as
is.
“‘cl-transcript
(on-values (values 1 "abc" 7)
(1+ *)
(length *))
=> 2
=> 3
=> 7
“‘
If the number of values is less than the number of transformation
forms, then in later transformation forms [‘*‘][dislocated] is bound
to NIL.
“‘cl-transcript
(on-values (values)
*
*)
=> NIL
=> NIL
“‘
The first forms in BODY may be options. Options must precede
transformation forms. With :TRUNCATE T, the excess values are
discarded.
“‘cl-transcript
(on-values (values 1 "abc" 7)
(:truncate t)
(1+ *)
(length *))
=> 2
=> 3
“‘
The :ON-LENGTH-MISMATCH option may be NIL or a function of a single argument. If the number of values and the number of transformation forms are different, then this function is called to transform the list of values. :TRUNCATE is handled before :ON-LENGTH-MISMATCH.
“‘cl-transcript
(on-values 1
(:on-length-mismatch (lambda (values)
(if (= (length values) 1)
(append values ’("abc"))
values)))
(1+ *)
*)
=> 2
=> "abc"
“‘
If the same option is specified multiple times, the first one is in
effect.
Check that BODY signals a CONDITION of CONDITION-TYPE (not evaluated) that matches PRED. To detect matching conditions, SIGNALS sets up a HANDLER-BIND. Thus it can only see what BODY does not handle. The arguments are described in @TRY/CHECKING-CONDITIONS.
“‘cl-transcript (:dynenv try-transcript)
(signals (error)
(error "xxx"))
=> NIL
“‘
The following example shows a failure where CONDITION-TYPE matches
but PRED does not.
“‘cl-transcript (:dynenv try-transcript)
(signals (error :pred "non-matching")
(error "xxx"))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. (ERROR "xxx") signals a condition of type ERROR that matches
.. "non-matching".
.. The predicate did not match "xxx".
“‘
try
.
Check that BODY does not signal a CONDITION of CONDITION-TYPE (not evaluated) that matches PRED. To detect matching conditions, SIGNALS-NOT sets up a HANDLER-BIND. Thus, it can only see what BODY does not handle. The arguments are described in @TRY/CHECKING-CONDITIONS.
try
.
A convenience utility to that records the global tests run by BODY
with WITH-TESTS-RUN and, when BODY finishes, signals a warning for
each global tests in PACKAGE not run.
This is how Try runs its own tests:
“‘
(defun test ()
;; Bind *PACKAGE* so that names of tests printed have package names,
;; and M-. works on them in Slime.
(let ((*package* (find-package :common-lisp)))
(warn-on-tests-not-run ((find-package :try))
(print (try ’test-all
:print ’unexpected
:describe ’unexpected)))))
“‘
When an OUTCOME is to be signalled, EXPECTED-TYPE determines
whether it’s going to be EXPECTED. The concrete OUTCOME classes are
‘{EXPECTED,UNEXPECTED}-{RESULT,VERDICT}-{SUCCESS,FAILURE}‘ (see
@TRY/EVENTS), of which RESULT or VERDICT and SUCCESS or FAILURE are
already known. If a RESULT FAILURE is to be signalled, then the
moral equivalent of ‘(SUBTYPEP ’(AND RESULT FAILURE) EXPECTED-TYPE)‘
is evaluated and depending on whether it’s true,
EXPECTED-RESULT-FAILURE or UNEXPECTED-RESULT-FAILURE is signalled.
By default, SUCCESS is expected. The following example shows how to
expect both SUCCESS and FAILURE for RESULTs, while requiring
VERDICTs to succeed:
“‘cl-transcript (:dynenv try-transcript)
(let ((*debug* nil))
(with-expected-outcome (’(or result (and verdict success)))
(with-test (t1)
(is nil))))
.. T1
.. Ă— (IS NIL)
.. â‹… T1 Ă—1
..
==> #<TRIAL (WITH-TEST (T1)) EXPECTED-SUCCESS 0.000s Ă—1>
“‘
This is equivalent to ‘(WITH-FAILURE-EXPECTED () ...)‘. To make
result failures expected but result successes unexpected:
“‘cl-transcript (:dynenv try-transcript)
(let ((*debug* nil))
(with-expected-outcome (’(or (and result failure) (and verdict success)))
(with-test (t1)
(is t)
(is nil))))
.. T1
.. ⊡ (IS T)
.. Ă— (IS NIL)
.. ⋅ T1 ⊡1 ×1
..
==> #<TRIAL (WITH-TEST (T1)) EXPECTED-SUCCESS 0.000s ⊡1 ×1>
“‘
This is equivalent to ‘(WITH-FAILURE-EXPECTED (’FAILURE) ...)‘. The
final example leaves result failures unexpected but makes both
verdict successes and failures expected:
“‘cl-transcript (:dynenv try-transcript)
(let ((*debug* nil))
(with-expected-outcome (’(or (and result success) verdict))
(with-test (t1)
(is nil))))
.. T1
.. ⊠(IS NIL)
.. × T1 ⊠1
..
==> #<TRIAL (WITH-TEST (T1)) EXPECTED-FAILURE 0.004s ⊠1>
“‘
try
.
A convenience macro on top of WITH-EXPECTED-OUTCOME, WITH-FAILURE-EXPECTED expects VERDICTs to have VERDICT-EXPECTED-TYPE and RESULTs to have RESULT-EXPECTED-TYPE. A simple ‘(WITH-FAILURE-EXPECTED () ...)‘ makes all RESULT SUCCESSes and FAILUREs EXPECTED. ‘(WITH-FAILURE-EXPECTED (’FAILURE) ..)‘ expects FAILUREs only, and any SUCCESSes will be UNEXPECTED.
try
.
Execute the forms that make up the list of forms BODY in random order and return NIL. This may be useful to prevent writing tests that accidentally depend on the order in which subtests are called.
“‘cl-transcript (:check-consistency nil)
(loop repeat 3 do
(with-shuffling ()
(prin1 1)
(prin1 2)))
.. 122112
=> NIL
“‘
try
.
WITH-SKIP skips checks and trials. It forces an immediate SKIP-TRIAL whenever a trial is started (which turns into a VERDICT-SKIP) and makes checks (without intervening trials, of course) evaluate normally but signal RESULT-SKIP. SKIP is NIL cancels the effect of any enclosing WITH-SKIP with SKIP true.
try
.
Define a so-called lambda test to group together CHECKs and other
tests it executes. WITH-TEST executes BODY in its lexical
environment even on a rerun (see @TRY/RERUN).
If TRIAL-VAR is a non-‘NIL‘ symbol, bind it to the trial object.
NAME may be any type, it is purely for presentation purposes. If
NAME is NIL, then it defaults to TRIAL-VAR.
To facilitate returning values, a BLOCK is wrapped around BODY. The
name of the block is TRIAL-VAR if it is a symbol, else it’s NIL.
When both TRIAL-VAR and NAME are specified:
“‘cl-transcript (:dynenv try-transcript)
(with-test (some-feature :name "obscure feature")
(prin1 some-feature)
(is t)
(return-from some-feature (values 1 2)))
.. #<TRIAL (WITH-TEST ("obscure feature")) RUNNING>
.. obscure feature
.. â‹… (IS T)
.. â‹… obscure feature â‹…1
..
==> #<TRIAL (WITH-TEST ("obscure feature")) EXPECTED-SUCCESS 0.002s â‹…1>
=> 1
=> 2
“‘
If only TRIAL-VAR is specified:
“‘cl-transcript (:dynenv try-transcript)
(with-test (some-feature)
(prin1 some-feature)
(is t)
(return-from some-feature (values 1 2)))
.. #<TRIAL (WITH-TEST (SOME-FEATURE)) RUNNING>
.. SOME-FEATURE
.. â‹… (IS T)
.. â‹… SOME-FEATURE â‹…1
..
==> #<TRIAL (WITH-TEST (SOME-FEATURE)) EXPECTED-SUCCESS 0.000s â‹…1>
=> 1
=> 2
“‘
If neither is specified:
“‘cl-transcript (:dynenv try-transcript)
(with-test ()
(prin1 (current-trial))
(is t)
(return (values 1 2)))
.. #<TRIAL (WITH-TEST (NIL)) RUNNING>
.. NIL
.. â‹… (IS T)
.. â‹… NIL â‹…1
..
==> #<TRIAL (WITH-TEST (NIL)) EXPECTED-SUCCESS 0.000s â‹…1>
=> 1
=> 2
“‘
Finally, using that NAME defaults to TRIAL-VAR and that it is valid
to specify non-symbols for TRIAL-VAR, one can also write:
“‘cl-transcript (:dynenv try-transcript)
(with-test ("Some feature")
(prin1 (current-trial))
(is t)
(return (values 1 2)))
.. #<TRIAL (WITH-TEST ("Some feature")) RUNNING>
.. Some feature
.. â‹… (IS T)
.. â‹… Some feature â‹…1
..
==> #<TRIAL (WITH-TEST ("Some feature")) EXPECTED-SUCCESS 0.000s â‹…1>
=> 1
=> 2
“‘
In summary and in contrast to global tests (those defined with
DEFTEST), lambda tests
- have no arguments,
- are defined and called at the same time,
- may not bind their trial object to any variable,
- may have a BLOCK named NIL,
- have a NAME purely for presentation purposes.
Lambda tests can be thought of as analogous to ‘(FUNCALL (LAMBDA ()
BODY))‘. The presence of the LAMBDA is important because it is
stored in the TRIAL object to support @TRY/RERUN.
Bind the symbol TESTS-RUN to an empty ‘EQ‘ hash table and execute BODY. The has table reflects call counts to global tests. Keys are symbols naming global tests, and the values are the number of times the keys have been called.
Change the OUTCOME of the check being signalled to ‘RESULT-ABORT*‘. ‘RESULT-ABORT*‘, being ‘(NOT PASS)‘, will cause the check to return NIL if RECORD-EVENT is invoked on it.
try
.
Invoke the ABORT-TRIAL restart of a RUNNINGP TRIAL.
When CONDITION is a VERDICT for TRIAL, ABORT-TRIAL signals a new
verdict of type VERDICT-ABORT\*. This behavior is similar to that
of ABORT-CHECK. Else, the ABORT-TRIAL restart may record CONDITION,
then it initiates a [non-local exit][clhs] to return from the test
function with VERDICT-ABORT\*. If during the unwinding SKIP-TRIAL
or RETRY-TRIAL is called, then the abort is cancelled.
Since ABORT* is an UNEXPECTED EVENT, ABORT-TRIAL is rarely used programatically. Signalling any error in a trial that’s not caught before the trial’s handler catches it will get turned into an UNHANDLED-ERROR, and TRY will invoke ABORT-TRIAL with it. Thus, instead of invoking ABORT-TRIAL directly, signalling an error will often suffice.
try
.
Returns a value suitable for *CATEGORIES*, which uses only ASCII
characters for the markers.
“‘
’((abort* :marker "!")
(unexpected-failure :marker "F")
(unexpected-success :marker ":")
(skip :marker "-")
(expected-failure :marker "f")
(expected-success :marker "."))
“‘
try
.
Ensure that the format specifier form FORM is in its full form.
TRIALs, like the calls to tests they stand for, nest. CURRENT-TRIAL returns the innermost trial. If there is no currently running test, then an error is signalled. The returned trial is RUNNINGP.
try
.
Return the different elements under PRED in the given sequences as a list of ‘(:INDEX <INDEX> <E1> <E2>)‘ elements, where ‘E1‘ and ‘E2‘ are elements of SEQUENCE1 and SEQUENCE2 at ‘<INDEX>‘, respectively, and they may be MISSING if the corresponding sequence is too short.
“‘cl-transcript (:dynenv try-transcript)
(is (endp (different-elements ’(1 2 3) ’(1 b 3 d))))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. (IS (ENDP #1=(DIFFERENT-ELEMENTS ’(1 2 3) ’(1 B 3 D))))
.. where
.. #1# = ((:INDEX 1 2 B) (:INDEX 3 :MISSING D))
“‘
try
.
See if TRIAL has finished and its [VERDICT][(reader trial)] is a FAIL.
try
.
Returns the default value of *CATEGORIES* (see @TRY/CATEGORIES), which contains some fancy Unicode characters.
try
.
Return whether X is approximately less than Y. Equivalent to ‘<‘, but it also allows for approximate equality according to FLOAT-~=.
try
.
Return whether two numbers, X and Y, are approximately equal either
according to MAX-DIFF-IN-VALUE or MAX-DIFF-IN-ULP.
If the absolute value of the difference of two floats is not greater
than MAX-DIFF-IN-VALUE, then they are considered equal.
If two floats are of the same sign and the number of representable
floats (ULP, unit in the last place) between them is less than
MAX-DIFF-IN-ULP, then they are considered equal.
If neither X nor Y are floats, then the comparison is done with ‘=‘. If one of them is a DOUBLE-FLOAT, then the other is converted to a double float, and the comparison takes place in double float space. Else, both are converted to SINGLE-FLOAT and the comparison takes place in single float space.
try
.
Return whether X is approximately greater than Y. Equivalent to ‘>‘, but it also allows for approximate equality according to FLOAT-~=.
try
.
Change the type of OUTCOME being signalled to EXPECTED and FAILURE.
try
.
Change the type of the OUTCOME being signalled to EXPECTED and SUCCESS. If the original condition is a RESULT, then this will be EXPECTED-RESULT-SUCCESS, if it is a VERDICT, then EXPECTED-VERDICT-SUCCESS.
try
.
Change the type of OUTCOME being signalled to UNEXPECTED and FAILURE.
try
.
Change the type of OUTCOME being signalled to UNEXPECTED and SUCCESS.
try
.
Copy ‘mgl-try.el‘ distributed with this package to TARGET-DIR.
try
.
List all symbols in PACKAGE that name global tests in the sense of TEST-BOUND-P.
Like CL:MISMATCH but CAPTUREs and returns the common prefix and
the mismatched suffixes. The ‘TEST-NOT‘ argument is deprecated by
the CLHS and is not supported. In addition, if MAX-PREFIX-LENGTH and
MAX-SUFFIX-LENGTH are non-‘NIL‘, they must be non-negative integers,
and they limit the number of elements in the prefix and the
suffixes.
“‘cl-transcript (:dynenv try-transcript)
(is (null (mismatch% ’(1 2 3) ’(1 2 4 5))))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. (IS (NULL #1=(MISMATCH% ’(1 2 3) ’(1 2 4 5))))
.. where
.. COMMON-PREFIX = (1 2)
.. MISMATCHED-SUFFIX-1 = (3)
.. MISMATCHED-SUFFIX-2 = (4 5)
.. #1# = 2
“‘
“‘cl-transcript (:dynenv try-transcript)
(is (null (mismatch% "Hello, World!"
"Hello, world!")))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. (IS (NULL #1=(MISMATCH% "Hello, World!" "Hello, world!")))
.. where
.. COMMON-PREFIX = "Hello, "
.. MISMATCHED-SUFFIX-1 = "World!"
.. MISMATCHED-SUFFIX-2 = "world!"
.. #1# = 7
“‘
try
.
See if TRIAL has finished and its [VERDICT][(reader trial)] is a PASS.
try
.
Returns the ‘N‘th most recent trial or NIL if there are not enough trials recorded. Every TRIAL returned by TRY gets pushed onto a list of trials, but only *N-RECENT-TRIALS* are kept.
This restart is always the first restart available when an EVENT is signalled running under TRY (i.e. there is a CURRENT-TRIAL). TRY always invokes RECORD-EVENT when handling events.
try
.
REPLAY-EVENTS reprocesses the events collected (see @TRY/COLLECT)
in TRIAL. It takes the same arguments as TRY except
[DEBUG][argument], [COUNT][argument] and RERUN. This is because
REPLAY-EVENTS does not run any tests. It simply signals the events
collected in TRIAL again to allow further processing. The values of
*CATEGORIES* and *COUNT* that were in effect for TRIAL are used, and
their current values are ignored to be able to keep consistent
counts (see @TRY/COUNT).
Suppose we have run a large test using the default ‘:PRINT ’LEAF‘
‘:COLLECT ’UNEXPECTED‘ arguments for TRY, and now we have too much
output to look at. Instead of searching for the interesting bits in
the output, we can replay the events and print only the UNEXPECTED
events:
“‘
(replay-events ! :print ’unexpected)
“‘
Or we could tell the printer to just print markers for *CATEGORIES*
and :DESCRIBE at the end:
“‘
(let ((*print-parent* nil)
(*print-compactly* t)
(*defer-describe* t)
(*categories* (ascii-std-categories)))
(replay-events !))
.. ................F................!.....
..
.. ;; UNEXPECTED-FAILURE (F) in SOME-TEST INNER-TEST:
.. (IS (= 5 6))
.. debug info
..
.. ;; UNHANDLED-ERROR (!) in SOME-TEST:
.. "my-msg" (MY-ERR)
“‘
try
.
Initiate a [non-local exit][clhs] to go reevaluate the forms wrapped by the check without signalling an OUTCOME.
try
.
Invoke the RETRY-TRIAL restart of RUNNINGP TRIAL. The RETRY-TRIAL
restart may record CONDITION, then it initiates a [non-local
exit][clhs] to go back to the beginning of the test function. If the
non-local exit completes, then
- (N-RETRIES TRIAL) is incremented,
- collected results and trials are cleared (see @TRY/COLLECT),
- counts are zeroed (see @TRY/COUNT), and
- TRIAL-START is signalled again.
If during the unwinding ABORT-TRIAL or SKIP-TRIAL is called, then
the retry is cancelled.
CONDITION (which may be NIL) is recorded if it is an EVENT but not the VERDICT of TRIAL, and the RECORD-EVENT restart is available.
try
.
See if the function call associated with TRIAL has not returned yet. Trials that are not running have a VERDICT and are said to be finished.
try
.
See if LIST1 and LIST2 represent the same set.
See CL:SET-DIFFERENCE for a description of the KEY and TEST arguments.
“‘cl-transcript (:dynenv try-transcript)
(try:is (try:same-set-p ’(1) ’(2)))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
.. UNEXPECTED-FAILURE in check:
.. (IS (SAME-SET-P ’(1) ’(2)))
.. where
.. ONLY-IN-1 = (1)
.. ONLY-IN-2 = (2)
“‘
try
.
Invoke the SET-TRY-DEBUG restart to override the DEBUG argument of the currently running TRY. DEBUG must thus be a suitable type. When the SET-TRY-DEBUG restart is invoked interactively, DEBUG is read as a non-evaluated form from *QUERY-IO*.
Change the OUTCOME of the check being signalled to RESULT-SKIP. RESULT-SKIP, being a PASS, will cause the check to return T if CONTINUE or RECORD-EVENT is invoked on it.
try
.
Invoke the SKIP-TRIAL restart of a RUNNINGP TRIAL.
When CONDITION is a VERDICT for TRIAL, SKIP-TRIAL signals a new
verdict of type VERDICT-SKIP. This behavior is similar to that of
SKIP-CHECK. Else, the SKIP-TRIAL restart may record CONDITION, then
it initiates a [non-local exit][clhs] to return from the test function with
VERDICT-SKIP. If during the unwinding ABORT-TRIAL or RETRY-TRIAL is
called, then the skip is cancelled.
“‘cl-transcript (:dynenv try-transcript)
(with-test (skipped)
(handler-bind ((unexpected-result-failure #’skip-trial))
(is nil)))
.. SKIPPED
.. ⊠(IS NIL)
.. - SKIPPED ⊠1
..
==> #<TRIAL (WITH-TEST (SKIPPED)) SKIP 0.000s ⊠1>
“‘
Invoking SKIP-TRIAL on the TRIAL’s own TRIAL-START skips the trial
being started.
“‘cl-transcript (:dynenv try-transcript)
(let ((*print* ’(or outcome leaf)))
(with-test (parent)
(handler-bind ((trial-start #’skip-trial))
(with-test (child)
(is nil)))))
.. PARENT
.. - CHILD
.. â‹… PARENT
..
“‘
try
.
See if SYMBOL names a global test (i.e. a test defined with DEFTEST). If since the execution of DEFTEST, the symbol has been UNINTERNed, FMAKUNBOUNDed, or redefined with DEFUN, then it no longer names a global test.
TRY runs TESTABLE and handles the EVENTs to collect, debug, print
the results of checks and trials, and to decide what tests to skip
and what to rerun.
DEBUG, COUNT, COLLECT, RERUN, PRINT, and DESCRIBE must all be valid
specifiers for types that are either NIL (the empty type) or have a
non-empty intersection with the type EVENT (e.g. T, OUTCOME,
UNEXPECTED, VERDICT).
TRY sets up a HANDLER-BIND handler for EVENTs and runs TESTABLE (see
@TRY/TESTABLES). When an EVENT is signalled, the handler matches its
type to the value of the DEBUG argument (in the sense of ‘(TYPEP
EVENT DEBUG)‘). If it matches, then the debugger is invoked with the
event. In the debugger, the user has a number of restarts available
to change (see @TRY/EVENT-RESTARTS, @TRY/OUTCOME-RESTARTS,
@TRY/CHECK-RESTARTS, @TRY/TRIAL-RESTARTS, and SET-TRY-DEBUG.
If the debugger is not invoked, TRY invokes the very first restart
available, which is always RECORD-EVENT.
Recording the event is performed as follows.
- Outcome counts are updated (see @TRY/COUNT).
- The event is passed to the collector (see @TRY/COLLECT).
- The event is passed to the printer (see @TRY/PRINT).
- Finally, when rerunning a trial (i.e. when TESTABLE is a trial),
on a TRIAL-START event, the trial may be skipped (see @TRY/RERUN).
TRY returns the values returned by the outermost trial (see @TRY/TESTS).
try
.
unhandled-error
)) ¶try
.
unhandled-error
)) ¶try
.
unhandled-error
)) ¶In the list FORM, whose CAR is FIRST, substitute
subexpressions of interest with a GENSYM and return the new form. As
the second value, return a list of SUBs.
For example, consider ‘(IS (FIND (FOO) LIST))‘. When
SUBSTITUTE-IS-LIST-FORM is invoked on ‘(FIND (FOO) LIST)‘, it
substitutes each argument of FIND with a variable, returning the new
form ‘(FIND TEMP1 TEMP2)‘ and the list of two
substitutions ‘((TEMP2 (FOO) (FOO) NIL) (TEMP3 LIST LIST NIL))‘.
This allows the original form to be rewritten as
“‘
(let* ((temp1 (foo))
(temp2 list))
(find temp1 temp2))
“‘
TEMP1 and TEMP2 may then be reported in the OUTCOME condition
signalled by IS like this:
The following check failed:
(is (find #1=(foo) #2=list))
where
#1# = <return-value-of-foo>
#2# = <value-of-variable-list>
try
.
(eql try:match-values)
) form env) ¶(eql not)
) form env) ¶(eql endp)
) form env) ¶(eql null)
) form env) ¶try
.
trial-event
)) ¶wrapped-stream
) &key abort) ¶line/column-character-output-stream
) &key &allow-other-keys) ¶dummy-with-print-object
) stream) ¶wrapped-stream
)) ¶line/column-character-output-stream
)) ¶sb-gray
.
line/column-character-output-stream
) char) ¶sb-gray
.
‘RESULT-ABORT*‘, ‘VERDICT-ABORT*‘ or ERROR*.
try
.
The third possibility after SUCCESS and FAILURE. Either SKIP or ABORT*.
try
.
Either UNHANDLED-ERROR or NLX, ERROR* causes or
represents abnormal termination of a TRIAL. ABORT-TRIAL can be
called with ERROR*s, but there is little need for explicitly doing
so as RECORD-EVENT, which TRY invokes, takes care of this.
try
.
Common abstract superclass of all events in Try.
try
.
condition
.
Concrete condition classes with EXPECTED in their
name are subclasses of EXPECTED. SKIP is also a subclass of
EXPECTED.
try
.
RESULT or ERROR*.
try
.
Representing a [non-local exit][clhs] of unknown
origin, this is signalled if a TRIAL does not return normally
although it should have because it was not dismissed (see DISMISSAL,
SKIP-TRIAL, ABORT-TRIAL). In this case, there is no CL:ERROR
associated with the event.
An OUTCOME is the resolution of either a TRIAL or a
check (see @TRY/CHECKS), corresponding to subclasses VERDICT and
RESULT.
try
.
try
.
(quote nil)
:elapsed-seconds
This slot is read-only.
(quote nil)
:captures
This slot is read-only.
(quote t)
:print-captures
This slot is read-only.
(quote nil)
RESULT-SKIP or VERDICT-SKIP.
try
.
See @TRY/CHECKS and @TRY/TRIAL-VERDICTS for how SUCCESS or FAILURE is decided.
try
.
A TRIAL-EVENT is either a TRIAL-START or a VERDICT.
try
.
TRIAL-START is signalled when a test function
(see @TRY/TESTS) is entered and a TRIAL is started, it is already
the CURRENT-TRIAL, and the @TRY/TRIAL-RESTARTS are available. It is
also signalled when a trial is retried:
“‘cl-transcript
(let ((*print* nil)
(n 0))
(with-test ()
(handler-bind ((trial-start (lambda (c)
(format t "TRIAL-START for ~S retry#~S~%"
(test-name (trial c))
(n-retries (trial c))))))
(with-test (this)
(incf n)
(when (< n 3)
(retry-trial))))))
.. TRIAL-START for THIS retry#0
.. TRIAL-START for THIS retry#1
.. TRIAL-START for THIS retry#2
..
“‘
The matching of TRIAL-START events is less straightforward than that
of other EVENTs.
- When a TRIAL-START event matches the ‘COLLECT‘ type (see
@TRY/COLLECT), its [TRIAL][(reader trial-event)] is collected.
- Similarly, when a TRIAL-START matches the [PRINT][argument]
type (see @TRY/PRINT), it is printed immediately, and its trial’s
VERDICT will be printed too regardless of whether it matches
[PRINT][argument]. If TRIAL-START does not match
[PRINT][argument], it may still be printed if for example
*PRINT-PARENT* requires it.
- When a TRIAL-START matches the ‘RERUN‘ type (see @TRY/RERUN), its
[TRIAL][(reader trial-event)] may be rerun.
- Also, see WITH-SKIP.
try
.
Concrete condition classes with UNEXPECTED in their
name are subclasses of UNEXPECTED. ABORT* is also a subclass of
UNEXPECTED.
try
.
Signalled when an CL:ERROR condition reaches the
handlers set up DEFTEST or WITH-TEST, or when their *DEBUGGER-HOOK*
is invoked with a condition that’s not an EVENT.
try
.
The unhandled condition.
(quote nil)
:condition
This slot is read-only.
A string if *GATHER-BACKTRACE* was true when this event was signalled, NIL otherwise.
(quote nil)
:backtrace
This slot is read-only.
True if NESTED-CONDITION was caught by a trial’s *DEBUGGER-HOOK*, NIL if it was caught by its ERROR handler.
(quote nil)
:debugger-invoked-p
This slot is read-only.
A VERDICT is the OUTCOME of a TRIAL. It is one of
‘{EXPECTED,UNEXPECTED}-VERDICT-{SUCCESS,FAILURE}‘, VERDICT-SKIP and
VERDICT-ABORT*. Regarding how the verdict type is determined, see
@TRY/TRIAL-VERDICTS.
Verdicts are signalled while their [TRIAL][(reader trial-event)] is
still the CURRENT-TRIAL, and @TRY/TRIAL-RESTARTS are still
available.
“‘cl-transcript (:check-consistency nil)
(try (lambda ()
(handler-bind (((and verdict failure) #’retry-trial))
(with-test (this)
(is (zerop (random 2)))))))
.. (TRY #<FUNCTION (LAMBDA ()) {53038ADB}>)
.. THIS
.. ⊠(IS (ZEROP #1=(RANDOM 2)))
.. where
.. #1# = 1
.. THIS retry #1
.. â‹… (IS (ZEROP (RANDOM 2)))
.. â‹… THIS â‹…1
.. â‹… (TRY #<FUNCTION (LAMBDA ()) {53038ADB}>) â‹…1
..
==> #<TRIAL (TRY #<FUNCTION (LAMBDA ()) {53038ADB}>) EXPECTED-SUCCESS 0.000s â‹…1>
“‘
A SUB (short for substitution) says that in the original form IS is checking, a SUBFORM was substituted (by SUBSTITUTE-IS-FORM) with VAR (if VALUESP is NIL) or with (VALUES-LIST VAR) if VALUESP is true. Conversely, VAR is to be bound to the evaluated NEW-FORM if VALUESP is NIL, and to (MULTIPLE-VALUE-LIST FORM) if VALUESP. NEW-FORM is often ‘EQ‘ to SUBFORM, but it may be different, which is the case when further substitutions are made within a substitution.
TREE-PRINTER prints events in an indented
tree-like structure, with each internal node corresponding to a
TRIAL. This is the default printer (according to *PRINTER* and
*TRY-PRINTER*) and currently the only one.
The following example prints all @TRY/CONCRETE-EVENTS.
“‘cl-transcript (:dynenv try-transcript)
(let ((*debug* nil)
(*print* ’(not trial-start))
(*describe* nil))
(with-test (verdict-abort*)
(with-test (expected-verdict-success))
(with-expected-outcome (’failure)
(with-test (unexpected-verdict-success)))
(handler-bind (((and verdict success) #’force-expected-failure))
(with-test (expected-verdict-failure)))
(handler-bind (((and verdict success) #’force-unexpected-failure))
(with-test (unexpected-verdict-failure)))
(with-test (verdict-skip)
(skip-trial))
(is t :msg "EXPECTED-RESULT-SUCCESS")
(with-failure-expected (’failure)
(is t :msg "UNEXPECTED-RESULT-SUCCESS")
(is nil :msg "EXPECTED-RESULT-FAILURE"))
(is nil :msg "UNEXPECTED-RESULT-FAILURE")
(with-skip ()
(is nil :msg "RESULT-SKIP"))
(handler-bind (((and result success) #’abort-check))
(is t :msg "RESULT-ABORT*"))
(catch ’foo
(with-test (nlx-test)
(throw ’foo nil)))
(error "UNHANDLED-ERROR")))
.. VERDICT-ABORT* ; TRIAL-START
.. â‹… EXPECTED-VERDICT-SUCCESS
.. ⊡ UNEXPECTED-VERDICT-SUCCESS
.. Ă— EXPECTED-VERDICT-FAILURE
.. ⊠UNEXPECTED-VERDICT-FAILURE
.. - VERDICT-SKIP
.. â‹… EXPECTED-RESULT-SUCCESS
.. ⊡ UNEXPECTED-RESULT-SUCCESS
.. Ă— EXPECTED-RESULT-FAILURE
.. ⊠UNEXPECTED-RESULT-FAILURE
.. - RESULT-SKIP
.. ⊟ RESULT-ABORT*
.. NLX-TEST ; TRIAL-START
.. ⊟ non-local exit ; NLX
.. ⊟ NLX-TEST ⊟1 ; VERDICT-ABORT*
.. ⊟ "UNHANDLED-ERROR" (SIMPLE-ERROR)
.. ⊟ VERDICT-ABORT* ⊟3 ⊠1 ⊡1 -1 ×1 ⋅1
..
==> #<TRIAL (WITH-TEST (VERDICT-ABORT*)) ABORT* 0.004s ⊟3 ⊠1 ⊡1 -1 ×1 ⋅1>
“‘
The ‘⊟3 ⊠1 ⊡1 -1 Ă—1 â‹…1‘ part is the counts for *CATEGORIES* printed
with their markers.
try
.
try:*print-indentation*
This slot is read-only.
try:*print-duration*
This slot is read-only.
try:*print-compactly*
This slot is read-only.
try:*defer-describe*
This slot is read-only.
Trials are records of calls to tests (see
@TRY/COUNT, @TRY/COLLECT). Their behaviour as @FUNCALLABLE-INSTANCEs
is explained in @TRY/RERUN.
There are three ways to acquire a TRIAL object: by calling
CURRENT-TRIAL, through the lexical binding of the symbol that names
the test or through the return value of a test:
“‘cl-transcript (:dynenv try-transcript)
(deftest xxx ()
(prin1 xxx))
(xxx)
.. #<TRIAL (XXX) RUNNING>
==> #<TRIAL (XXX) EXPECTED-SUCCESS 0.000s>
“‘
WITH-TRIAL can also provide access to its TRIAL:
“‘cl-transcript (:dynenv try-transcript)
(with-test (t0)
(prin1 t0))
.. #<TRIAL (WITH-TEST (T0)) RUNNING>
==> #<TRIAL (WITH-TEST (T0)) EXPECTED-SUCCESS 0.000s>
“‘
TRIALs are not to be instantiated by client code.
try
.
funcallable-standard-object
.
(setf abort-restart)
.
abort-restart
.
categories
.
cform
.
children
.
count-of
.
counter
.
depth
.
elapsed-seconds
.
has-non-collected-failed-child-p
.
how-it-ended
.
(setf how-to-end)
.
how-to-end
.
initialize-instance
.
n-retries
.
non-collected-counter
.
parent
.
print-object
.
(setf retry-restart)
.
retry-restart
.
(setf skip-restart)
.
skip-restart
.
test-name
.
trial-start
.
verdict
.
(error "trials are not to be instantiated directly.")
try::%test-name
This slot is read-only.
(if try::*trial* (1+ (slot-value try::*trial* (quote try::depth))) 0)
This slot is read-only.
This slot is read-only.
:elapsed-seconds
This slot is read-only.
(if try::*trial* (try::categories try::*trial*) try:*categories*)
:categories
This slot is read-only.
common-lisp
.
(if try::*trial* (try::count-of try::*trial*) try:*count*)
:count
This slot is read-only.
The number of times this [TRIAL][dislocated] has been retried. See RETRY-TRIAL.
0
:n-retries
This slot is read-only.
(member nil :return :abort :retry :skip)
:return
:how-to-end
This slot is read-only.
The [VERDICT][condition] EVENT signalled when this [TRIAL][dislocated] finished or NIL if it has not finished yet.
This slot is read-only.
A list of immediate child VERDICTs, RESULTs, and
ERROR*s collected in reverse chronological order (see
@TRY/COLLECT). The VERDICT of this TRIAL is not among CHILDREN,
but the VERDICTs of child trials’ are.
:children
This slot is read-only.
:has-non-collected-failed-child-p
This slot is read-only.
:non-collected-counter
This slot is read-only.
try
.
try
.
try
.
try
.
try
.
Return a copy of SEQUENCE which is EQUAL to SEQUENCE but not EQ.
try
.
copy-seq
.
try
.
try
.
try
.
try
.
try
.
try
.
try
.
Copy of SEQ and shuffle it using Fisher-Yates algorithm.
try
.
try
.
line/column-character-output-stream
)) ¶automatically generated reader method
try
.
line/column-character-output-stream
)) ¶automatically generated writer method
try
.
tree-printer
)) ¶automatically generated reader method
try
.
tree-printer
) outcome) ¶try
.
tree-printer
)) ¶try
.
tree-printer
)) ¶automatically generated reader method
try
.
wrapped-stream
)) ¶automatically generated reader method
try
.
line/column-character-output-stream
)) ¶automatically generated reader method
line
.
try
.
line/column-character-output-stream
)) ¶automatically generated writer method
line
.
try
.
try-internal-error
)) ¶try
.
tree-printer
)) ¶automatically generated reader method
try
.
tree-printer
)) ¶automatically generated reader method
try
.
tree-printer
) (leaf leaf
)) ¶tree-printer
) (verdict verdict
)) ¶tree-printer
) (event trial-start
)) ¶try
.
line/column-character-output-stream
)) ¶try
.
line/column-character-output-stream
)) ¶try
.
tree-printer
)) ¶automatically generated reader method
try
.
tree-printer
)) ¶automatically generated writer method
try
.
unhandled-error
) stream &key terse ctx) ¶trial-start
) stream &key terse ctx) ¶try
.
fundamental-character-output-stream
.
wrapped-stream
.
PRINTER is the abstract base class for all printers.
try
.
The stream to which output shall be written.
common-lisp
.
*debug-io*
:stream
This slot is read-only.
The PRINT argument of TRY.
t
:print-type
This slot is read-only.
The DESCRIBE argument of TRY.
t
:describe-type
This slot is read-only.
The value of *PRINT-PARENT* when the printer was instantiated.
try:*print-parent*
This slot is read-only.
(append try:*event-print-bindings* (sb-int:quasiquote ((*package* #s(sb-impl::comma :expr *package* :kind 0)) (try:*categories* #s(sb-impl::comma :expr try:*categories* :kind 0)) (try:*event-print-bindings* nil))))
A list
This slot is read-only.
Jump to: | %
(
A B C D E F G H I L M N O P R S T V W |
---|
Jump to: | %
(
A B C D E F G H I L M N O P R S T V W |
---|
Jump to: | !
*
@
A B C D E F H I L M N P R S T V |
---|