The try Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The try Reference Manual

This is the try Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 06:22:01 2022 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

# Try Manual

###### \[in package TRY\]
## TRY ASDF System

- Version: 0.0.1
- Description: Try is a test framework.
- Long Description: Try is what we get if we make tests functions and
  build a test framework on top of the condition system as
  [Stefil](https://common-lisp.net/project/stefil/index-old.shtml) did
  but also address the issue of rerunning and replaying, make the IS
  check more capable, use the types of the condition hierarchy to
  parameterize what to debug, print, rerun, and finally document the
  whole thing.
- Licence: MIT, see COPYING.
- Author: Gábor Melis
- Mailto: [mega@retes.hu](mailto:mega@retes.hu)
- Homepage: [http://melisgl.github.io/try](http://melisgl.github.io/try)
- Bug tracker: [https://github.com/melisgl/try/issues](https://github.com/melisgl/try/issues)
- Source control: [GIT](https://github.com/melisgl/try.git)

## Links

Here is the [official repository](https://github.com/melisgl/try)
and the [HTML
documentation](http://melisgl.github.io/mgl-pax-world/try-manual.html)
for the latest version.

## Tutorial

Try is a library for unit testing with equal support for
interactive and non-interactive workflows. Tests are functions, and
almost everything else is a condition, whose types feature
prominently in parameterization.

##### Looking for Truth

@TRY/IS is a replacement for CL:ASSERT, that can capture values of
subforms to provide context to failures:

```common-lisp
(is (= (1+ 5) 0))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS (= #1=(1+ 5) 0))
..   where
..     #1# = 6
```

This is a PAX transcript,
output is prefixed with `..` and the unreadable return value with
`==>`.

Note the `#N#` syntax due to *PRINT-CIRCLE*.

##### Checking Multiple Values

IS automatically captures values of
arguments to functions like `1+` in the above example. Values of
other interesting subforms can be explicitly
captured. IS supports capturing multiple
values and can be taught how to deal with macros. The combination of these
features allows MATCH-VALUES to be implementable as tiny extension:

```common-lisp
(is (match-values (values (1+ 5) "sdf")
      (= * 0)
      (string= * "sdf")))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS
..      (MATCH-VALUES #1=(VALUES (1+ 5) #2="sdf")
..        (= * 0)
..        (STRING= * "sdf")))
..   where
..     #1# == 6
..            #2#
```

In the body of MATCH-VALUES, `*` is bound to
successive return values of some form, here `(VALUES (1+ 5) "sdf")`.
MATCH-VALUES comes with an automatic rewrite rule that captures the
values of this form, which are printed above as `#1# == 6 #2#`. IS
is flexible enough that all other checks (SIGNALS, SIGNALS-NOT,
INVOKES-DEBUGGER, INVOKES-DEBUGGER-NOT, FAILS, and IN-TIME are built
on top of it.

##### Writing Tests

Beyond a fancy ASSERT, Try provides tests, which are Lisp functions
that record their execution in TRIAL objects. Let's define a test
and run it:

```common-lisp
(deftest should-work ()
  (is t))

(should-work)
.. SHOULD-WORK            ; TRIAL-START
..   ⋅ (IS T)             ; EXPECTED-RESULT-SUCCESS
.. ⋅ SHOULD-WORK ⋅1       ; EXPECTED-VERDICT-SUCCESS
..
==> #
```

Try is driven by conditions, and the comments to the right give the
type of the condition that is printed on that line. The `⋅`
character marks successes.

We could have run our test with `(TRY 'SHOULD-WORK)`, as well, which
does pretty much the same thing except it defaults to never entering
the debugger, whereas calling a test function directly enters the
debugger on events whose type matches the type in the variable
*DEBUG*.

```common-lisp
(try 'should-work)
.. SHOULD-WORK
..   ⋅ (IS T)
.. ⋅ SHOULD-WORK ⋅1
..
==> #
```

##### Test Suites

Test suites are just tests which call other tests.

```common-lisp
(deftest my-suite ()
  (should-work)
  (is (= (foo) 5)))

(defun foo ()
  4)

(try 'my-suite)
.. MY-SUITE                 ; TRIAL-START
..   SHOULD-WORK            ; TRIAL-START
..     ⋅ (IS T)             ; EXPECTED-RESULT-SUCCESS
..   ⋅ SHOULD-WORK ⋅1       ; EXPECTED-VERDICT-SUCCESS
..   ⊠ (IS (= #1=(FOO) 5))  ; UNEXPECTED-RESULT-FAILURE
..     where
..       #1# = 4
.. ⊠ MY-SUITE ⊠1 ⋅1         ; UNEXPECTED-VERDICT-FAILURE
..
==> #
```

`⊠` marks UNEXPECTED-FAILUREs. Note how the failure of `(IS (= (FOO)
5))` caused `MY-SUITE` to fail as well.

##### Filtering Output

To focus on the important bits, we can print only the UNEXPECTED
events:

```common-lisp
(try 'my-suite :print 'unexpected)
.. MY-SUITE
..   ⊠ (IS (= #1=(FOO) 5))
..     where
..       #1# = 4
.. ⊠ MY-SUITE ⊠1 ⋅1
..
==> #
```

Note that `SHOULD-WORK` is still run, and its check's success is
counted as evidenced by`⋅1`. The above effect can also be achieved
without running the tests again with REPLAY-EVENTS.

##### Debugging

Let's figure out what went wrong:

```
(my-suite)

;;; Here the debugger is invoked:
UNEXPECTED-FAILURE in check:
  (IS (= #1=(FOO) 5))
where
  #1# = 4
Restarts:
 0: [RECORD-EVENT] Record the event and continue.
 1: [FORCE-EXPECTED-SUCCESS] Change outcome to TRY:EXPECTED-RESULT-SUCCESS.
 2: [FORCE-UNEXPECTED-SUCCESS] Change outcome to TRY:UNEXPECTED-RESULT-SUCCESS.
 3: [FORCE-EXPECTED-FAILURE] Change outcome to TRY:EXPECTED-RESULT-FAILURE.
 4: [ABORT-CHECK] Change outcome to TRY:RESULT-ABORT*.
 5: [SKIP-CHECK] Change outcome to TRY:RESULT-SKIP.
 6: [RETRY-CHECK] Retry check.
 7: [ABORT-TRIAL] Record the event and abort trial TRY::MY-SUITE.
 8: [SKIP-TRIAL] Record the event and skip trial TRY::MY-SUITE.
 9: [RETRY-TRIAL] Record the event and retry trial TRY::MY-SUITE.
 10: [SET-TRY-DEBUG] Supply a new value for :DEBUG of TRY:TRY.
 11: [RETRY] Retry SLIME interactive evaluation request.
```

In the [SLIME](https://common-lisp.net/project/slime/doc/html/)
debugger, we press `v` on the frame of the call to `MY-SUITE` to
navigate to its definition, realize what the problem is and fix
`FOO`:

```common-lisp
(defun foo ()
  5)
```

Now, we select the `RETRY-TRIAL` restart, and on the retry
`MY-SUITE` passes. The full output is:

```
MY-SUITE
  SHOULD-WORK
    ⋅ (IS T)
  ⋅ SHOULD-WORK ⋅1
WARNING: redefining TRY::FOO in DEFUN
  ⊠ (IS (= #1=(FOO) 5))
    where
      #1# = 4
MY-SUITE retry #1
  SHOULD-WORK
    ⋅ (IS T)
  ⋅ SHOULD-WORK ⋅1
  ⋅ (IS (= (FOO) 5))
⋅ MY-SUITE ⋅2
```

##### Rerunning Stuff

Instead of working interactively, one can fix the failing test and
rerun it. Now, let's fix `MY-SUITE` and rerun it:

```common-lisp
(deftest my-suite ()
  (should-work)
  (is nil))

(try 'my-suite)
.. MY-SUITE
..   SHOULD-WORK
..     ⋅ (IS T)
..   ⋅ SHOULD-WORK ⋅1
..   ⊠ (IS NIL)
.. ⊠ MY-SUITE ⊠1 ⋅1
..
==> #

(deftest my-suite ()
  (should-work)
  (is t))

(try !)
.. MY-SUITE
..   ⋅ (IS T)
.. ⋅ MY-SUITE ⋅1
..
==> #
```

Here, `!` refers to the most recent TRIAL returned by TRY. When a
trial is passed to TRY or is `FUNCALL`ed, trials in it which match
the type in TRY's RERUN argument are rerun (here, UNEXPECTED by
default). `SHOULD-WORK` and its check are `EXPECTED-SUCCESS`es,
hence they don't match UNEXPECTED and are not rerun.

##### Conditional Execution

Conditional execution can be achieved simply testing the TRIAL
object returned by @TRY/TESTS.

```
(deftest my-suite ()
  (when (passedp (should-work))
    (is t :msg "a test that depends on SHOULD-WORK")
    (when (is nil)
      (is nil :msg "never run"))))
```

##### Skipping

```common-lisp
(deftest my-suite ()
  (with-skip ((not (server-available-p)))
    (test-server)))

(deftest test-server ()
  (is t))

(defun server-available-p ()
  nil)

(my-suite)
==> #
```

In the above, `TEST-SERVER` was skipped. No checks were made, no
errors happened, so nothing was printed.

##### Expecting Outcomes

```common-lisp
(deftest known-broken ()
  (with-failure-expected (t)
    (is nil)))

(known-broken)
.. KNOWN-BROKEN
..   × (IS NIL)
.. ⋅ KNOWN-BROKEN ×1
..
==> #
```

`×` marks `EXPECTED-SUCCESS`es. `(WITH-SKIP (T) ...)` makes all
checks successes and failures EXPECTED, which are counted in their
own *CATEGORIES* by default but don't make the enclosing tests to
fail. Also see WITH-EXPECTED-OUTCOME.

##### Running Tests on Definition

With *RUN-DEFTEST-WHEN*, one can run test on definition. To run
tests on evaluation, as in SLIME `C-M-x`, `slime-eval-defun`:

```common-lisp
(setq *run-deftest-when* :execute)

(deftest some-test ()
  (is t))
.. SOME-TEST
..   ⋅ (IS T)
.. ⋅ SOME-TEST ⋅1
..
=> SOME-TEST

(setq *run-deftest-when* nil)
```

##### Fixtures

There is no direct support for fixtures in Try. One can easily write
macros like the following.

```
(defvar *server* nil)

(defmacro with-xxx (&body body)
  `(flet ((,with-xxx-body ()
            ,@body))
     (if *server*
         (with-xxx-body)
         (with-server (make-expensive-server)
           (with-xxx-body)))))
```

Plus, with support for selectively @TRY/RERUN, the need for fixtures
is lessened.

##### Packages

The suggested way of writing tests is to call test functions
explicitly:

```
(defpackage :some-test-package
  (:use #:common-lisp #:try))
(in-package :some-test-package)

(deftest test-all ()
  (test-this)
  (test-that))

(deftest test-this ()
  (test-this/more))

(deftest test-this/more ()
  (is t))

(deftest test-that ()
  (is t))

(deftest not-called ()
  (is t))

(defun test ()
  (warn-on-tests-not-run ((find-package :some-test-package))
    (try 'test-all)))

(test)
.. TEST-ALL
..   TEST-THIS
..     TEST-THIS/MORE
..       ⋅ (IS T)
..     ⋅ TEST-THIS/MORE ⋅1
..   ⋅ TEST-THIS ⋅1
..   TEST-THAT
..     ⋅ (IS T)
..   ⋅ TEST-THAT ⋅1
.. ⋅ TEST-ALL ⋅2
.. WARNING: Test NOT-CALLED not run.
==> #
```

Note how the TEST function uses WARN-ON-TESTS-NOT-RUN to catch any
tests defined in `SOME-TEST-PACKAGE` that were not run. Tests can be
deleted by FMAKUNBOUND, UNINTERN, or by redefining the function with
DEFUN. Tests defined in a given package can be listed with
LIST-PACKAGE-TESTS.

This style allows higher level tests to establish the dynamic
environment necessary for lower level tests.

## Events

Try is built around events implemented as CONDITIONs.
Matching the types of events to *DEBUG*, *COUNT*, *COLLECT*, *RERUN*,
*PRINT*, and *DESCRIBE* is what gives Try its flexibility.

### Middle Layer of Events

The event hierarchy is fairly involved, so let's start in the middle.
The condition EVENT has 4 disjoint subclasses:

- TRIAL-START, which corresponds to the entry to a test (see
  @TRY/TESTS),

- VERDICT, the OUTCOME of a TRIAL,

- RESULT, the OUTCOME of a check (see @TRY/CHECKS), and

- ERROR\*, an unexpected CL:ERROR or unadorned @NON-LOCAL-EXIT.

```common-lisp
(let (;; We don't want to debug nor print a backtrace for the error below.
      (*debug* nil)
      (*describe* nil))
  ;; signals TRIAL-START / VERDICT-ABORT* on entry / exit
  (with-test (demo)
    ;; signals EXPECTED-RESULT-SUCCESS
    (is t)
    ;; signals UNHANDLED-ERROR with a nested CL:ERROR
    (error "xxx")))
.. DEMO                       ; TRIAL-START
..   ⋅ (IS T)                 ; EXPECTED-RESULT-SUCCESS (⋅)
..   ⊟ "xxx" (SIMPLE-ERROR)   ; UNHANDLED-ERROR (⊟)
.. ⊟ DEMO ⊟1 ⋅1               ; VERDICT-ABORT* (⊟)
..
==> #
```


### Concrete Events

The non-abstract condition classes of events that are actually
signalled are called concrete.

TRIAL-START is a concrete event class. RESULTs and VERDICTs have six
 concrete subclasses:

- EXPECTED-RESULT-SUCCESS, UNEXPECTED-RESULT-SUCCESS,
   EXPECTED-RESULT-FAILURE, UNEXPECTED-RESULT-FAILURE,
   RESULT-SKIP, RESULT-ABORT\*

- EXPECTED-VERDICT-SUCCESS, UNEXPECTED-VERDICT-SUCCESS,
   EXPECTED-VERDICT-FAILURE, UNEXPECTED-VERDICT-FAILURE,
   VERDICT-SKIP, VERDICT-ABORT\*

ERROR\* is an abstract class with two concrete subclasses:

- UNHANDLED-ERROR, signalled when a CL:ERROR reaches the handler set
   up by DEFTEST or WITH-TEST, or when the debugger is invoked.

- NLX, signalled when no error was detected by the handler, but the
   trial finishes with a @NON-LOCAL-EXIT.

These are the 15 concrete event classes.

### Event Glue

These condition classes group various bits of the
@TRY/CONCRETE-EVENTS and the @TRY/MIDDLE-LAYER-OF-EVENTS for ease of
reference.

Concrete event classes except TRIAL-START are subclasses of
hyphen-separated words in their name. For example,
UNEXPECTED-RESULT-FAILURE inherits from UNEXPECTED, RESULT, and
FAILURE, so it matches types such as UNEXPECTED or `(AND UNEXPECTED
RESULT)`.

- [condition] EVENT

    Common abstract superclass of all events in Try.

- [condition] EXPECTED EVENT

    Concrete condition classes with EXPECTED in their
    name are subclasses of EXPECTED. SKIP is also a subclass of
    EXPECTED.

- [condition] UNEXPECTED EVENT

    Concrete condition classes with UNEXPECTED in their
    name are subclasses of UNEXPECTED. ABORT\* is also a subclass of
    UNEXPECTED.

- [condition] SUCCESS EVENT

    See @TRY/CHECKS and @TRY/TRIAL-VERDICTS for how
    SUCCESS or FAILURE is decided.

- [condition] FAILURE EVENT

    See SUCCESS.

- [condition] DISMISSAL EVENT

    The third possibility after SUCCESS and FAILURE.
    Either SKIP or ABORT\*.

- [condition] ABORT* UNEXPECTED

    `RESULT-ABORT*`, `VERDICT-ABORT*` or ERROR\*.

- [condition] SKIP EXPECTED DISMISSAL

    RESULT-SKIP or VERDICT-SKIP.

- [condition] LEAF EVENT

    RESULT or ERROR\*.

- [type] EXPECTED-SUCCESS

    A shorthand for `(AND EXPECTED SUCCESS)`.

- [type] UNEXPECTED-SUCCESS

    A shorthand for `(AND UNEXPECTED SUCCESS)`.

- [type] EXPECTED-FAILURE

    A shorthand for `(AND EXPECTED FAILURE)`.

- [type] UNEXPECTED-FAILURE

    A shorthand for `(AND UNEXPECTED FAILURE)`.

- [type] PASS

    An OUTCOME that's not an ABORT\* or an UNEXPECTED FAILURE.

- [type] FAIL

    An ABORT\* or an UNEXPECTED FAILURE.

### Printing Events

- [variable] *EVENT-PRINT-BINDINGS* ((\*PRINT-CIRCLE\* T))

    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.

### Event Restarts

Only RECORD-EVENT is applicable to all EVENTs. See
@TRY/CHECK-RESTARTS, @TRY/TRIAL-RESTARTS for more.

- [function] RECORD-EVENT &OPTIONAL CONDITION

    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.

### Outcomes

- [condition] OUTCOME EVENT

    An OUTCOME is the resolution of either a TRIAL or a
    check (see @TRY/CHECKS), corresponding to subclasses VERDICT and
    RESULT.

- [macro] WITH-EXPECTED-OUTCOME (EXPECTED-TYPE) &BODY BODY

    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:
    
    ```common-lisp
    (let ((*debug* nil))
      (with-expected-outcome ('(or result (and verdict success)))
        (with-test (t1)
          (is nil))))
    .. T1
    ..   × (IS NIL)
    .. ⋅ T1 ×1
    ..
    ==> #
    ```
    
    This is equivalent to `(WITH-FAILURE-EXPECTED () ...)`. To make
    result failures expected but result successes unexpected:
    
    ```common-lisp
    (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
    ..
    ==> #
    ```
    
    This is equivalent to `(WITH-FAILURE-EXPECTED ('FAILURE) ...)`. The
    final example leaves result failures unexpected but makes both
    verdict successes and failures expected:
    
    ```common-lisp
    (let ((*debug* nil))
      (with-expected-outcome ('(or (and result success) verdict))
        (with-test (t1)
          (is nil))))
    .. T1
    ..   ⊠ (IS NIL)
    .. × T1 ⊠1
    ..
    ==> #
    ```


- [macro] WITH-FAILURE-EXPECTED (&OPTIONAL (RESULT-EXPECTED-TYPE T) (VERDICT-EXPECTED-TYPE ''SUCCESS)) &BODY BODY

    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 `SUCCESS`es and
    FAILUREs EXPECTED. `(WITH-FAILURE-EXPECTED ('FAILURE) ..)` expects
    FAILUREs only, and any `SUCCESS`es will be UNEXPECTED.

- [macro] WITH-SKIP (&OPTIONAL (SKIP T)) &BODY BODY

    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.

#### Outcome Restarts

- [function] FORCE-EXPECTED-SUCCESS &OPTIONAL CONDITION

    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.

- [function] FORCE-UNEXPECTED-SUCCESS &OPTIONAL CONDITION

    Change the type of OUTCOME being signalled to UNEXPECTED and
    SUCCESS.

- [function] FORCE-EXPECTED-FAILURE &OPTIONAL CONDITION

    Change the type of OUTCOME being signalled to EXPECTED and
    FAILURE.

- [function] FORCE-UNEXPECTED-FAILURE &OPTIONAL CONDITION

    Change the type of OUTCOME being signalled to UNEXPECTED and
    FAILURE.

#### Checks

Checks are like CL:ASSERTs, they check whether some condition holds
and signal an OUTCOME. The outcome signalled for checks is a
subclass of RESULT.

Take, for example, `(IS (= X 5))`. Depending on whether `X` is
indeed 5, some kind of RESULT SUCCESS or FAILURE will be signalled.
WITH-EXPECTED-OUTCOME determines whether it's EXPECTED or
UNEXPECTED, and we have one of EXPECTED-RESULT-SUCCESS,
UNEXPECTED-RESULT-SUCCESS, EXPECTED-RESULT-FAILURE,
UNEXPECTED-RESULT-FAILURE to signal. Furthermore, if WITH-SKIP is in
effect, then RESULT-SKIP is signalled.

The result is signalled with `#'SIGNAL` if it is a PASS, else it's
signalled with `#'ERROR`. This distinction matters only if the event
is not handled, which is never the case in a TRIAL. Standalone
checks though - those that are not enclosed by a trial - invoke the
debugger on RESULTs which are not of type PASS.

The signalled RESULT is not final until RECORD-EVENT is invoked on
it, and it can be changed with the @TRY/OUTCOME-RESTARTS and the
@TRY/CHECK-RESTARTS.

- [condition] RESULT LEAF OUTCOME

- [condition] EXPECTED-RESULT-SUCCESS EXPECTED RESULT SUCCESS

- [condition] UNEXPECTED-RESULT-SUCCESS UNEXPECTED RESULT SUCCESS

- [condition] EXPECTED-RESULT-FAILURE EXPECTED RESULT FAILURE

- [condition] UNEXPECTED-RESULT-FAILURE UNEXPECTED RESULT FAILURE

- [condition] RESULT-SKIP RESULT SKIP

- [condition] RESULT-ABORT* RESULT ABORT\* DISMISSAL

##### Check Restarts

- [function] ABORT-CHECK &OPTIONAL CONDITION

    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.

- [function] SKIP-CHECK &OPTIONAL CONDITION

    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.

- [function] RETRY-CHECK &OPTIONAL CONDITION

    Initiate a @NON-LOCAL-EXIT to go reevaluate the forms wrapped by
    the check without signalling an OUTCOME.

#### Trials

- [type] TRIAL

    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:
    
    ```common-lisp
    (deftest xxx ()
      (prin1 xxx))
    
    (xxx)
    .. #
    ==> #
    ```
    
    WITH-TRIAL can also provide access to its TRIAL:
    
    ```common-lisp
    (with-test (t0)
      (prin1 t0))
    .. #
    ==> #
    ```
    
    TRIALs are not to be instantiated by client code.

- [function] CURRENT-TRIAL

    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.

##### Trial Events

- [condition] TRIAL-EVENT EVENT

    A TRIAL-EVENT is either a TRIAL-START or a
    VERDICT.

- [reader] TRIAL TRIAL-EVENT (:TRIAL)

- [condition] TRIAL-START TRIAL-EVENT

    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:
    
    ```common-lisp
    (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 is collected.
    
    - Similarly, when a TRIAL-START matches the PRINT
      type (see @TRY/PRINT), it is printed immediately, and its trial's
      VERDICT will be printed too regardless of whether it matches
      PRINT. If TRIAL-START does not match
      PRINT, 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 may be rerun.
    
    - Also, see WITH-SKIP.


- [condition] VERDICT TRIAL-EVENT OUTCOME

    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 is
    still the CURRENT-TRIAL, and @TRY/TRIAL-RESTARTS are still
    available.
    
    ```common-lisp
    (try (lambda ()
           (handler-bind (((and verdict failure) #'retry-trial))
             (with-test (this)
               (is (zerop (random 2)))))))
    .. (TRY #)
    ..   THIS
    ..     ⊠ (IS (ZEROP #1=(RANDOM 2)))
    ..       where
    ..         #1# = 1
    ..   THIS retry #1
    ..     ⋅ (IS (ZEROP (RANDOM 2)))
    ..   ⋅ THIS ⋅1
    .. ⋅ (TRY #) ⋅1
    ..
    ==> #) EXPECTED-SUCCESS 0.000s ⋅1>
    ```


- [condition] EXPECTED-VERDICT-SUCCESS EXPECTED VERDICT SUCCESS

- [condition] UNEXPECTED-VERDICT-SUCCESS UNEXPECTED VERDICT SUCCESS

- [condition] EXPECTED-VERDICT-FAILURE EXPECTED VERDICT FAILURE

- [condition] UNEXPECTED-VERDICT-FAILURE UNEXPECTED VERDICT FAILURE

- [condition] VERDICT-SKIP VERDICT SKIP

- [condition] VERDICT-ABORT* VERDICT ABORT\* DISMISSAL

##### Trial Verdicts

When a trial finished, a VERDICT is signalled. The verdict's type
is determined as follows.

- It is a VERDICT-SKIP if

    - SKIP-TRIAL was called on the trial, or

    - ABORT-TRIAL, SKIP-TRIAL, or RETRY-TRIAL was called on an
      enclosing trial, and

    - these were not overruled by a later ABORT-TRIAL or RETRY-TRIAL
      on the trial.

- It is a VERDICT-ABORT\* if ABORT-TRIAL was called on the trial, and
  it wasn't overruled by a later SKIP-TRIAL or RETRY-TRIAL.

- If all children (including those not collected in CHILDREN) of the
  trial PASS, then the verdict will be a SUCCESS, else it will be a
  FAILURE.

- Subject to the WITH-EXPECTED-OUTCOME in effect,
  `{EXPECTED,UNEXPECTED}-VERDICT-{SUCCESS,FAILURE}` is the type of
  the verdict which will be signalled.

The verdict of this type is signalled, but its type can be changed
by the @TRY/OUTCOME-RESTARTS or the @TRY/TRIAL-RESTARTS before
RECORD-EVENT is invoked on it.

- [reader] VERDICT TRIAL (= NIL)

    The VERDICT EVENT signalled when this
    TRIAL finished or NIL if it has not finished yet.

- [function] RUNNINGP TRIAL

    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.

- [function] PASSEDP TRIAL

    See if TRIAL has finished and its VERDICT is a
    PASS.

- [function] FAILEDP TRIAL

    See if TRIAL has finished and its VERDICT is a
    FAIL.

##### Trial Restarts

There are three restarts available for manipulating running
trials: ABORT-TRIAL, SKIP-TRIAL, and RETRY-TRIAL. They may be
invoked programatically or from the debugger. ABORT-TRIAL is also
invoked by TRY when encountering UNHANDLED-ERROR.

The functions below invoke one of these restarts associated with a
TRIAL. It is an error to call them on trials that are not RUNNINGP,
but they may be called on trials other than the CURRENT-TRIAL. In
that case, any intervening trials are skipped.

```common-lisp
;; Skipped trials are marked with '-' in the output.
(with-test (outer)
  (with-test (inner)
    (is t)
    (skip-trial nil outer)))
.. OUTER
..   INNER
..     ⋅ (IS T)
..   - INNER ⋅1
.. - OUTER ⋅1
..
==> #
```

Furthermore, all three restarts initiate a @NON-LOCAL-EXIT to return
from the trial. If during the unwinding of the stack, the
non-local-exit is cancelled (see @CANCELLED-NLX), the appropriate
restart will be invoked upon returning from the trial. In the
following example, the non-local exit from a skip is cancelled by a
THROW.

```common-lisp
(with-test (some-test)
  (catch 'foo
    (unwind-protect
         (skip-trial)
      (throw 'foo nil)))
  (is t :msg "check after skip"))
.. SOME-TEST
..   ⋅ check after skip
.. - SOME-TEST ⋅1
..
==> #
```

In the next example, the non-local exit from a skip is cancelled by
an ERROR, which triggers an ABORT-TRIAL.

```common-lisp
(let ((*debug* nil)
      (*describe* nil))
  (with-test (foo)
    (unwind-protect
         (skip-trial)
      (error "xxx"))))
.. FOO
..   ⊟ "xxx" (SIMPLE-ERROR)
.. ⊟ FOO ⊟1
..
==> #
```

All three restarts may be invoked on any EVENT, including the
trial's own TRIAL-START and VERDICT. If their CONDITION
argument is an EVENT (RETRY-TRIAL has a special case here), they
also record it (as in RECORD-EVENT) to ensure that when they handle
an EVENT in the debugger or programatically that event is not
dropped.

- [function] ABORT-TRIAL &OPTIONAL CONDITION (TRIAL (CURRENT-TRIAL))

    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 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.

- [function] SKIP-TRIAL &OPTIONAL CONDITION (TRIAL (CURRENT-TRIAL))

    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 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.
    
    ```common-lisp
    (with-test (skipped)
      (handler-bind ((unexpected-result-failure #'skip-trial))
        (is nil)))
    .. SKIPPED
    ..   ⊠ (IS NIL)
    .. - SKIPPED ⊠1
    ..
    ==> #
    ```
    
    Invoking SKIP-TRIAL on the TRIAL's own TRIAL-START skips the trial
    being started.
    
    ```common-lisp
    (let ((*print* '(or outcome leaf)))
      (with-test (parent)
        (handler-bind ((trial-start #'skip-trial))
          (with-test (child)
            (is nil)))))
    .. PARENT
    ..   - CHILD
    .. ⋅ PARENT
    ..
    ```


- [function] RETRY-TRIAL &OPTIONAL CONDITION (TRIAL (CURRENT-TRIAL))

    Invoke the RETRY-TRIAL restart of RUNNINGP TRIAL. The RETRY-TRIAL
    restart may record CONDITION, then it initiates a @NON-LOCAL-EXIT 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.

- [reader] N-RETRIES TRIAL (:N-RETRIES = 0)

    The number of times this TRIAL has
    been retried. See RETRY-TRIAL.

### Errors

- [condition] ERROR* ABORT\* TRIAL-EVENT LEAF

    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.

- [reader] TEST-NAME ERROR\* (:TEST-NAME)

- [condition] UNHANDLED-ERROR ERROR\*

    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.

- [reader] NESTED-CONDITION UNHANDLED-ERROR (:CONDITION = 'NIL)

- [reader] BACKTRACE-OF UNHANDLED-ERROR (:BACKTRACE = 'NIL)

- [reader] DEBUGGER-INVOKED-P UNHANDLED-ERROR (:DEBUGGER-INVOKED-P = 'NIL)

- [variable] *GATHER-BACKTRACE* T

    Capturing the backtrace can be expensive. *GATHER-BACKTRACE*
    controls whether UNHANDLED-ERRORs shall have their BACKTRACE-OF
    populated.

- [condition] NLX ERROR\*

    Representing a @NON-LOCAL-EXIT 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.

### Categories

Categories determine how event types are printed and events of
what types are counted together.

The default value of *CATEGORIES* is

```
((abort*             :marker "⊟")
 (unexpected-failure :marker "⊠")
 (unexpected-success :marker "⊡")
 (skip               :marker "-")
 (expected-failure   :marker "×")
 (expected-success   :marker "⋅"))
```

which says that all concrete EVENTs that are of type ABORT\* (i.e.
`RESULT-ABORT*`, `VERDICT-ABORT*`, UNHANDLED-ERROR, and NLX) are to
be marked with `"⊟"` when printed (see @TRY/PRINT). Also, the six
types define six counters for @TRY/COUNT. Note that UNEXPECTED
events have the same marker but squared as their EXPECTED
counterpart.

- [variable] *CATEGORIES* "- see above -"

    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.

- [function] FANCY-STD-CATEGORIES

    Returns the default value of *CATEGORIES* (see @TRY/CATEGORIES),
    which contains some fancy Unicode characters.

- [function] ASCII-STD-CATEGORIES

    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 "."))
    ```


## The IS Macro

IS is the most fundamental one among @TRY/CHECKS, on which all
the others are built, and it is a replacement for CL:ASSERT that can
capture values of subforms to provide context to failures:

```common-lisp
(is (= (1+ 5) 0))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS (= #1=(1+ 5) 0))
..   where
..     #1# = 6
```

IS automatically captures values of arguments to functions like `1+`
in the above example. Values of other interesting subforms can be
explicitly requested to be captured. IS supports capturing multiple
values and can be taught how to deal with macros. The combination of
these features allows MATCH-VALUES to be implementable as tiny
extension:

```common-lisp
(is (match-values (values (1+ 5) "sdf")
      (= * 0)
      (string= * "sdf")))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS
..      (MATCH-VALUES #1=(VALUES (1+ 5) #2="sdf")
..        (= * 0)
..        (STRING= * "sdf")))
..   where
..     #1# == 6
..            #2#
```

IS is flexible enough that all other checks (SIGNALS, SIGNALS-NOT,
INVOKES-DEBUGGER, INVOKES-DEBUGGER-NOT, FAILS, and IN-TIME are built
on top of it.

- [macro] IS FORM &KEY MSG CTX (CAPTURE T) (PRINT-CAPTURES T) (RETRY T)

    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.
    
    ```common-lisp
    (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 # 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.

- [variable] *IS-FORM*

    IS binds this to its FORM argument for CTX and MSG.

- [variable] *IS-CAPTURES*

    Captures made during an IS evaluation are made available for
    CTX via *IS-CAPTURES*.

### Format Specifier Forms

A format specifier form is a Lisp form, typically an argument to
macro, standing for the FORMAT-CONTROL and FORMAT-ARGS arguments to
the FORMAT function.

It may be a constant string:

```common-lisp
(is nil :msg "FORMAT-CONTROL~%with no args.")
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     FORMAT-CONTROL
..     with no args.
```

It may be a list whose first element is a constant string, and the
rest are the format arguments to be evaluated:

```common-lisp
(is nil :msg ("Implicit LIST ~A." "form"))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     Implicit LIST form.
```

Or it may be a form that evaluates to a list like `(FORMAT-CONTROL
&REST FORMAT-ARGS)`:

```common-lisp
(is nil :msg (list "Full ~A." "form"))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     Full form.
```

Finally, it may evaluate to NIL, in which case some context specific
default is implied.

- [function] CANONICALIZE-FORMAT-SPECIFIER-FORM FORM

    Ensure that the format specifier form FORM is in its full form.

### Captures

During the evaluation of the FORM argument of IS, evaluation of any
form (e.g. a subform of FORM) may be recorded, which are called
captures.

#### Automatic Captures

IS automatically captures some subforms of FORM that are likely
to be informative. In particular, if FORM is a function call, then
non-constant arguments are automatically captured:

```common-lisp
(is (= 3 (1+ 2) (- 4 3)))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS (= 3 #1=(1+ 2) #2=(- 4 3)))
..   where
..     #1# = 3
..     #2# = 1
```

By default, automatic captures are not made for subforms deeper in
FORM, except for when FORM is a call to NULL,
ENDP and NOT:

```common-lisp
(is (null (find (1+ 1) '(1 2 3))))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS (NULL #1=(FIND #2=(1+ 1) '(1 2 3))))
..   where
..     #2# = 2
..     #1# = 2
```

```common-lisp
(is (endp (member (1+ 1) '(1 2 3))))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS (ENDP #1=(MEMBER #2=(1+ 1) '(1 2 3))))
..   where
..     #2# = 2
..     #1# = (2 3)
```

Note that the argument of NOT is not captured as it is
assumed to be NIL or T. If that's not true, use NULL.

```common-lisp
(is (not (equal (1+ 5) 6)))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS (NOT (EQUAL #1=(1+ 5) 6)))
..   where
..     #1# = 6
```

Other automatic captures are discussed with the relevant
functionality such as MATCH-VALUES.

##### Writing Automatic Capture Rules

- [class] SUB STRUCTURE-OBJECT

    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.

- [function] MAKE-SUB VAR SUBFORM NEW-FORM VALUESP

- [structure-accessor] SUB-VAR

- [structure-accessor] SUB-SUBFORM

- [structure-accessor] SUB-NEW-FORM

- [structure-accessor] SUB-VALUESP

- [generic-function] SUBSTITUTE-IS-LIST-FORM FIRST FORM ENV

    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# = 
          #2# = 


#### Explicit Captures

In addition to automatic captures, which are prescribed by
rewriting rules (see @TRY/WRITING-AUTOMATIC-CAPTURE-RULES),
explicit, ad-hoc captures can also be made.

```common-lisp
(is (let ((x 1))
      (= (capture x) 2)))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS
..      (LET ((X 1))
..        (= (CAPTURE X) 2)))
..   where
..     X = 1
```

If CAPTURE showing up in the form that IS prints is undesirable,
then `%` may be used instead:

```common-lisp
(is (let ((x 1))
      (= (% x) 2)))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS
..      (LET ((X 1))
..        (= X 2)))
..   where
..     X = 1
```

Multiple values may be captured with CAPTURE-VALUES and its
secretive counterpart `%%`:

```common-lisp
(is (= (%% (values 1 2)) 2))
.. debugger invoked on UNEXPECTED-RESULT-FAILURE:
..   UNEXPECTED-FAILURE in check:
..     (IS (= #1=(VALUES 1 2) 2))
..   where
..     #1# == 1
..            2
```

where printing `==` instead of = indicates that this
is a multiple value capture.

- [macro] CAPTURE FORM

    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.

- [macro] CAPTURE-VALUES FORM

    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.

- [macrolet] % FORM

    An alias for CAPTURE in the lexical scope of IS. Removed from the
    IS form when printed.

- [macrolet] %% FORM

    An alias for CAPTURE-VALUES in the lexical scope of IS. Removed
    from the IS form when printed.

## Check Library

In the following, various checks built on top of IS are described.
Many of them share a number of arguments, which are described here.

- ON-RETURN is a boolean that determines whether the check in a
  macro that wraps BODY is made when BODY returns normally.

- ON-NLX is a boolean that determines whether the check in a macro
  that wraps BODY is made when BODY performs a @NON-LOCAL-EXIT.

- MSG and CTX are @TRY/FORMAT-SPECIFIER-FORMS as in IS.

- NAME may be provided so that it is printed (with PRIN1) instead of
  BODY in MSG.


### Checking Conditions

The macros SIGNALS, SIGNALS-NOT, INVOKES-DEBUGGER, and
INVOKES-DEBUGGER-NOT all check whether a condition of a given type,
possibly also matching a predicate, was signalled. In addition to
those already described in @TRY/CHECK-LIBRARY, these macros share a
number of arguments.

Matching conditions are those that are of type CONDITION-TYPE (not
evaluated) and satisfy the predicate PRED.

When PRED is NIL, it always matches. When it is a string, then it
matches if it is a substring of the printed representation of the
condition being handled (by PRINC under WITH-STANDARD-IO-SYNTAX).
When it is a function, it matches if it returns true when called
with the condition as its argument.

The check is performed in the cleanup form of an UNWIND-PROTECT
around BODY.

HANDLER is called when a matching condition is found. It can be a
function, T, or NIL. When it is a function, it is called from the
condition handler (SIGNALS and SIGNALS-NOT) or the debugger
hook (invokes-debugger and INVOKES-DEBUGGER-NOT) with the matching
condition. HANDLER may perform a @NON-LOCAL-EXIT. When HANDLER is T,
the matching condition is handled by performing a non-local exit to
just outside BODY. If the exit completes, BODY is treated as if it
had returned normally, and ON-RETURN is consulted. When HANDLER is
NIL, no addition action is performed when a matching condition is
found.

The default CTX describes the result of the matching process in
terms of *CONDITION-MATCHED-P* and *BEST-MATCHING-CONDITION*.

- [variable] *CONDITION-MATCHED-P*

    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.

- [variable] *BEST-MATCHING-CONDITION*

    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.

- [macro] SIGNALS (CONDITION-TYPE &KEY PRED (HANDLER T) (ON-RETURN T) (ON-NLX T) NAME MSG CTX) &BODY BODY

    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.
    
    ```common-lisp
    (signals (error)
      (error "xxx"))
    => NIL
    ```
    
    The following example shows a failure where CONDITION-TYPE matches
    but PRED does not.
    
    ```common-lisp
    (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".
    ```


- [macro] SIGNALS-NOT (CONDITION-TYPE &KEY PRED (HANDLER T) (ON-RETURN T) (ON-NLX T) NAME MSG CTX) &BODY BODY

    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.

- [macro] INVOKES-DEBUGGER (CONDITION-TYPE &KEY PRED (HANDLER T) (ON-RETURN T) (ON-NLX T) NAME MSG CTX) &BODY BODY

    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.
    
    ```common-lisp
    (invokes-debugger (error :pred "xxx")
      (handler-bind ((error #'invoke-debugger))
        (error "xxx")))
    => NIL
    ```


- [macro] INVOKES-DEBUGGER-NOT (CONDITION-TYPE &KEY PRED (HANDLER T) (ON-RETURN T) (ON-NLX T) NAME MSG CTX) &BODY BODY

    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.

### Miscellaneous Checks

- [macro] FAILS (&KEY NAME MSG CTX) &BODY BODY

    Check that BODY performs a @NON-LOCAL-EXIT 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.
    
    ```common-lisp
    (catch 'foo
      (fails ()
        (throw 'foo 7)))
    => 7
    ```
    
    Next, FAILS signals an UNEXPECTED-FAILURE because BODY returns
    normally.
    
    ```common-lisp
    (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.

- [macro] IN-TIME (SECONDS &KEY (ON-RETURN T) (ON-NLX T) NAME MSG CTX) &BODY BODY

    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.

- [variable] *IN-TIME-ELAPSED-SECONDS*

    Bound to the number of seconds passed during the evaluation of
    BODY when IN-TIME signals its OUTCOME.

### Check Utilities

These utilities are not checks (which signal OUTCOMEs) but simple
functions and macros that may be useful for writing IS checks.

- [macro] ON-VALUES FORM &BODY BODY

    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 `*` 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.
    
    ```common-lisp
    (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 `*` is bound
    to NIL.
    
    ```common-lisp
    (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.
    
    ```common-lisp
    (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 is different, then this function is called to transform the
    list of values. :TRUNCATE is handled before :ON-LENGTH-MISMATCH.
    
    ```common-lisp
    (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, only the first one
    is in effect.

- [macro] MATCH-VALUES FORM &BODY BODY

    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.
    
    ```common-lisp
    ;; 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")))
    ```


- [function] MISMATCH% SEQUENCE1 SEQUENCE2 &KEY FROM-END (TEST #'EQL) (START1 0) END1 (START2 0) END2 KEY MAX-PREFIX-LENGTH MAX-SUFFIX-LENGTH

    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.
    
    ```common-lisp
    (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
    ```
    
    ```common-lisp
    (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
    ```


- [function] DIFFERENT-ELEMENTS SEQUENCE1 SEQUENCE2 &KEY (PRED #'EQL) (MISSING :MISSING)

    Return the different elements under PRED in the given sequences as
    a list of `(:INDEX   )` elements, where `E1` and `E2`
    are elements of SEQUENCE1 and SEQUENCE2 at ``, respectively,
    and they may be MISSING if the corresponding sequence is too short.
    
    ```common-lisp
    (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))
    ```


- [macro] WITH-SHUFFLING NIL &BODY BODY

    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.
    
    ```common-lisp
    (loop repeat 3 do
      (with-shuffling ()
        (prin1 1)
        (prin1 2)))
    .. 122112
    => NIL
    ```


#### Comparing Floats

Float comparisons following
[https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/).

- [function] FLOAT-~= X Y &KEY (MAX-DIFF-IN-VALUE \*MAX-DIFF-IN-VALUE\*) (MAX-DIFF-IN-ULP \*MAX-DIFF-IN-ULP\*)

    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.

- [variable] *MAX-DIFF-IN-VALUE* 1.0e-16

    The default value of the MAX-DIFF-IN-VALUE argument of FLOAT-~=.

- [variable] *MAX-DIFF-IN-ULP* 2

    The default value of the MAX-DIFF-IN-ULP argument of FLOAT-~=.

- [function] FLOAT-~< X Y &KEY (MAX-DIFF-IN-VALUE \*MAX-DIFF-IN-VALUE\*) (MAX-DIFF-IN-ULP \*MAX-DIFF-IN-ULP\*)

    Return whether X is approximately less than Y. Equivalent to `<`,
    but it also allows for approximate equality according to FLOAT-~=.

- [function] FLOAT-~> X Y &KEY (MAX-DIFF-IN-VALUE \*MAX-DIFF-IN-VALUE\*) (MAX-DIFF-IN-ULP \*MAX-DIFF-IN-ULP\*)

    Return whether X is approximately greater than Y. Equivalent to `>`,
    but it also allows for approximate equality according to FLOAT-~=.

## Tests

In Try, tests are Lisp functions that record their execution in
TRIAL objects. TRIALs are to tests what function call traces are to
functions. In more detail, tests

- create a TRIAL object and signal a TRIAL-START event upon entry to
  the function,

- signal a VERDICT condition before returning normally or via a
  @NON-LOCAL-EXIT,

- return the TRIAL object as the first value,

- return explicitly returned values as the second, third, and so on
  values.

See DEFTEST and WITH-TEST for more precise descriptions.

- [macro] DEFTEST NAME LAMBDA-LIST &BODY BODY

    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.
    
    ```common-lisp
    (deftest my-test ()
      (write-string "hey"))
    => MY-TEST
    
    (test-bound-p 'my-test)
    => T
    
    (my-test)
    .. hey
    ==> #
    ```
    
    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
    
    ```common-lisp
    (deftest my-test ()
      (prin1 my-test)
      (return-from my-test (values 2 3)))
    
    (my-test)
    .. #
    ==> #
    => 2
    => 3
    ```


- [variable] *RUN-DEFTEST-WHEN* NIL

    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*.

- [function] TEST-BOUND-P SYMBOL

    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, FMAKUNBOUND, or redefined with DEFUN, then it no longer
    names a global test.

- [macro] WITH-TEST (&OPTIONAL TRIAL-VAR &KEY NAME) &BODY BODY

    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:
    
    ```common-lisp
    (with-test (some-feature :name "obscure feature")
      (prin1 some-feature)
      (is t)
      (return-from some-feature (values 1 2)))
    .. #
    .. obscure feature
    ..   ⋅ (IS T)
    .. ⋅ obscure feature ⋅1
    ..
    ==> #
    => 1
    => 2
    ```
    
    If only TRIAL-VAR is specified:
    
    ```common-lisp
    (with-test (some-feature)
      (prin1 some-feature)
      (is t)
      (return-from some-feature (values 1 2)))
    .. #
    .. SOME-FEATURE
    ..   ⋅ (IS T)
    .. ⋅ SOME-FEATURE ⋅1
    ..
    ==> #
    => 1
    => 2
    ```
    
    If neither is specified:
    
    ```common-lisp
    (with-test ()
      (prin1 (current-trial))
      (is t)
      (return (values 1 2)))
    .. #
    .. NIL
    ..   ⋅ (IS T)
    .. ⋅ NIL ⋅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:
    
    ```common-lisp
    (with-test ("Some feature")
      (prin1 (current-trial))
      (is t)
      (return (values 1 2)))
    .. #
    .. Some feature
    ..   ⋅ (IS T)
    .. ⋅ Some feature ⋅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.

- [function] LIST-PACKAGE-TESTS &OPTIONAL (PACKAGE \*PACKAGE\*)

    List all symbols in PACKAGE that name global tests in the sense of
    TEST-BOUND-P.

- [macro] WITH-TESTS-RUN (TESTS-RUN) &BODY BODY

    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.

- [macro] WARN-ON-TESTS-NOT-RUN (&OPTIONAL (PACKAGE \*PACKAGE\*)) &BODY BODY

    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)))))
    ```


### Calling Test Functions

Tests can be run explicitly by invoking the TRY function or
implicitly by calling a test function:

```common-lisp
(deftest my-test ()
  (is t))

(my-test)
.. MY-TEST
..   ⋅ (IS T)
.. ⋅ MY-TEST ⋅1
..
==> #
```

The situation is similar with a WITH-TEST:

```common-lisp
(with-test (my-test)
  (is t))
.. MY-TEST
..   ⋅ (IS T)
.. ⋅ MY-TEST ⋅1
..
==> #
```

Behind the scenes, the outermost test function calls TRY with

```
(try trial :debug *debug* :collect *collect* :rerun *rerun*
     :print *print* :describe *describe*
     :stream *stream* :printer *printer*)
```

TRY then calls the test function belonging to TRIAL.
The rest of the behaviour is described in @TRY/EXPLICIT-TRY.

- [variable] *DEBUG* (AND UNEXPECTED (NOT NLX) (NOT VERDICT))

    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.

- [variable] *COUNT* LEAF

    Although the default value of *CATEGORIES* lumps RESULTs and
    VERDICTs together, with the default of LEAF, VERDICTs are not
    counted.

- [variable] *COLLECT* UNEXPECTED

    To save memory, only the UNEXPECTED are collected by default.

- [variable] *RERUN* UNEXPECTED

    The default matches that of *COLLECT*.

- [variable] *PRINT* LEAF

    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.

- [variable] *DESCRIBE* (OR UNEXPECTED FAILURE)

    By default, the context (e.g. @TRY/CAPTURES, and the CTX argument
    of is and other checks) of UNEXPECTED events is described.

- [variable] *STREAM* (MAKE-SYNONYM-STREAM '\*DEBUG-IO\*)

- [variable] *PRINTER* TREE-PRINTER

### Explicit TRY

Instead of invoking the test function directly, tests can also be
run by invoking the TRY function.

```common-lisp
(deftest my-test ()
  (is t))

(try 'my-test)
.. MY-TEST
..   ⋅ (IS T)
.. ⋅ MY-TEST ⋅1
..
==> #
```

The situation is similar with a WITH-TEST, only that TRY wraps an
extra TRIAL around the execution of the LAMBDA to ensure that all
EVENTs are signalled within a trial.

```
(try (lambda ()
       (with-test (my-test)
         (is t))))
.. (TRY #)
..   MY-TEST
..     ⋅ (IS T)
..   ⋅ MY-TEST ⋅1
.. ⋅ (TRY #) ⋅1
..
==> #) EXPECTED-SUCCESS 0.000s ⋅1>
```

Invoking tests with an explicit TRY is very similar to just calling
the test functions directly (see @TRY/IMPLICIT-TRY). The differences
are that TRY

- can run @TRY/TESTABLES,

- has a function argument for each of the *DEBUG*, *COLLECT*, etc
  variables.

Those arguments default to *TRY-DEBUG*, *TRY-COLLECT*, etc, which
parallel and default to *DEBUG*, *COLLECT*, etc if set to
:UNSPECIFIED. *TRY-DEBUG* is NIL, the rest of them are :UNSPECIFIED.

These defaults encourage the use of an explicit TRY call in the
non-interactive case and calling the test functions directly in the
interactive one, but this is not enforced in any way.

- [function] TRY TESTABLE &KEY (DEBUG \*TRY-DEBUG\*) (COUNT \*TRY-COUNT\*) (COLLECT \*TRY-COLLECT\*) (RERUN \*TRY-RERUN\*) (PRINT \*TRY-PRINT\*) (DESCRIBE \*TRY-DESCRIBE\*) (STREAM \*TRY-STREAM\*) (PRINTER \*TRY-PRINTER\*)

    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).

- [function] SET-TRY-DEBUG DEBUG

    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*.

- [variable] *TRY-DEBUG* NIL

    The default value for TRY's :DEBUG argument. If
    :UNSPECIFIED, then the value of *DEBUG* is used instead.

- [variable] *TRY-COUNT* :UNSPECIFIED

    The default value for TRY's :COUNT argument. If
    :UNSPECIFIED, then the value of *COUNT* is used instead.

- [variable] *TRY-COLLECT* :UNSPECIFIED

    The default value for TRY's :COLLECT argument. If
    :UNSPECIFIED, then the value of *COLLECT* is used instead.

- [variable] *TRY-RERUN* :UNSPECIFIED

    The default value for TRY's :RERUN argument. If
    :UNSPECIFIED, then the value of *RERUN* is used instead.

- [variable] *TRY-PRINT* :UNSPECIFIED

    The default value for TRY's :PRINT argument. If
    :UNSPECIFIED, then the value of *PRINT* is used instead.

- [variable] *TRY-DESCRIBE* :UNSPECIFIED

    The default value for TRY's :DESCRIBE argument. If
    :UNSPECIFIED, then the value of *DESCRIBE* is used instead.

- [variable] *TRY-STREAM* :UNSPECIFIED

    The default value for TRY's :STREAM argument. If
    :UNSPECIFIED, then the value of *STREAM* is used instead.

- [variable] *TRY-PRINTER* :UNSPECIFIED

    The default value for TRY's :PRINTER argument. If
    :UNSPECIFIED, then the value of *PRINTER* is used instead.

- [variable] *N-RECENT-TRIALS* 3

    See *RECENT-TRIALS*.

- [function] RECENT-TRIAL &OPTIONAL (N 0)

    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.

- [variable] ! NIL

    The most recent trial. Equivalent to `(RECENT-TRIAL 0)`.

- [variable] !! NIL

    Equivalent to `(RECENT-TRIAL 1)`.

- [variable] !!! NIL

    Equivalent to `(RECENT-TRIAL 2)`.

#### Testables

Valid first arguments to TRY are called testables. A testable may
be:

- a @FUNCTION-DESIGNATOR

    - the name of a global test

    - the name of a global function

    - a function object

    - a trial

- a list of testables

- a PACKAGE

In the function designator cases, TRY calls the designated function.
TRIALs, being @FUNCALLABLE-INSTANCEs, designate themselves. If the
trial is not RUNNINGP, then it will be rerun (see @TRY/RERUN). Don't
invoke TRY with RUNNINGP trials (but see
@TRY/IMPLICIT-TRY-IMPLEMENTATION for discussion).

When given a list of testables, TRY calls each testable one by one.

Finally, a PACKAGE stands for the result of calling
LIST-PACKAGE-TESTS on that package.

#### Implementation of Implicit TRY

What's happening in the implementation is that a test function,
when it is called, checks whether it is running under the TRY
function. If it isn't, then it invokes TRY with its TRIAL. TRY
realizes the trial cannot be rerun yet (see @TRY/RERUN) because it
is RUNNINGP, sets up its event handlers for debugging, collecting,
printing, and invokes the trial as if it were rerun but without
skipping anything based on the RERUN argument. Thus the following
are infinite recursions:

```
(with-test (recurse)
  (try recurse))

(with-test (recurse)
  (funcall recurse))
```


### Printing Events

TRY instantiates a printer of the type given by its PRINTER
argument. All EVENTs recorded by TRY are sent to this printer. The
printer then prints events that match the type given by the PRINT
argument of TRY. Events that also match the DESCRIBE argument of TRY
are printed with context information (see IS) and backtraces (see
UNHANDLED-ERROR).

Although the printing is primarily customized with global special
variables, changing the value of those variables after the printer
object is instantiated by TRY has no effect. This is to ensure
consistent output with nested TRY calls of differing printer
setups.

- [class] TREE-PRINTER

    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.
    
    ```common-lisp
    (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
    ..
    ==> #
    ```
    
    The `⊟3 ⊠1 ⊡1 -1 ×1 ⋅1` part is the counts for *CATEGORIES* printed
    with their markers.

- [variable] *PRINT-PARENT* T

    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.
    
    ```common-lisp
    (let ((*print* 'leaf)
          (*print-parent* t))
      (with-test (t0)
        (is t)
        (is t)))
    .. T0
    ..   ⋅ (IS T)
    ..   ⋅ (IS T)
    .. ⋅ T0 ⋅2
    ..
    ==> #
    ```
    
    ```common-lisp
    (let ((*print* 'leaf)
          (*print-parent* nil))
      (with-test (t0)
        (is t)
        (is t)))
    .. ⋅ (IS T)
    .. ⋅ (IS T)
    ..
    ==> #
    ```
    
    *PRINT-PARENT* NIL combined with printing VERDICTs results in a flat
     output:
    
    ```common-lisp
    (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
    ..
    ==> #
    ```


- [variable] *PRINT-INDENTATION* 2

    The number of spaces each printed TRIAL increases the indentation
    of its children.

- [variable] *PRINT-DURATION* NIL

    If true, the number of seconds spent during execution is printed.
    
    ```common-lisp
    (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
    ..
    ==> #
    ```
    
    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.

- [variable] *PRINT-COMPACTLY* NIL

    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 `=>
    ` (see *CATEGORIES*).
    
    ```common-lisp
    (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
    ..
    ==> #
    ```
    
    *PRINT-COMPACTLY* has no effect on events being `DESCRIBE`d.

- [variable] *DEFER-DESCRIBE* NIL

    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.
    
    ```common-lisp
    (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
    ..
    ==> #
    ```


### Counting Events

TRIALs have a counter for each category in *CATEGORIES*. When an
EVENT is recorded by TRY and its type matches *COUNT*, the counters
of all categories matching the event type are incremented in the
CURRENT-TRIAL. When a trial finishes and a VERDICT is recorded, the
trial's event counters are added to that of its parent's (if any).
The counts are printed with VERDICTs (see @TRY/PRINT).

If both *COUNT* and *CATEGORIES* are unchanged from the their
default values, then only LEAF events are counted, and we get
separate counters for ABORT\*, UNEXPECTED-FAILURE,
UNEXPECTED-SUCCESS, SKIP, EXPECTED-FAILURE, and EXPECTED-SUCCESS.

```common-lisp
(let ((*debug* nil))
  (with-test (outer)
    (with-test (inner)
      (is t))
    (is t)
    (is nil)))
.. OUTER
..   INNER
..     ⋅ (IS T)
..   ⋅ INNER ⋅1
..   ⋅ (IS T)
..   ⊠ (IS NIL)
.. ⊠ OUTER ⊠1 ⋅2
..
==> #
```

As the above example shows, EXPECTED-VERDICT-SUCCESS and
EXPECTED-RESULT-SUCCESS are both marked with `"⋅"`, but only
EXPECTED-RESULT-SUCCESS is counted due to *COUNT* being LEAF.

### Collecting Events

When an EVENT is recorded and the type of the EVENT matches the
COLLECT type argument of TRY, then a corresponding object is pushed
onto CHILDREN of the CURRENT-TRIAL for subsequent @TRY/RERUN or
@TRY/REPLAY.

In particular, if the matching event is a LEAF, then the event
itself is collected. If the matching event is a TRIAL-EVENT, then
its TRIAL is collected. Furthermore, trials
which collected anything are always collected by their parent.

By default, both implicit and explicit calls to TRY collect the
UNEXPECTED (see *COLLECT* and *TRY-COLLECT*), and consequently all
the enclosing trials.

- [reader] CHILDREN TRIAL (:CHILDREN = NIL)

    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.

### Rerunning Trials

When a TRIAL is `FUNCALL`ed or passed to TRY, the same tests that
instantiated TRIAL are executed.

- If the trial was created by calling a DEFTEST function, then the
  test currently associated with that symbol naming the function is
  called with the arguments of the original function call. If the
  symbol is no longer FBOUNDP (because it was FMAKUNBOUND) or it no
  longer names a DEFTEST (it was redefined with DEFUN), then an
  error is signalled.

- If the trial was created by entering a WITH-TEST form, then its
  body is executed again in the original lexical but the current
  dynamic environment. Implementationally speaking, WITH-TEST
  defines a local function of no arguments (likely a closure) that
  wraps its body, stores the closure in the trial object and calls
  it on a rerun in a WITH-TEST of the same TRIAL-VAR and same NAME.

- If the trial was created by TRY itself to ensure that all events
  are signalled in a trial (see @TRY/EXPLICIT-TRY), then on a rerun
  the same TESTABLE is run again.

All three possibilities involve entering DEFTEST or WITH-TEST, or
invoking TRY: the same cases that we have when calling tests
functions (see @TRY/IMPLICIT-TRY). Thus even if a trial is rerun
with FUNCALL, execution is guaranteed to happen under an TRY, so we
can talk about its RERUN parameter.

As the test functions are being rerun, some trials are automatically
skipped. When that happens the corresponding function call
immediately returns the TRIAL object. A new trial is skipped if

- among the collected but not yet rerun trials in the trial being
  rerun, there is no trial representing the same function call, or

- the first such trial does not match the RERUN type argument of TRY
  in that neither its TRIAL-START, VERDICT events match the type
  RERUN, nor do any of its collected RESULTs and trials.


### Reprocessing Trials

- [function] REPLAY-EVENTS TRIAL &KEY (COLLECT \*TRY-COLLECT\*) (PRINT \*TRY-PRINT\*) (DESCRIBE \*TRY-DESCRIBE\*) (STREAM \*TRY-STREAM\*) (PRINTER \*TRY-PRINTER\*)

    REPLAY-EVENTS reprocesses the events collected (see @TRY/COLLECT)
    in TRIAL. It takes the same arguments as TRY except
    DEBUG, COUNT 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)
    ```


## Implementation Notes

Try is supported on ABCL, AllegroCL, CLISP, CCL, CMUCL, ECL and
SBCL.

- Pretty printing is non-existent on CLISP and broken on ABCL. The
  output may look garbled on them.

- Gray streams are broken on ABCL so the output may look even worse
  [https://abcl.org/trac/ticket/373](https://abcl.org/trac/ticket/373).

- ABCL, CMUCL, and ECL have a bug related to losing
  EQLness of source literals
  [https://gitlab.com/embeddable-common-lisp/ecl/-/issues/665](https://gitlab.com/embeddable-common-lisp/ecl/-/issues/665).
  The result is somewhat cosmetic, it may cause multiple captures
  being made for the same thing.


## Glossary

- [glossary-term] function designator

    This is a term from the Common Lisp ANSI standard. A function
    designator is a symbol (denoting the function named by that symbol
    in the global environment), or a function (denoting itself).

- [glossary-term] funcallable instance

    This is a term from the MOP. A funcallable instance is an instance
    of a class that's a subclass of `MOP:FUNCALLABLE-STANDARD-CLASS`. It
    is like a normal instance, but it can also be `FUNCALL`ed.

- [glossary-term] non-local exit

    This is a term from the Common Lisp ANSI standard. If a form does
    not return normally, but control is transferred via `GO`, RETURN,
    RETURN-FROM or THROW, then it is said to have performed a non-local
    exit.

- [glossary-term] cancelled non-local exit

    This is a term from the Common Lisp ANSI standard. If during the
    unwinding of the stack initiated by a @NON-LOCAL-EXIT another nlx is
    initiated in, and exits from an UNWIND-PROTECT cleanup form, then
    this second nlx is said to have cancelled the first, and the first
    nlx will not continue.
    
    ```common-lisp
    (catch 'foo
      (catch 'bar
        (unwind-protect
             (throw 'foo 'foo)
          (throw 'bar 'bar))))
    => BAR
    ```


* * *
###### \[generated by [MGL-PAX](https://github.com/melisgl/mgl-pax)\]


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Next: , Previous: , Up: Systems   [Contents][Index]

2.1 try

Author

Gábor Melis

Contact

mega@retes.hu

Home Page

http://melisgl.github.io/try

Source Control

(:git "https://github.com/melisgl/try.git")

Bug Tracker

https://github.com/melisgl/try/issues

License

MIT, see COPYING.

Description

Try is a test framework.

Long Description

Try is what we get if we make tests functions and
build a test framework on top of the condition system as [Stefil](https://common-lisp.net/project/stefil/index-old.shtml) did but also address the issue of rerunning and replaying, make the IS check more capable, use the types of the condition hierarchy to parameterize what to debug, print, rerun, and finally document the whole thing.

Version

0.0.1

Defsystem Dependency

try.asdf (system)

Dependencies
Source

try.asd (file)

Components

Previous: , Up: Systems   [Contents][Index]

2.2 try.asdf

Source

try.asdf.asd (file)

Component

asdf.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 try.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/try-20220331-git/try.asd

Systems

try (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 try.asdf.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/try-20220331-git/try.asdf.asd

Systems

try.asdf (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 try/package.lisp

Parent

try (system)

Location

package.lisp

Packages

try


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 try/util.lisp

Dependency

package.lisp (file)

Parent

try (system)

Location

util.lisp

Exported Definitions

on-values (macro)

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 try/gray-stream.lisp

Dependency

util.lisp (file)

Parent

try (system)

Location

gray-stream.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.6 try/early.lisp

Dependency

gray-stream.lisp (file)

Parent

try (system)

Location

early.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.7 try/debug.lisp

Dependency

early.lisp (file)

Parent

try (system)

Location

debug.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.8 try/events.lisp

Dependency

debug.lisp (file)

Parent

try (system)

Location

events.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.9 try/outcome.lisp

Dependency

events.lisp (file)

Parent

try (system)

Location

outcome.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.10 try/result.lisp

Dependency

outcome.lisp (file)

Parent

try (system)

Location

result.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.11 try/is.lisp

Dependency

result.lisp (file)

Parent

try (system)

Location

is.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.12 try/checks.lisp

Dependency

is.lisp (file)

Parent

try (system)

Location

checks.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.13 try/floats.lisp

Dependency

checks.lisp (file)

Parent

try (system)

Location

floats.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.14 try/trial-event.lisp

Dependency

floats.lisp (file)

Parent

try (system)

Location

trial-event.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.15 try/error.lisp

Dependency

trial-event.lisp (file)

Parent

try (system)

Location

error.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.16 try/count.lisp

Dependency

error.lisp (file)

Parent

try (system)

Location

count.lisp

Exported Definitions

@try/count (special variable)

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.17 try/trial.lisp

Dependency

count.lisp (file)

Parent

try (system)

Location

trial.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.18 try/test.lisp

Dependency

trial.lisp (file)

Parent

try (system)

Location

test.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.19 try/testable.lisp

Dependency

test.lisp (file)

Parent

try (system)

Location

testable.lisp

Exported Definitions

@try/testables (special variable)

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.20 try/rerun.lisp

Dependency

testable.lisp (file)

Parent

try (system)

Location

rerun.lisp

Exported Definitions

@try/rerun (special variable)

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.21 try/print.lisp

Dependency

rerun.lisp (file)

Parent

try (system)

Location

print.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.22 try/collect.lisp

Dependency

print.lisp (file)

Parent

try (system)

Location

collect.lisp

Exported Definitions

@try/collect (special variable)

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.23 try/try.lisp

Dependency

collect.lisp (file)

Parent

try (system)

Location

try.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.24 try/replay.lisp

Dependency

try.lisp (file)

Parent

try (system)

Location

replay.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.25 try/manual.lisp

Dependency

replay.lisp (file)

Parent

try (system)

Location

manual.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.26 try.asdf/asdf.lisp

Parent

try.asdf (system)

Location

asdf.lisp

Packages

try/asdf

Exported Definitions

compile-wrapper (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 try

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

4.2 try/asdf

Source

asdf.lisp (file)

Use List

common-lisp

Exported Definitions

compile-wrapper (function)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: !

The most recent trial. Equivalent to ‘(RECENT-TRIAL 0)‘.

Package

try

Source

try.lisp (file)

Special Variable: !!

Equivalent to ‘(RECENT-TRIAL 1)‘.

Package

try

Source

try.lisp (file)

Special Variable: !!!

Equivalent to ‘(RECENT-TRIAL 2)‘.

Package

try

Source

try.lisp (file)

Special Variable: *best-matching-condition*

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.

Package

try

Source

checks.lisp (file)

Special Variable: *categories*

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.

Package

try

Source

events.lisp (file)

Special Variable: *collect*

To save memory, only the UNEXPECTED are collected by default.

Package

try

Source

try.lisp (file)

Special Variable: *condition-matched-p*

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.

Package

try

Source

checks.lisp (file)

Special Variable: *count*

Although the default value of *CATEGORIES* lumps RESULTs and VERDICTs together, with the default of LEAF, VERDICTs are not counted.

Package

try

Source

try.lisp (file)

Special Variable: *debug*

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.

Package

try

Source

try.lisp (file)

Special Variable: *defer-describe*

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> “‘

Package

try

Source

print.lisp (file)

Special Variable: *describe*

By default, the context (e.g. @TRY/CAPTURES, and the CTX argument of is and other checks) of UNEXPECTED events is described.

Package

try

Source

try.lisp (file)

Special Variable: *event-print-bindings*

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.

Package

try

Source

events.lisp (file)

Special Variable: *gather-backtrace*

Capturing the backtrace can be expensive. *GATHER-BACKTRACE* controls whether UNHANDLED-ERRORs shall have their BACKTRACE-OF populated.

Package

try

Source

error.lisp (file)

Special Variable: *in-time-elapsed-seconds*

Bound to the number of seconds passed during the evaluation of BODY when IN-TIME signals its OUTCOME.

Package

try

Source

checks.lisp (file)

Special Variable: *is-captures*

Captures made during an IS evaluation are made available for CTX via *IS-CAPTURES*.

Package

try

Source

is.lisp (file)

Special Variable: *is-form*

IS binds this to its FORM argument for CTX and MSG.

Package

try

Source

is.lisp (file)

Special Variable: *max-diff-in-ulp*

The default value of the MAX-DIFF-IN-ULP argument of FLOAT-~=.

Package

try

Source

floats.lisp (file)

Special Variable: *max-diff-in-value*

The default value of the MAX-DIFF-IN-VALUE argument of FLOAT-~=.

Package

try

Source

floats.lisp (file)

Special Variable: *n-recent-trials*

See *RECENT-TRIALS*.

Package

try

Source

try.lisp (file)

Special Variable: *print*

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.

Package

try

Source

try.lisp (file)

Special Variable: *print-compactly*

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.

Package

try

Source

print.lisp (file)

Special Variable: *print-duration*

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.

Package

try

Source

print.lisp (file)

Special Variable: *print-indentation*

The number of spaces each printed TRIAL increases the indentation of its children.

Package

try

Source

print.lisp (file)

Special Variable: *print-parent*

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> “‘

Package

try

Source

print.lisp (file)

Special Variable: *printer*
Package

try

Source

try.lisp (file)

Special Variable: *rerun*

The default matches that of *COLLECT*.

Package

try

Source

try.lisp (file)

Special Variable: *run-deftest-when*

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*.

Package

try

Source

test.lisp (file)

Special Variable: *stream*
Package

try

Source

try.lisp (file)

Special Variable: *try-collect*

The default value for TRY’s :COLLECT argument. If :UNSPECIFIED, then the value of *COLLECT* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: *try-count*

The default value for TRY’s :COUNT argument. If :UNSPECIFIED, then the value of *COUNT* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: *try-debug*

The default value for TRY’s :DEBUG argument. If :UNSPECIFIED, then the value of *DEBUG* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: *try-describe*

The default value for TRY’s :DESCRIBE argument. If :UNSPECIFIED, then the value of *DESCRIBE* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: *try-print*

The default value for TRY’s :PRINT argument. If :UNSPECIFIED, then the value of *PRINT* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: *try-printer*

The default value for TRY’s :PRINTER argument. If :UNSPECIFIED, then the value of *PRINTER* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: *try-rerun*

The default value for TRY’s :RERUN argument. If :UNSPECIFIED, then the value of *RERUN* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: *try-stream*

The default value for TRY’s :STREAM argument. If :UNSPECIFIED, then the value of *STREAM* is used instead.

Package

try

Source

try.lisp (file)

Special Variable: @try-manual
Package

try

Source

manual.lisp (file)

Special Variable: @try/automatic-captures
Package

try

Source

is.lisp (file)

Special Variable: @try/captures
Package

try

Source

is.lisp (file)

Special Variable: @try/categories
Package

try

Source

events.lisp (file)

Special Variable: @try/check-library
Package

try

Source

checks.lisp (file)

Special Variable: @try/check-restarts
Package

try

Source

outcome.lisp (file)

Special Variable: @try/check-utilities
Package

try

Source

checks.lisp (file)

Special Variable: @try/checking-conditions
Package

try

Source

checks.lisp (file)

Special Variable: @try/checks
Package

try

Source

outcome.lisp (file)

Special Variable: @try/collect
Package

try

Source

collect.lisp (file)

Special Variable: @try/comparing-floats
Package

try

Source

floats.lisp (file)

Special Variable: @try/concrete-events
Package

try

Source

events.lisp (file)

Special Variable: @try/count
Package

try

Source

count.lisp (file)

Special Variable: @try/errors
Package

try

Source

error.lisp (file)

Special Variable: @try/event-glue
Package

try

Source

events.lisp (file)

Special Variable: @try/event-restarts
Package

try

Source

events.lisp (file)

Special Variable: @try/events
Package

try

Source

events.lisp (file)

Special Variable: @try/explicit-captures
Package

try

Source

is.lisp (file)

Special Variable: @try/explicit-try
Package

try

Source

try.lisp (file)

Special Variable: @try/format-specifier-forms
Package

try

Source

is.lisp (file)

Special Variable: @try/glossary
Package

try

Source

manual.lisp (file)

Special Variable: @try/implementation-notes
Package

try

Source

manual.lisp (file)

Special Variable: @try/implicit-try
Package

try

Source

try.lisp (file)

Special Variable: @try/implicit-try-implementation
Package

try

Source

try.lisp (file)

Special Variable: @try/is
Package

try

Source

is.lisp (file)

Package

try

Source

manual.lisp (file)

Special Variable: @try/middle-layer-of-events
Package

try

Source

events.lisp (file)

Special Variable: @try/misc-checks
Package

try

Source

checks.lisp (file)

Special Variable: @try/outcome-restarts
Package

try

Source

outcome.lisp (file)

Special Variable: @try/outcomes
Package

try

Source

outcome.lisp (file)

Special Variable: @try/print
Package

try

Source

print.lisp (file)

Special Variable: @try/printing-events
Package

try

Source

events.lisp (file)

Special Variable: @try/replay
Package

try

Source

replay.lisp (file)

Special Variable: @try/rerun
Package

try

Source

rerun.lisp (file)

Special Variable: @try/testables
Package

try

Source

testable.lisp (file)

Special Variable: @try/tests
Package

try

Source

test.lisp (file)

Special Variable: @try/trial-events
Package

try

Source

trial-event.lisp (file)

Special Variable: @try/trial-restarts
Package

try

Source

trial.lisp (file)

Special Variable: @try/trial-verdicts
Package

try

Source

trial.lisp (file)

Special Variable: @try/trials
Package

try

Source

trial.lisp (file)

Special Variable: @try/tutorial
Package

try

Source

manual.lisp (file)

Special Variable: @try/writing-automatic-capture-rules
Package

try

Source

is.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: capture FORM

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.

Package

try

Source

is.lisp (file)

Macro: capture-values FORM

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.

Package

try

Source

is.lisp (file)

Macro: deftest NAME LAMBDA-LIST &body BODY

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
“‘

Package

try

Source

test.lisp (file)

Macro: fails (&key NAME MSG CTX) &body BODY

Check that BODY performs a @NON-LOCAL-EXIT 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.

Package

try

Source

checks.lisp (file)

Macro: in-time (SECONDS &key ON-RETURN ON-NLX NAME MSG CTX) &body BODY

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.

Package

try

Source

checks.lisp (file)

Macro: invokes-debugger (CONDITION-TYPE &key PRED HANDLER ON-RETURN ON-NLX NAME MSG CTX) &body BODY

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
“‘

Package

try

Source

checks.lisp (file)

Macro: invokes-debugger-not (CONDITION-TYPE &key PRED HANDLER ON-RETURN ON-NLX NAME MSG CTX) &body BODY

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.

Package

try

Source

checks.lisp (file)

Macro: is FORM &key MSG CTX CAPTURE PRINT-CAPTURES RETRY

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.

Package

try

Source

is.lisp (file)

Macro: match-values FORM &body BODY

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")))
“‘

Package

try

Source

checks.lisp (file)

Macro: on-values FORM &body BODY

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 is 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, only the first one is in effect.

Package

try

Source

util.lisp (file)

Macro: signals (CONDITION-TYPE &key PRED HANDLER ON-RETURN ON-NLX NAME MSG CTX) &body BODY

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".
“‘

Package

try

Source

checks.lisp (file)

Macro: signals-not (CONDITION-TYPE &key PRED HANDLER ON-RETURN ON-NLX NAME MSG CTX) &body BODY

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.

Package

try

Source

checks.lisp (file)

Macro: warn-on-tests-not-run (&optional PACKAGE) &body BODY

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)))))
“‘

Package

try

Source

test.lisp (file)

Macro: with-expected-outcome (EXPECTED-TYPE) &body BODY

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>
“‘

Package

try

Source

outcome.lisp (file)

Macro: with-failure-expected (&optional RESULT-EXPECTED-TYPE VERDICT-EXPECTED-TYPE) &body BODY

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 ‘SUCCESS‘es and FAILUREs EXPECTED. ‘(WITH-FAILURE-EXPECTED (’FAILURE) ..)‘ expects FAILUREs only, and any ‘SUCCESS‘es will be UNEXPECTED.

Package

try

Source

outcome.lisp (file)

Macro: with-shuffling () &body BODY

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
“‘

Package

try

Source

checks.lisp (file)

Macro: with-skip (&optional SKIP) &body BODY

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.

Package

try

Source

outcome.lisp (file)

Macro: with-test (&optional TRIAL-VAR &key NAME) &body BODY

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.

Package

try

Source

test.lisp (file)

Macro: with-tests-run (TESTS-RUN) &body BODY

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.

Package

try

Source

test.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: abort-check &optional CONDITION

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.

Package

try

Source

outcome.lisp (file)

Function: abort-trial &optional CONDITION TRIAL

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 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.

Package

try

Source

trial.lisp (file)

Function: ascii-std-categories ()

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 "."))
“‘

Package

try

Source

events.lisp (file)

Function: canonicalize-format-specifier-form FORM

Ensure that the format specifier form FORM is in its full form.

Package

try

Source

is.lisp (file)

Function: compile-wrapper CONTINUATION
Package

try/asdf

Source

asdf.lisp (file)

Function: current-trial ()

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.

Package

try

Source

trial.lisp (file)

Function: different-elements SEQUENCE1 SEQUENCE2 &key PRED MISSING

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))
“‘

Package

try

Source

checks.lisp (file)

Function: failedp TRIAL

See if TRIAL has finished and its [VERDICT][(reader trial)] is a FAIL.

Package

try

Source

trial.lisp (file)

Function: fancy-std-categories ()

Returns the default value of *CATEGORIES* (see @TRY/CATEGORIES), which contains some fancy Unicode characters.

Package

try

Source

events.lisp (file)

Function: float-~< X Y &key MAX-DIFF-IN-VALUE MAX-DIFF-IN-ULP

Return whether X is approximately less than Y. Equivalent to ‘<‘, but it also allows for approximate equality according to FLOAT-~=.

Package

try

Source

floats.lisp (file)

Function: float-~= X Y &key MAX-DIFF-IN-VALUE MAX-DIFF-IN-ULP

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.

Package

try

Source

floats.lisp (file)

Function: float-~> X Y &key MAX-DIFF-IN-VALUE MAX-DIFF-IN-ULP

Return whether X is approximately greater than Y. Equivalent to ‘>‘, but it also allows for approximate equality according to FLOAT-~=.

Package

try

Source

floats.lisp (file)

Function: force-expected-failure &optional CONDITION

Change the type of OUTCOME being signalled to EXPECTED and FAILURE.

Package

try

Source

outcome.lisp (file)

Function: force-expected-success &optional CONDITION

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.

Package

try

Source

outcome.lisp (file)

Function: force-unexpected-failure &optional CONDITION

Change the type of OUTCOME being signalled to UNEXPECTED and FAILURE.

Package

try

Source

outcome.lisp (file)

Function: force-unexpected-success &optional CONDITION

Change the type of OUTCOME being signalled to UNEXPECTED and SUCCESS.

Package

try

Source

outcome.lisp (file)

Function: list-package-tests &optional PACKAGE

List all symbols in PACKAGE that name global tests in the sense of TEST-BOUND-P.

Package

try

Source

test.lisp (file)

Function: make-sub VAR SUBFORM NEW-FORM VALUESP
Package

try

Source

is.lisp (file)

Function: mismatch% SEQUENCE1 SEQUENCE2 &key FROM-END TEST START1 END1 START2 END2 KEY MAX-PREFIX-LENGTH MAX-SUFFIX-LENGTH

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
“‘

Package

try

Source

checks.lisp (file)

Function: passedp TRIAL

See if TRIAL has finished and its [VERDICT][(reader trial)] is a PASS.

Package

try

Source

trial.lisp (file)

Function: recent-trial &optional N

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.

Package

try

Source

try.lisp (file)

Function: record-event &optional CONDITION

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.

Package

try

Source

events.lisp (file)

Function: replay-events TRIAL &key COLLECT PRINT DESCRIBE STREAM PRINTER

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)
“‘

Package

try

Source

replay.lisp (file)

Function: retry-check &optional CONDITION

Initiate a @NON-LOCAL-EXIT to go reevaluate the forms wrapped by the check without signalling an OUTCOME.

Package

try

Source

outcome.lisp (file)

Function: retry-trial &optional CONDITION TRIAL

Invoke the RETRY-TRIAL restart of RUNNINGP TRIAL. The RETRY-TRIAL restart may record CONDITION, then it initiates a @NON-LOCAL-EXIT 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.

Package

try

Source

trial.lisp (file)

Function: runningp TRIAL

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.

Package

try

Source

trial.lisp (file)

Function: set-try-debug DEBUG

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*.

Package

try

Source

try.lisp (file)

Function: skip-check &optional CONDITION

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.

Package

try

Source

outcome.lisp (file)

Function: skip-trial &optional CONDITION TRIAL

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 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
..
“‘

Package

try

Source

trial.lisp (file)

Function: sub-new-form INSTANCE
Function: (setf sub-new-form) VALUE INSTANCE
Package

try

Source

is.lisp (file)

Function: sub-subform INSTANCE
Function: (setf sub-subform) VALUE INSTANCE
Package

try

Source

is.lisp (file)

Function: sub-valuesp INSTANCE
Function: (setf sub-valuesp) VALUE INSTANCE
Package

try

Source

is.lisp (file)

Function: sub-var INSTANCE
Function: (setf sub-var) VALUE INSTANCE
Package

try

Source

is.lisp (file)

Function: test-bound-p SYMBOL

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, FMAKUNBOUND, or redefined with DEFUN, then it no longer names a global test.

Package

try

Source

test.lisp (file)

Function: try TESTABLE &key DEBUG COUNT COLLECT RERUN PRINT DESCRIBE STREAM PRINTER

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).

Package

try

Source

try.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Generic functions

Generic Function: backtrace-of CONDITION
Package

try

Methods
Method: backtrace-of (CONDITION unhandled-error)
Source

error.lisp (file)

Generic Function: children OBJECT
Package

try

Methods
Method: children (TRIAL trial)

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.

Source

trial.lisp (file)

Generic Function: debugger-invoked-p CONDITION
Package

try

Methods
Method: debugger-invoked-p (CONDITION unhandled-error)
Source

error.lisp (file)

Generic Function: n-retries OBJECT
Package

try

Methods
Method: n-retries (TRIAL trial)

The number of times this [TRIAL][dislocated] has been retried. See RETRY-TRIAL.

Source

trial.lisp (file)

Generic Function: nested-condition CONDITION
Package

try

Methods
Method: nested-condition (CONDITION unhandled-error)
Source

error.lisp (file)

Generic Function: substitute-is-list-form FIRST FORM ENV

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>

Package

try

Source

is.lisp (file)

Methods
Method: substitute-is-list-form (FIRST (eql match-values)) FORM ENV
Source

checks.lisp (file)

Method: substitute-is-list-form (FIRST (eql not)) FORM ENV
Method: substitute-is-list-form (FIRST (eql endp)) FORM ENV
Method: substitute-is-list-form (FIRST (eql null)) FORM ENV
Method: substitute-is-list-form FIRST FORM ENV
Generic Function: test-name CONDITION
Package

try

Methods
Method: test-name (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Method: test-name (CONDITION error*)
Source

error.lisp (file)

Generic Function: trial CONDITION
Package

try

Methods
Method: trial (CONDITION trial-event)
Source

trial-event.lisp (file)

Generic Function: trial-start OBJECT
Package

try

Methods
Method: trial-start (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: verdict OBJECT
Package

try

Methods
Method: verdict (TRIAL trial)

The [VERDICT][condition] EVENT signalled when this [TRIAL][dislocated] finished or NIL if it has not finished yet.

Source

trial.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 Conditions

Condition: abort* ()

‘RESULT-ABORT*‘, ‘VERDICT-ABORT*‘ or ERROR*.

Package

try

Source

events.lisp (file)

Direct superclasses

unexpected (condition)

Direct subclasses
Condition: dismissal ()

The third possibility after SUCCESS and FAILURE. Either SKIP or ABORT*.

Package

try

Source

events.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Condition: error* ()

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.

Package

try

Source

error.lisp (file)

Direct superclasses
Direct subclasses
Direct methods

test-name (method)

Direct slots
Slot: test-name
Initargs

:test-name

Readers

test-name (generic function)

Condition: event ()

Common abstract superclass of all events in Try.

Package

try

Source

events.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses
Direct methods

print-object (method)

Condition: expected ()

Concrete condition classes with EXPECTED in their
name are subclasses of EXPECTED. SKIP is also a subclass of EXPECTED.

Package

try

Source

events.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Condition: expected-result-failure ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: expected-result-success ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: expected-verdict-failure ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses
Condition: expected-verdict-success ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses
Condition: failure ()

See SUCCESS.

Package

try

Source

events.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Condition: leaf ()

RESULT or ERROR*.

Package

try

Source

events.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Direct methods

print-event (method)

Condition: nlx ()

Representing a @NON-LOCAL-EXIT 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.

Package

try

Source

error.lisp (file)

Direct superclasses

error* (condition)

Direct methods
Direct slots
Slot: extra-message
Initargs

:extra-message

Readers

extra-message (generic function)

Condition: outcome ()

An OUTCOME is the resolution of either a TRIAL or a
check (see @TRY/CHECKS), corresponding to subclasses VERDICT and RESULT.

Package

try

Source

outcome.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Condition: result ()
Package

try

Source

result.lisp (file)

Direct superclasses
Direct subclasses
Direct methods
Direct slots
Slot: check
Initargs

:check

Readers

check (generic function)

Slot: elapsed-seconds
Initargs

:elapsed-seconds

Initform

(quote nil)

Readers

elapsed-seconds (generic function)

Slot: msg
Initargs

:msg

Initform

(quote nil)

Readers

msg (generic function)

Slot: ctx
Initargs

:ctx

Initform

(quote nil)

Readers

ctx (generic function)

Slot: captures
Initargs

:captures

Initform

(quote nil)

Readers

captures (generic function)

Slot: print-captures
Initargs

:print-captures

Initform

(quote t)

Readers

print-captures (generic function)

Slot: print-form-memoization-data
Initform

(quote nil)

Readers

print-form-memoization-data (generic function)

Writers

(setf print-form-memoization-data) (generic function)

Condition: result-abort* ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: result-skip ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: skip ()

RESULT-SKIP or VERDICT-SKIP.

Package

try

Source

outcome.lisp (file)

Direct superclasses
Direct subclasses
Condition: success ()

See @TRY/CHECKS and @TRY/TRIAL-VERDICTS for how SUCCESS or FAILURE is decided.

Package

try

Source

events.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Condition: trial-event ()

A TRIAL-EVENT is either a TRIAL-START or a VERDICT.

Package

try

Source

trial-event.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Direct methods

trial (method)

Direct slots
Slot: trial

The TRIAL object associated with this event.

Initargs

:trial

Readers

trial (generic function)

Condition: trial-start ()

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.

Package

try

Source

trial-event.lisp (file)

Direct superclasses

trial-event (condition)

Direct methods
Condition: unexpected ()

Concrete condition classes with UNEXPECTED in their
name are subclasses of UNEXPECTED. ABORT* is also a subclass of UNEXPECTED.

Package

try

Source

events.lisp (file)

Direct superclasses

event (condition)

Direct subclasses
Condition: unexpected-result-failure ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: unexpected-result-success ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: unexpected-verdict-failure ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses
Condition: unexpected-verdict-success ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses
Condition: unhandled-error ()

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.

Package

try

Source

error.lisp (file)

Direct superclasses

error* (condition)

Direct methods
Direct slots
Slot: nested-condition

The unhandled condition.

Initargs

:condition

Initform

(quote nil)

Readers

nested-condition (generic function)

Slot: backtrace

A string if *GATHER-BACKTRACE* was true when this event was signalled, NIL otherwise.

Initargs

:backtrace

Initform

(quote nil)

Readers

backtrace-of (generic function)

Slot: debugger-invoked-p

True if NESTED-CONDITION was caught by a trial’s *DEBUGGER-HOOK*, NIL if it was caught by its ERROR handler.

Initargs

:debugger-invoked-p

Initform

(quote nil)

Readers

debugger-invoked-p (generic function)

Condition: verdict ()

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> “‘

Package

try

Source

trial-event.lisp (file)

Direct superclasses
Direct subclasses
Direct methods
Direct slots
Slot: elapsed-seconds
Initargs

:elapsed-seconds

Initform

(quote nil)

Readers

elapsed-seconds (generic function)

Condition: verdict-abort* ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses
Condition: verdict-skip ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses

Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.6 Structures

Structure: sub ()

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.

Package

try

Source

is.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: var
Readers

sub-var (function)

Writers

(setf sub-var) (function)

Slot: subform
Readers

sub-subform (function)

Writers

(setf sub-subform) (function)

Slot: new-form
Readers

sub-new-form (function)

Writers

(setf sub-new-form) (function)

Slot: valuesp
Readers

sub-valuesp (function)

Writers

(setf sub-valuesp) (function)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.7 Classes

Class: tree-printer ()

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.

Package

try

Source

print.lisp (file)

Direct superclasses

printer (class)

Direct methods
Direct slots
Slot: indentation
Initform

try:*print-indentation*

Readers

indentation (generic function)

Slot: print-duration-p
Initform

try:*print-duration*

Readers

print-duration-p (generic function)

Slot: print-compactly
Initform

try:*print-compactly*

Readers

print-compactly (generic function)

Slot: defer-describe
Initform

try:*defer-describe*

Readers

defer-describe (generic function)

Slot: to-be-described
Readers

to-be-described (generic function)

Writers

(setf to-be-described) (generic function)

Class: trial ()

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.

Package

try

Source

trial.lisp (file)

Direct superclasses

funcallable-standard-object (class)

Direct methods
Direct slots
Slot: test-name
Initargs

try::%test-name

Initform

(error "trials are not to be instantiated directly.")

Readers

test-name (generic function)

Slot: cform
Initargs

:cform

Readers

cform (generic function)

Slot: parent
Initform

try::*trial*

Readers

parent (generic function)

Slot: depth
Initform

(if try::*trial* (1+ (slot-value try::*trial* (quote try::depth))) 0)

Readers

depth (generic function)

Slot: abort-restart
Readers

abort-restart (generic function)

Writers

(setf abort-restart) (generic function)

Slot: skip-restart
Readers

skip-restart (generic function)

Writers

(setf skip-restart) (generic function)

Slot: retry-restart
Readers

retry-restart (generic function)

Writers

(setf retry-restart) (generic function)

Slot: trial-start
Readers

trial-start (generic function)

Slot: elapsed-seconds
Initargs

:elapsed-seconds

Readers

elapsed-seconds (generic function)

Slot: categories
Initargs

:categories

Initform

(if try::*trial* (try::categories try::*trial*) try:*categories*)

Readers

categories (generic function)

Slot: count
Initargs

:count

Initform

(if try::*trial* (try::count-of try::*trial*) try:*count*)

Readers

count-of (generic function)

Slot: n-retries

The number of times this [TRIAL][dislocated] has been retried. See RETRY-TRIAL.

Initargs

:n-retries

Initform

0

Readers

n-retries (generic function)

Slot: how-to-end
Type

(member nil :return :abort :retry :skip)

Initargs

:how-to-end

Initform

:return

Readers

how-to-end (generic function)

Writers

(setf how-to-end) (generic function)

Slot: how-it-ended
Readers

how-it-ended (generic function)

Slot: verdict

The [VERDICT][condition] EVENT signalled when this [TRIAL][dislocated] finished or NIL if it has not finished yet.

Readers

verdict (generic function)

Slot: children

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.

Initargs

:children

Readers

children (generic function)

Slot: has-non-collected-failed-child-p
Initargs

:has-non-collected-failed-child-p

Readers

has-non-collected-failed-child-p (generic function)

Slot: counter
Initargs

:counter

Readers

counter (generic function)

Slot: non-collected-counter
Initargs

:non-collected-counter

Readers

non-collected-counter (generic function)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.8 Types

Type: expected-failure ()

A shorthand for ‘(AND EXPECTED FAILURE)‘.

Package

try

Source

events.lisp (file)

Type: expected-success ()

A shorthand for ‘(AND EXPECTED SUCCESS)‘.

Package

try

Source

events.lisp (file)

Type: fail ()

An ABORT* or an UNEXPECTED FAILURE.

Package

try

Source

events.lisp (file)

Type: pass ()

An OUTCOME that’s not an ABORT* or an UNEXPECTED FAILURE.

Package

try

Source

events.lisp (file)

Type: unexpected-failure ()

A shorthand for ‘(AND UNEXPECTED FAILURE)‘.

Package

try

Source

events.lisp (file)

Type: unexpected-success ()

A shorthand for ‘(AND UNEXPECTED SUCCESS)‘.

Package

try

Source

events.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *call-test*
Package

try

Source

test.lisp (file)

Special Variable: *call-test-fn*
Package

try

Source

test.lisp (file)

Special Variable: *dbg*
Package

try

Source

debug.lisp (file)

Special Variable: *dummy*
Package

try

Source

util.lisp (file)

Special Variable: *expected-outcome*
Package

try

Source

outcome.lisp (file)

Special Variable: *internal-error*
Package

try

Source

debug.lisp (file)

Special Variable: *invoking-debugger*
Package

try

Source

try.lisp (file)

Special Variable: *print-backtrace*
Package

try

Source

error.lisp (file)

Special Variable: *recent-trials*
Package

try

Source

try.lisp (file)

Special Variable: *record-event*
Package

try

Source

early.lisp (file)

Special Variable: *skip*
Package

try

Source

outcome.lisp (file)

Special Variable: *start-time*
Package

try

Source

util.lisp (file)

Special Variable: *testing-timing*
Package

try

Source

util.lisp (file)

Special Variable: *tests-run*
Package

try

Source

test.lisp (file)

Special Variable: *trial*
Package

try

Source

early.lisp (file)

Special Variable: *trial-initargs*
Package

try

Source

test.lisp (file)

Special Variable: *try-id*
Package

try

Source

early.lisp (file)

Special Variable: @cancelled-nlx
Package

try

Source

manual.lisp (file)

Special Variable: @funcallable-instance
Package

try

Source

manual.lisp (file)

Special Variable: @function-designator
Package

try

Source

manual.lisp (file)

Special Variable: @non-local-exit
Package

try

Source

manual.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: %unwind-protect PROTECTED &body CLEANUP
Package

try

Source

util.lisp (file)

Macro: condition-match-checker (CONDITION-TYPE &key PRED HANDLER ON-RETURN ON-NLX NAME MSG CTX CHECK-FUNCTION) &body BODY
Package

try

Source

checks.lisp (file)

Macro: dbg FORMAT-CONTROL &rest FORMAT-ARGS
Package

try

Source

debug.lisp (file)

Macro: define-combi-event BASIC-SUPERCLASSES
Package

try

Source

events.lisp (file)

Macro: define-macrolet SYMBOL LAMBDA-LIST &body DOCSTRING
Package

try

Source

is.lisp (file)

Macro: match-values% FORM &body BODY
Package

try

Source

checks.lisp (file)

Macro: on-finish PROTECTED &body CLEANUP
Package

try

Source

util.lisp (file)

Macro: on-nlx PROTECTED &body CLEANUP
Package

try

Source

util.lisp (file)

Macro: on-return PROTECTED &body CLEANUP
Package

try

Source

util.lisp (file)

Macro: remembering-most-recent-trials &body BODY
Package

try

Source

try.lisp (file)

Macro: restart-bind ((&key STREAM CONDITION) &rest BINDINGS) &body BODY
Package

try

Source

util.lisp (file)

Macro: restart-case FORM (&key STREAM CONDITION) &body BINDINGS
Package

try

Source

util.lisp (file)

Macro: try-default-unspecified-args &key REPLAYP
Package

try

Source

try.lisp (file)

Macro: with-bindings BINDINGS &body BODY
Package

try

Source

util.lisp (file)

Macro: with-circularity-detection (STREAM) &body BODY
Package

try

Source

util.lisp (file)

Macro: with-condition-matching (MATCHEDP &optional BEST-MATCH) (CONDITION-TYPE &key PRED HANDLER) &body BODY
Package

try

Source

checks.lisp (file)

Macro: with-current-debug (VAR INIT-FORM) &body BODY
Package

try

Source

try.lisp (file)

Macro: with-debugger-hook FN &body BODY
Package

try

Source

util.lisp (file)

Macro: with-debugger-hook-form FORM &body BODY
Package

try

Source

util.lisp (file)

Macro: with-error*-handled (TRIAL) &body BODY
Package

try

Source

trial.lisp (file)

Macro: with-gensyms VARS &body BODY
Package

try

Source

util.lisp (file)

Macro: with-internal-errors &body BODY
Package

try

Source

debug.lisp (file)

Macro: with-retry (&key RETRY ON-RETRY) &body BODY
Package

try

Source

util.lisp (file)

Macro: with-retry/catch (&key CATCH ON-RETRY) &body BODY
Package

try

Source

util.lisp (file)

Macro: with-timing &body BODY
Package

try

Source

util.lisp (file)

Macro: with-trial (TRIAL) &body BODY
Package

try

Source

trial.lisp (file)

Macro: with-trial-restarts (TRIAL &key RETURN-FORM RETRY-FORM RESIGNAL-VERDICT-FORM) &body BODY
Package

try

Source

trial.lisp (file)

Macro: with-try-context &body BODY
Package

try

Source

try.lisp (file)

Macro: without-tail-call &body BODY
Package

try

Source

util.lisp (file)

Macro: wrap-trial-body-for-return TRIAL &body BODY
Package

try

Source

test.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: %%write-result-msg RESULT STREAM
Package

try

Source

result.lisp (file)

Function: %collector-collect-type INSTANCE
Function: (setf %collector-collect-type) VALUE INSTANCE
Package

try

Source

collect.lisp (file)

Function: %collector-count-type INSTANCE
Function: (setf %collector-count-type) VALUE INSTANCE
Package

try

Source

collect.lisp (file)

Function: %collector-p OBJECT
Package

try

Source

collect.lisp (file)

Function: %count-and-collect-event COLLECTOR EVENT
Package

try

Source

collect.lisp (file)

Function: %describe-condition-for-matching CONDITION &optional STREAM
Package

try

Source

checks.lisp (file)

Function: %ensure-new-line STREAM
Package

try

Source

print.lisp (file)

Function: %ensure-trial-printed TRIAL PRINTER
Package

try

Source

print.lisp (file)

Function: %extract-options OPTION-NAMES BODY &key OPTIONS-FIRST
Package

try

Source

util.lisp (file)

Function: %frob-form-for-printing RESULT FORM
Package

try

Source

result.lisp (file)

Function: %make-counter &key (COUNTS COUNTS) (CATEGORIES CATEGORIES)
Package

try

Source

count.lisp (file)

Function: %make-indent N
Package

try

Source

print.lisp (file)

Function: %make-rerun-trial-event-handler TRIAL-TO-RERUN RERUN-TYPE
Package

try

Source

rerun.lisp (file)

Function: %match-condition CONDITION CONDITION-TYPE PRED
Package

try

Source

checks.lisp (file)

Function: %maybe-invoke-debugger OUTCOME DEBUG-OUTCOME-TYPE
Package

try

Source

try.lisp (file)

Function: %print-event PRINTER EVENT
Package

try

Source

print.lisp (file)

Function: %print-indent-for PRINTER EVENT
Package

try

Source

print.lisp (file)

Function: %print-leaf PRINTER LEAF
Package

try

Source

print.lisp (file)

Function: %print-verdict PRINTER VERDICT
Package

try

Source

print.lisp (file)

Function: %replay-events TRIAL
Package

try

Source

replay.lisp (file)

Function: %replay-trial-initargs TRIAL
Package

try

Source

replay.lisp (file)

Function: %subs-to-bindings SUBS
Package

try

Source

is.lisp (file)

Function: %subs-to-captures SUBS
Package

try

Source

is.lisp (file)

Function: %trial-basic-verdict TRIAL
Package

try

Source

trial.lisp (file)

Function: %wrap-restart-bind-binding-in-lambda BINDING STREAM-VAR CONDITION-VAR
Package

try

Source

util.lisp (file)

Function: %wrap-restart-bind-option-in-lambda OPTION FORM STREAM-VAR CONDITION-VAR
Package

try

Source

util.lisp (file)

Function: %wrap-restart-case-binding-in-lambda BINDING STREAM-VAR CONDITION-VAR
Package

try

Source

util.lisp (file)

Function: %wrap-restart-case-option-in-lambda OPTION FORM STREAM-VAR CONDITION-VAR
Package

try

Source

util.lisp (file)

Function: %write-result RESULT STREAM &key TERSE CTX
Package

try

Source

result.lisp (file)

Function: %write-result-captures RESULT STREAM
Package

try

Source

result.lisp (file)

Function: %write-result-ctx RESULT STREAM
Package

try

Source

result.lisp (file)

Function: %write-result-msg RESULT STREAM &key TERSE
Package

try

Source

result.lisp (file)

Function: add-to-counter COUNTER1 COUNTER2
Package

try

Source

count.lisp (file)

Function: add-to-recent-trials TRIAL
Package

try

Source

try.lisp (file)

Function: ancestor-trial-names TRIAL
Package

try

Source

print.lisp (file)

Function: ancestors-from-oldest TRIAL
Package

try

Source

print.lisp (file)

Function: bool= A B
Package

try

Source

util.lisp (file)

Function: bump-counter COUNTER EVENT
Package

try

Source

count.lisp (file)

Function: call-lambda-trial TRIAL
Package

try

Source

rerun.lisp (file)

Function: call-named-trial CFORM
Package

try

Source

rerun.lisp (file)

Function: call-test ()
Package

try

Source

test.lisp (file)

Function: call-testable TESTABLE
Package

try

Source

testable.lisp (file)

Function: call-trial TRIAL
Package

try

Source

rerun.lisp (file)

Function: call-try-trial TRIAL
Package

try

Source

rerun.lisp (file)

Function: call-with-wrapper FUNCTION-DESIGNATORS WRAPPER-CFORM
Package

try

Source

testable.lisp (file)

Function: capture-explicitp STRUCTURE
Function: (setf capture-explicitp) VALUE STRUCTURE
Package

try

Source

is.lisp (file)

Function: capture-subform STRUCTURE
Function: (setf capture-subform) VALUE STRUCTURE
Package

try

Source

is.lisp (file)

Function: capture-value STRUCTURE
Function: (setf capture-value) VALUE STRUCTURE
Package

try

Source

is.lisp (file)

Function: capture-valuesp STRUCTURE
Function: (setf capture-valuesp) VALUE STRUCTURE
Package

try

Source

is.lisp (file)

Function: category-marker EVENT CATEGORIES
Package

try

Source

events.lisp (file)

Function: check-event-type TYPE ARG-NAME
Package

try

Source

try.lisp (file)

Function: check-fails FINISHEDP NAME MSG CTX BODY
Package

try

Source

checks.lisp (file)

Function: check-invokes-debugger CONDITION-TYPE PRED NAME MSG CTX BODY
Package

try

Source

checks.lisp (file)

Function: check-invokes-debugger-not CONDITION-TYPE PRED NAME MSG CTX BODY
Package

try

Source

checks.lisp (file)

Function: check-printer-arg PRINTER
Package

try

Source

try.lisp (file)

Function: check-signals CONDITION-TYPE PRED NAME MSG CTX BODY
Package

try

Source

checks.lisp (file)

Function: check-signals-not CONDITION-TYPE PRED NAME MSG CTX BODY
Package

try

Source

checks.lisp (file)

Function: check-trial-running TRIAL
Package

try

Source

trial.lisp (file)

Function: child-trials TRIAL
Package

try

Source

rerun.lisp (file)

Function: clean-up-cancelled-nlx-of-retry-for-end-trial TRIAL
Package

try

Source

trial.lisp (file)

Function: clear-trial-restarts TRIAL
Package

try

Source

trial.lisp (file)

Function: combine-superclasses BASIC-SUPERCLASSES
Package

try

Source

events.lisp (file)

Function: compiler-policy ENV
Package

try

Source

util.lisp (file)

Function: compiler-policy-quantity QUANTITY ENV
Package

try

Source

util.lisp (file)

Function: constantishp FORM
Package

try

Source

is.lisp (file)

Function: copy-%collector INSTANCE
Package

try

Source

collect.lisp (file)

Function: copy-capture SEQUENCE

Return a copy of SEQUENCE which is EQUAL to SEQUENCE but not EQ.

Package

try

Source

SYS:SRC;CODE;SEQ.LISP (not found)

Function: copy-counter COUNTER
Package

try

Source

count.lisp (file)

Function: copy-print-state INSTANCE
Package

try

Source

print.lisp (file)

Function: copy-sub INSTANCE
Package

try

Source

is.lisp (file)

Function: count-and-collect-leaf COLLECTOR LEAF
Package

try

Source

collect.lisp (file)

Function: count-and-collect-verdict COLLECTOR VERDICT
Package

try

Source

collect.lisp (file)

Function: count-collected-leaf LEAF COUNT-TYPE
Package

try

Source

collect.lisp (file)

Function: count-collected-verdict VERDICT COUNT-TYPE
Package

try

Source

collect.lisp (file)

Function: count-non-collected-leaf LEAF COUNT-TYPE
Package

try

Source

collect.lisp (file)

Function: count-non-collected-verdict VERDICT TRIAL PARENT COUNT-TYPE
Package

try

Source

collect.lisp (file)

Function: count-trial-start TRIAL-START COUNT-TYPE
Package

try

Source

collect.lisp (file)

Function: counter-categories INSTANCE
Function: (setf counter-categories) VALUE INSTANCE
Package

try

Source

count.lisp (file)

Function: counter-counts INSTANCE
Function: (setf counter-counts) VALUE INSTANCE
Package

try

Source

count.lisp (file)

Function: counter-p OBJECT
Package

try

Source

count.lisp (file)

Function: deftest-registry-var-name PACKAGE
Package

try

Source

test.lisp (file)

Function: describe-condition CONDITION &optional STREAM
Package

try

Source

error.lisp (file)

Function: describe-to-be-described PRINTER
Package

try

Source

print.lisp (file)

Function: determine-outcome-type CHECKP BASIC-OUTCOME &optional EXPECTED-TYPE
Package

try

Source

outcome.lisp (file)

Function: double-float-~= X Y MAX-DIFF-IN-VALUE MAX-DIFF-IN-ULP
Package

try

Source

floats.lisp (file)

Function: end-trial TRIAL
Package

try

Source

trial.lisp (file)

Function: ensure-deftest-registry PACKAGE
Package

try

Source

test.lisp (file)

Function: ensure-list OBJECT
Package

try

Source

util.lisp (file)

Function: ensure-rest-arg LAMBDA-LIST &optional REST-VAR
Package

try

Source

util.lisp (file)

Function: event-category EVENT CATEGORIES
Package

try

Source

events.lisp (file)

Function: event-print-depth EVENT PRINTER
Package

try

Source

print.lisp (file)

Function: expand-with-trial-in-deftest-p ENV
Package

try

Source

test.lisp (file)

Function: get-deftest-registry PACKAGE
Package

try

Source

test.lisp (file)

Function: get-elapsed-seconds ()
Package

try

Source

util.lisp (file)

Function: intern-hyphenated SYMBOLS
Package

try

Source

util.lisp (file)

Function: invoke-test-interactively NAME LAMBDA-LIST
Package

try

Source

test.lisp (file)

Function: invokes-debugger-default-ctx CONDITION-TYPE
Package

try

Source

checks.lisp (file)

Function: invokes-debugger-default-msg NAME BODY CONDITION-TYPE PRED
Package

try

Source

checks.lisp (file)

Function: invokes-debugger-not-default-msg NAME BODY CONDITION-TYPE PRED
Package

try

Source

checks.lisp (file)

Function: lambda-list-to-arglist-form LAMBDA-LIST
Package

try

Source

util.lisp (file)

Function: lambda-list-with-&rest-to-arglist-form LAMBDA-LIST
Package

try

Source

util.lisp (file)

Function: lambda-trial-p TRIAL
Package

try

Source

trial.lisp (file)

Function: list-function-designators TESTABLE
Package

try

Source

testable.lisp (file)

Function: make-%collector &key (COUNT-TYPE COUNT-TYPE) (COLLECT-TYPE COLLECT-TYPE)
Package

try

Source

collect.lisp (file)

Function: make-capture SUBFORM VALUE VALUESP EXPLICITP
Package

try

Source

is.lisp (file)

Function: make-counter CATEGORIES
Package

try

Source

count.lisp (file)

Function: make-gensym OBJECT
Package

try

Source

util.lisp (file)

Function: make-print-state &key (TRIAL TRIAL) (N-RETRIES N-RETRIES) (FIRST-LINE-AND-COLUMN FIRST-LINE-AND-COLUMN)
Package

try

Source

print.lisp (file)

Function: make-trial NAME CFORM &optional EXTRA-INITARGS
Package

try

Source

test.lisp (file)

Function: maybe-backtrace CONDITION
Package

try

Source

error.lisp (file)

Function: maybe-mark-test-run TRIAL
Package

try

Source

test.lisp (file)

Function: named-trial-p TRIAL
Package

try

Source

trial.lisp (file)

Function: present-body BODY
Package

try

Source

util.lisp (file)

Function: print-duration SECONDS STREAM
Package

try

Source

print.lisp (file)

Function: print-event-header PRINTER EVENT
Package

try

Source

print.lisp (file)

Function: print-state-first-line-and-column INSTANCE
Function: (setf print-state-first-line-and-column) VALUE INSTANCE
Package

try

Source

print.lisp (file)

Function: print-state-n-retries INSTANCE
Function: (setf print-state-n-retries) VALUE INSTANCE
Package

try

Source

print.lisp (file)

Function: print-state-p OBJECT
Package

try

Source

print.lisp (file)

Function: print-state-trial INSTANCE
Function: (setf print-state-trial) VALUE INSTANCE
Package

try

Source

print.lisp (file)

Function: print-state-trial-printed-p PRINT-STATE
Package

try

Source

print.lisp (file)

Function: printer-depth PRINTER
Package

try

Source

print.lisp (file)

Function: read-argument-list NAME LAMBDA-LIST
Package

try

Source

test.lisp (file)

Function: read-try-debug ()
Package

try

Source

try.lisp (file)

Function: register-deftest SYMBOL
Package

try

Source

test.lisp (file)

Function: report-change-outcome-to STREAM OUTCOME-TYPE
Package

try

Source

outcome.lisp (file)

Function: reset-counter COUNTER
Package

try

Source

count.lisp (file)

Function: safe-subtypep TYPE1 TYPE2
Package

try

Source

util.lisp (file)

Function: safe-typep OBJECT TYPE
Package

try

Source

util.lisp (file)

Function: same-but-different-implicit-captures-p CAPTURE1 CAPTURE2
Package

try

Source

is.lisp (file)

Function: say-how-to-end ANCESTOR-TRIAL ANCESTOR-HOW-TO-END UNTIL-THEN-HOW-TO-END
Package

try

Source

trial.lisp (file)

Function: scrub-captures CAPTURES
Package

try

Source

is.lisp (file)

Function: set-up-trial-restarts TRIAL
Package

try

Source

trial.lisp (file)

Function: shuffle SEQ

Copy of SEQ and shuffle it using Fisher-Yates algorithm.

Package

try

Source

util.lisp (file)

Function: shuffle! SEQ

Shuffle SEQ using Fisher-Yates algorithm.

Package

try

Source

util.lisp (file)

Function: shuffle-vector! VECTOR
Package

try

Source

util.lisp (file)

Function: signal-error* UNHANDLED-ERROR TRIAL &key EXTRA-MESSAGE DEBUGGER-INVOKED-P
Package

try

Source

error.lisp (file)

Function: signal-outcome CHECKP BASIC-OUTCOME INITARGS
Package

try

Source

outcome.lisp (file)

Function: signal-with-record-event CONDITION
Package

try

Source

events.lisp (file)

Function: single-float-~= X Y MAX-DIFF-IN-VALUE MAX-DIFF-IN-ULP
Package

try

Source

floats.lisp (file)

Function: start-retry-for-trial TRIAL
Package

try

Source

trial.lisp (file)

Function: start-trial TRIAL
Package

try

Source

trial.lisp (file)

Function: stream-line-column* STREAM
Package

try

Source

gray-stream.lisp (file)

Function: strip-outer-%-and-%%-from-implicit-captures CAPTURES
Package

try

Source

is.lisp (file)

Function: sub-p OBJECT
Package

try

Source

is.lisp (file)

Function: subseq* SEQ START END
Package

try

Source

util.lisp (file)

Function: substitute-args FORM
Package

try

Source

is.lisp (file)

Function: substitute-in-subs SUBS ENV
Package

try

Source

is.lisp (file)

Function: substitute-is-form FORM ENV
Package

try

Source

is.lisp (file)

Function: substitute-tilde-percent STRING
Package

try

Source

result.lisp (file)

Function: sync-stream-line-column TO-COLUMN STREAM
Package

try

Source

gray-stream.lisp (file)

Function: trial-call-= TRIAL1 TRIAL2
Package

try

Source

rerun.lisp (file)

Function: trial-has-event-of-type-p TRIAL TYPE
Package

try

Source

rerun.lisp (file)

Function: trial-printed-p TRIAL PRINTER
Package

try

Source

print.lisp (file)

Function: trialp OBJECT
Package

try

Source

trial.lisp (file)

Function: try-trial-p TRIAL
Package

try

Source

trial.lisp (file)

Function: try-trial-testable TRIAL
Package

try

Source

trial.lisp (file)

Function: try/implicit TRIAL
Package

try

Source

try.lisp (file)

Function: valid-type-specifier-p TYPE
Package

try

Source

util.lisp (file)

Function: verdict-for-trial-p TRIAL EVENT
Package

try

Source

trial.lisp (file)

Function: write-trial-counts TRIAL STREAM
Package

try

Source

print.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Generic functions

Generic Function: abort-restart OBJECT
Generic Function: (setf abort-restart) NEW-VALUE OBJECT
Package

try

Methods
Method: abort-restart (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Method: (setf abort-restart) NEW-VALUE (TRIAL trial)

automatically generated writer method

Source

trial.lisp (file)

Generic Function: captures CONDITION
Package

try

Methods
Method: captures (CONDITION result)
Source

result.lisp (file)

Generic Function: categories OBJECT
Package

try

Methods
Method: categories (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: cform OBJECT
Package

try

Methods
Method: cform (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: check CONDITION
Package

try

Methods
Method: check (CONDITION result)
Source

result.lisp (file)

Generic Function: column OBJECT
Generic Function: (setf column) NEW-VALUE OBJECT
Package

try

Methods
Method: column (LINE/COLUMN-CHARACTER-OUTPUT-STREAM line/column-character-output-stream)

automatically generated reader method

Source

gray-stream.lisp (file)

Method: (setf column) NEW-VALUE (LINE/COLUMN-CHARACTER-OUTPUT-STREAM line/column-character-output-stream)

automatically generated writer method

Source

gray-stream.lisp (file)

Generic Function: count-of OBJECT
Package

try

Methods
Method: count-of (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: counter OBJECT
Package

try

Methods
Method: counter (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: ctx CONDITION
Package

try

Methods
Method: ctx (CONDITION result)
Source

result.lisp (file)

Generic Function: defer-describe OBJECT
Package

try

Methods
Method: defer-describe (TREE-PRINTER tree-printer)

automatically generated reader method

Source

print.lisp (file)

Generic Function: depth OBJECT
Package

try

Methods
Method: depth (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: describe-leaf PRINTER LEAF
Package

try

Source

print.lisp (file)

Methods
Method: describe-leaf (PRINTER tree-printer) OUTCOME
Generic Function: describe-type OBJECT
Package

try

Methods
Method: describe-type (PRINTER printer)

The DESCRIBE argument of TRY.

Source

print.lisp (file)

Generic Function: elapsed-seconds CONDITION
Package

try

Methods
Method: elapsed-seconds (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Method: elapsed-seconds (CONDITION verdict)
Source

trial-event.lisp (file)

Method: elapsed-seconds (CONDITION result)
Source

result.lisp (file)

Generic Function: extra-message CONDITION
Package

try

Methods
Method: extra-message (CONDITION nlx)
Source

error.lisp (file)

Generic Function: finish-printing PRINTER
Package

try

Source

print.lisp (file)

Methods
Method: finish-printing (PRINTER tree-printer)
Method: finish-printing PRINTER around
Generic Function: has-non-collected-failed-child-p OBJECT
Package

try

Methods
Method: has-non-collected-failed-child-p (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: how-it-ended OBJECT
Package

try

Methods
Method: how-it-ended (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: how-to-end OBJECT
Generic Function: (setf how-to-end) NEW-VALUE OBJECT
Package

try

Methods
Method: how-to-end (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Method: (setf how-to-end) NEW-VALUE (TRIAL trial)

automatically generated writer method

Source

trial.lisp (file)

Generic Function: indentation OBJECT
Package

try

Methods
Method: indentation (TREE-PRINTER tree-printer)

automatically generated reader method

Source

print.lisp (file)

Generic Function: inner-stream OBJECT
Package

try

Methods
Method: inner-stream (WRAPPED-STREAM wrapped-stream)

automatically generated reader method

Source

gray-stream.lisp (file)

Generic Function: line OBJECT
Generic Function: (setf line) NEW-VALUE OBJECT
Package

try

Methods
Method: line (LINE/COLUMN-CHARACTER-OUTPUT-STREAM line/column-character-output-stream)

automatically generated reader method

Source

gray-stream.lisp (file)

Method: (setf line) NEW-VALUE (LINE/COLUMN-CHARACTER-OUTPUT-STREAM line/column-character-output-stream)

automatically generated writer method

Source

gray-stream.lisp (file)

Generic Function: msg CONDITION
Package

try

Methods
Method: msg (CONDITION result)
Source

result.lisp (file)

Generic Function: nested-error CONDITION
Package

try

Methods
Method: nested-error (CONDITION try-internal-error)
Source

debug.lisp (file)

Generic Function: non-collected-counter OBJECT
Package

try

Methods
Method: non-collected-counter (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: parent OBJECT
Package

try

Methods
Method: parent (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Generic Function: print-captures CONDITION
Package

try

Methods
Method: print-captures (CONDITION result)
Source

result.lisp (file)

Generic Function: print-compactly OBJECT
Package

try

Methods
Method: print-compactly (TREE-PRINTER tree-printer)

automatically generated reader method

Source

print.lisp (file)

Generic Function: print-duration-p OBJECT
Package

try

Methods
Method: print-duration-p (TREE-PRINTER tree-printer)

automatically generated reader method

Source

print.lisp (file)

Generic Function: print-event PRINTER TRIAL
Package

try

Source

print.lisp (file)

Methods
Method: print-event (PRINTER tree-printer) (LEAF leaf)
Method: print-event (PRINTER tree-printer) (VERDICT verdict)
Method: print-event (PRINTER tree-printer) (EVENT trial-start)
Generic Function: print-form-memoization-data CONDITION
Generic Function: (setf print-form-memoization-data) NEW-VALUE CONDITION
Package

try

Methods
Method: print-form-memoization-data (CONDITION result)
Method: (setf print-form-memoization-data) NEW-VALUE (CONDITION result)
Source

result.lisp (file)

Generic Function: print-parent OBJECT
Package

try

Methods
Method: print-parent (PRINTER printer)

The value of *PRINT-PARENT* when the printer was instantiated.

Source

print.lisp (file)

Generic Function: print-type OBJECT
Package

try

Methods
Method: print-type (PRINTER printer)

The PRINT argument of TRY.

Source

print.lisp (file)

Generic Function: retry-restart OBJECT
Generic Function: (setf retry-restart) NEW-VALUE OBJECT
Package

try

Methods
Method: retry-restart (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Method: (setf retry-restart) NEW-VALUE (TRIAL trial)

automatically generated writer method

Source

trial.lisp (file)

Generic Function: skip-restart OBJECT
Generic Function: (setf skip-restart) NEW-VALUE OBJECT
Package

try

Methods
Method: skip-restart (TRIAL trial)

automatically generated reader method

Source

trial.lisp (file)

Method: (setf skip-restart) NEW-VALUE (TRIAL trial)

automatically generated writer method

Source

trial.lisp (file)

Generic Function: stream-column STREAM
Package

try

Source

gray-stream.lisp (file)

Methods
Method: stream-column (STREAM line/column-character-output-stream)
Generic Function: stream-line STREAM
Package

try

Source

gray-stream.lisp (file)

Methods
Method: stream-line (STREAM line/column-character-output-stream)
Generic Function: stream-of OBJECT
Package

try

Methods
Method: stream-of (PRINTER printer)

The stream to which output shall be written.

Source

print.lisp (file)

Generic Function: to-be-described OBJECT
Generic Function: (setf to-be-described) NEW-VALUE OBJECT
Package

try

Methods
Method: to-be-described (TREE-PRINTER tree-printer)

automatically generated reader method

Source

print.lisp (file)

Method: (setf to-be-described) NEW-VALUE (TREE-PRINTER tree-printer)

automatically generated writer method

Source

print.lisp (file)

Generic Function: trial-print-states OBJECT
Package

try

Methods
Method: trial-print-states (PRINTER printer)

A list

Source

print.lisp (file)

Generic Function: write-event EVENT STREAM &key TERSE CTX
Package

try

Source

events.lisp (file)

Methods
Method: write-event (NLX nlx) STREAM &key TERSE CTX
Source

error.lisp (file)

Method: write-event (UNHANDLED-ERROR unhandled-error) STREAM &key TERSE CTX
Source

error.lisp (file)

Method: write-event (VERDICT verdict) STREAM &key TERSE CTX
Source

trial-event.lisp (file)

Method: write-event (TRIAL-START trial-start) STREAM &key TERSE CTX
Source

trial-event.lisp (file)

Method: write-event (RESULT result) STREAM &key TERSE CTX
Source

result.lisp (file)

Method: write-event EVENT STREAM &key TERSE CTX around

Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Conditions

Condition: result-failure ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: result-success ()
Package

try

Source

result.lisp (file)

Direct superclasses
Condition: try-internal-error ()
Package

try

Source

debug.lisp (file)

Direct superclasses

serious-condition (condition)

Direct methods

nested-error (method)

Direct slots
Slot: error
Initargs

:error

Initform

(quote nil)

Readers

nested-error (generic function)

Condition: verdict-failure ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses
Condition: verdict-success ()
Package

try

Source

trial-event.lisp (file)

Direct superclasses

Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.6 Structures

Structure: %collector ()
Package

try

Source

collect.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: count-type
Readers

%collector-count-type (function)

Writers

(setf %collector-count-type) (function)

Slot: collect-type
Readers

%collector-collect-type (function)

Writers

(setf %collector-collect-type) (function)

Structure: counter ()
Package

try

Source

count.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: counts
Readers

counter-counts (function)

Writers

(setf counter-counts) (function)

Slot: categories
Readers

counter-categories (function)

Writers

(setf counter-categories) (function)

Structure: print-state ()
Package

try

Source

print.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: trial
Readers

print-state-trial (function)

Writers

(setf print-state-trial) (function)

Slot: n-retries
Readers

print-state-n-retries (function)

Writers

(setf print-state-n-retries) (function)

Slot: first-line-and-column
Readers

print-state-first-line-and-column (function)

Writers

(setf print-state-first-line-and-column) (function)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.7 Classes

Class: dummy-with-print-object ()
Package

try

Source

util.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

print-object (method)

Direct slots
Slot: fn
Initargs

:fn

Class: line/column-character-output-stream ()
Package

try

Source

gray-stream.lisp (file)

Direct superclasses
Direct methods
  • stream-column (method)
  • stream-line (method)
  • stream-write-char (method)
  • stream-line-column (method)
  • initialize-instance (method)
  • column (method)
  • column (method)
  • line (method)
  • line (method)
Direct slots
Slot: line
Initform

0

Readers

line (generic function)

Writers

(setf line) (generic function)

Slot: column
Readers

column (generic function)

Writers

(setf column) (generic function)

Class: printer ()

PRINTER is the abstract base class for all printers.

Package

try

Source

print.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

tree-printer (class)

Direct methods
Direct slots
Slot: stream

The stream to which output shall be written.

Initargs

:stream

Initform

*debug-io*

Readers

stream-of (generic function)

Slot: print-type

The PRINT argument of TRY.

Initargs

:print-type

Initform

t

Readers

print-type (generic function)

Slot: describe-type

The DESCRIBE argument of TRY.

Initargs

:describe-type

Initform

t

Readers

describe-type (generic function)

Slot: print-parent

The value of *PRINT-PARENT* when the printer was instantiated.

Initform

try:*print-parent*

Readers

print-parent (generic function)

Slot: variable-bindings
Initform

(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))))

Slot: trial-print-states

A list

Readers

trial-print-states (generic function)

Class: wrapped-stream ()
Package

try

Source

gray-stream.lisp (file)

Direct superclasses

fundamental-stream (class)

Direct subclasses

line/column-character-output-stream (class)

Direct methods
  • close (method)
  • stream-element-type (method)
  • inner-stream (method)
Direct slots
Slot: inner-stream
Initargs

:stream

Readers

inner-stream (generic function)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.8 Types

Type: basic-error*-outcome ()
Package

try

Source

error.lisp (file)

Type: basic-outcome ()
Package

try

Source

outcome.lisp (file)

Type: valid-type-specifier ()
Package

try

Source

util.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, try.asd: The try․asd file
File, Lisp, try.asdf.asd: The try․asdf․asd file
File, Lisp, try.asdf/asdf.lisp: The try․asdf/asdf․lisp file
File, Lisp, try/checks.lisp: The try/checks․lisp file
File, Lisp, try/collect.lisp: The try/collect․lisp file
File, Lisp, try/count.lisp: The try/count․lisp file
File, Lisp, try/debug.lisp: The try/debug․lisp file
File, Lisp, try/early.lisp: The try/early․lisp file
File, Lisp, try/error.lisp: The try/error․lisp file
File, Lisp, try/events.lisp: The try/events․lisp file
File, Lisp, try/floats.lisp: The try/floats․lisp file
File, Lisp, try/gray-stream.lisp: The try/gray-stream․lisp file
File, Lisp, try/is.lisp: The try/is․lisp file
File, Lisp, try/manual.lisp: The try/manual․lisp file
File, Lisp, try/outcome.lisp: The try/outcome․lisp file
File, Lisp, try/package.lisp: The try/package․lisp file
File, Lisp, try/print.lisp: The try/print․lisp file
File, Lisp, try/replay.lisp: The try/replay․lisp file
File, Lisp, try/rerun.lisp: The try/rerun․lisp file
File, Lisp, try/result.lisp: The try/result․lisp file
File, Lisp, try/test.lisp: The try/test․lisp file
File, Lisp, try/testable.lisp: The try/testable․lisp file
File, Lisp, try/trial-event.lisp: The try/trial-event․lisp file
File, Lisp, try/trial.lisp: The try/trial․lisp file
File, Lisp, try/try.lisp: The try/try․lisp file
File, Lisp, try/util.lisp: The try/util․lisp file

L
Lisp File, try.asd: The try․asd file
Lisp File, try.asdf.asd: The try․asdf․asd file
Lisp File, try.asdf/asdf.lisp: The try․asdf/asdf․lisp file
Lisp File, try/checks.lisp: The try/checks․lisp file
Lisp File, try/collect.lisp: The try/collect․lisp file
Lisp File, try/count.lisp: The try/count․lisp file
Lisp File, try/debug.lisp: The try/debug․lisp file
Lisp File, try/early.lisp: The try/early․lisp file
Lisp File, try/error.lisp: The try/error․lisp file
Lisp File, try/events.lisp: The try/events․lisp file
Lisp File, try/floats.lisp: The try/floats․lisp file
Lisp File, try/gray-stream.lisp: The try/gray-stream․lisp file
Lisp File, try/is.lisp: The try/is․lisp file
Lisp File, try/manual.lisp: The try/manual․lisp file
Lisp File, try/outcome.lisp: The try/outcome․lisp file
Lisp File, try/package.lisp: The try/package․lisp file
Lisp File, try/print.lisp: The try/print․lisp file
Lisp File, try/replay.lisp: The try/replay․lisp file
Lisp File, try/rerun.lisp: The try/rerun․lisp file
Lisp File, try/result.lisp: The try/result․lisp file
Lisp File, try/test.lisp: The try/test․lisp file
Lisp File, try/testable.lisp: The try/testable․lisp file
Lisp File, try/trial-event.lisp: The try/trial-event․lisp file
Lisp File, try/trial.lisp: The try/trial․lisp file
Lisp File, try/try.lisp: The try/try․lisp file
Lisp File, try/util.lisp: The try/util․lisp file

T
try.asd: The try․asd file
try.asdf.asd: The try․asdf․asd file
try.asdf/asdf.lisp: The try․asdf/asdf․lisp file
try/checks.lisp: The try/checks․lisp file
try/collect.lisp: The try/collect․lisp file
try/count.lisp: The try/count․lisp file
try/debug.lisp: The try/debug․lisp file
try/early.lisp: The try/early․lisp file
try/error.lisp: The try/error․lisp file
try/events.lisp: The try/events․lisp file
try/floats.lisp: The try/floats․lisp file
try/gray-stream.lisp: The try/gray-stream․lisp file
try/is.lisp: The try/is․lisp file
try/manual.lisp: The try/manual․lisp file
try/outcome.lisp: The try/outcome․lisp file
try/package.lisp: The try/package․lisp file
try/print.lisp: The try/print․lisp file
try/replay.lisp: The try/replay․lisp file
try/rerun.lisp: The try/rerun․lisp file
try/result.lisp: The try/result․lisp file
try/test.lisp: The try/test․lisp file
try/testable.lisp: The try/testable․lisp file
try/trial-event.lisp: The try/trial-event․lisp file
try/trial.lisp: The try/trial․lisp file
try/try.lisp: The try/try․lisp file
try/util.lisp: The try/util․lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   R   S   T   V   W  
Index Entry  Section

%
%%write-result-msg: Internal functions
%collector-collect-type: Internal functions
%collector-count-type: Internal functions
%collector-p: Internal functions
%count-and-collect-event: Internal functions
%describe-condition-for-matching: Internal functions
%ensure-new-line: Internal functions
%ensure-trial-printed: Internal functions
%extract-options: Internal functions
%frob-form-for-printing: Internal functions
%make-counter: Internal functions
%make-indent: Internal functions
%make-rerun-trial-event-handler: Internal functions
%match-condition: Internal functions
%maybe-invoke-debugger: Internal functions
%print-event: Internal functions
%print-indent-for: Internal functions
%print-leaf: Internal functions
%print-verdict: Internal functions
%replay-events: Internal functions
%replay-trial-initargs: Internal functions
%subs-to-bindings: Internal functions
%subs-to-captures: Internal functions
%trial-basic-verdict: Internal functions
%unwind-protect: Internal macros
%wrap-restart-bind-binding-in-lambda: Internal functions
%wrap-restart-bind-option-in-lambda: Internal functions
%wrap-restart-case-binding-in-lambda: Internal functions
%wrap-restart-case-option-in-lambda: Internal functions
%write-result: Internal functions
%write-result-captures: Internal functions
%write-result-ctx: Internal functions
%write-result-msg: Internal functions

(
(setf %collector-collect-type): Internal functions
(setf %collector-count-type): Internal functions
(setf abort-restart): Internal generic functions
(setf abort-restart): Internal generic functions
(setf capture-explicitp): Internal functions
(setf capture-subform): Internal functions
(setf capture-value): Internal functions
(setf capture-valuesp): Internal functions
(setf column): Internal generic functions
(setf column): Internal generic functions
(setf counter-categories): Internal functions
(setf counter-counts): Internal functions
(setf how-to-end): Internal generic functions
(setf how-to-end): Internal generic functions
(setf line): Internal generic functions
(setf line): Internal generic functions
(setf print-form-memoization-data): Internal generic functions
(setf print-form-memoization-data): Internal generic functions
(setf print-state-first-line-and-column): Internal functions
(setf print-state-n-retries): Internal functions
(setf print-state-trial): Internal functions
(setf retry-restart): Internal generic functions
(setf retry-restart): Internal generic functions
(setf skip-restart): Internal generic functions
(setf skip-restart): Internal generic functions
(setf sub-new-form): Exported functions
(setf sub-subform): Exported functions
(setf sub-valuesp): Exported functions
(setf sub-var): Exported functions
(setf to-be-described): Internal generic functions
(setf to-be-described): Internal generic functions

A
abort-check: Exported functions
abort-restart: Internal generic functions
abort-restart: Internal generic functions
abort-trial: Exported functions
add-to-counter: Internal functions
add-to-recent-trials: Internal functions
ancestor-trial-names: Internal functions
ancestors-from-oldest: Internal functions
ascii-std-categories: Exported functions

B
backtrace-of: Exported generic functions
backtrace-of: Exported generic functions
bool=: Internal functions
bump-counter: Internal functions

C
call-lambda-trial: Internal functions
call-named-trial: Internal functions
call-test: Internal functions
call-testable: Internal functions
call-trial: Internal functions
call-try-trial: Internal functions
call-with-wrapper: Internal functions
canonicalize-format-specifier-form: Exported functions
capture: Exported macros
capture-explicitp: Internal functions
capture-subform: Internal functions
capture-value: Internal functions
capture-values: Exported macros
capture-valuesp: Internal functions
captures: Internal generic functions
captures: Internal generic functions
categories: Internal generic functions
categories: Internal generic functions
category-marker: Internal functions
cform: Internal generic functions
cform: Internal generic functions
check: Internal generic functions
check: Internal generic functions
check-event-type: Internal functions
check-fails: Internal functions
check-invokes-debugger: Internal functions
check-invokes-debugger-not: Internal functions
check-printer-arg: Internal functions
check-signals: Internal functions
check-signals-not: Internal functions
check-trial-running: Internal functions
child-trials: Internal functions
children: Exported generic functions
children: Exported generic functions
clean-up-cancelled-nlx-of-retry-for-end-trial: Internal functions
clear-trial-restarts: Internal functions
column: Internal generic functions
column: Internal generic functions
combine-superclasses: Internal functions
compile-wrapper: Exported functions
compiler-policy: Internal functions
compiler-policy-quantity: Internal functions
condition-match-checker: Internal macros
constantishp: Internal functions
copy-%collector: Internal functions
copy-capture: Internal functions
copy-counter: Internal functions
copy-print-state: Internal functions
copy-sub: Internal functions
count-and-collect-leaf: Internal functions
count-and-collect-verdict: Internal functions
count-collected-leaf: Internal functions
count-collected-verdict: Internal functions
count-non-collected-leaf: Internal functions
count-non-collected-verdict: Internal functions
count-of: Internal generic functions
count-of: Internal generic functions
count-trial-start: Internal functions
counter: Internal generic functions
counter: Internal generic functions
counter-categories: Internal functions
counter-counts: Internal functions
counter-p: Internal functions
ctx: Internal generic functions
ctx: Internal generic functions
current-trial: Exported functions

D
dbg: Internal macros
debugger-invoked-p: Exported generic functions
debugger-invoked-p: Exported generic functions
defer-describe: Internal generic functions
defer-describe: Internal generic functions
define-combi-event: Internal macros
define-macrolet: Internal macros
deftest: Exported macros
deftest-registry-var-name: Internal functions
depth: Internal generic functions
depth: Internal generic functions
describe-condition: Internal functions
describe-leaf: Internal generic functions
describe-leaf: Internal generic functions
describe-to-be-described: Internal functions
describe-type: Internal generic functions
describe-type: Internal generic functions
determine-outcome-type: Internal functions
different-elements: Exported functions
double-float-~=: Internal functions

E
elapsed-seconds: Internal generic functions
elapsed-seconds: Internal generic functions
elapsed-seconds: Internal generic functions
elapsed-seconds: Internal generic functions
end-trial: Internal functions
ensure-deftest-registry: Internal functions
ensure-list: Internal functions
ensure-rest-arg: Internal functions
event-category: Internal functions
event-print-depth: Internal functions
expand-with-trial-in-deftest-p: Internal functions
extra-message: Internal generic functions
extra-message: Internal generic functions

F
failedp: Exported functions
fails: Exported macros
fancy-std-categories: Exported functions
finish-printing: Internal generic functions
finish-printing: Internal generic functions
finish-printing: Internal generic functions
float-~<: Exported functions
float-~=: Exported functions
float-~>: Exported functions
force-expected-failure: Exported functions
force-expected-success: Exported functions
force-unexpected-failure: Exported functions
force-unexpected-success: Exported functions
Function, %%write-result-msg: Internal functions
Function, %collector-collect-type: Internal functions
Function, %collector-count-type: Internal functions
Function, %collector-p: Internal functions
Function, %count-and-collect-event: Internal functions
Function, %describe-condition-for-matching: Internal functions
Function, %ensure-new-line: Internal functions
Function, %ensure-trial-printed: Internal functions
Function, %extract-options: Internal functions
Function, %frob-form-for-printing: Internal functions
Function, %make-counter: Internal functions
Function, %make-indent: Internal functions
Function, %make-rerun-trial-event-handler: Internal functions
Function, %match-condition: Internal functions
Function, %maybe-invoke-debugger: Internal functions
Function, %print-event: Internal functions
Function, %print-indent-for: Internal functions
Function, %print-leaf: Internal functions
Function, %print-verdict: Internal functions
Function, %replay-events: Internal functions
Function, %replay-trial-initargs: Internal functions
Function, %subs-to-bindings: Internal functions
Function, %subs-to-captures: Internal functions
Function, %trial-basic-verdict: Internal functions
Function, %wrap-restart-bind-binding-in-lambda: Internal functions
Function, %wrap-restart-bind-option-in-lambda: Internal functions
Function, %wrap-restart-case-binding-in-lambda: Internal functions
Function, %wrap-restart-case-option-in-lambda: Internal functions
Function, %write-result: Internal functions
Function, %write-result-captures: Internal functions
Function, %write-result-ctx: Internal functions
Function, %write-result-msg: Internal functions
Function, (setf %collector-collect-type): Internal functions
Function, (setf %collector-count-type): Internal functions
Function, (setf capture-explicitp): Internal functions
Function, (setf capture-subform): Internal functions
Function, (setf capture-value): Internal functions
Function, (setf capture-valuesp): Internal functions
Function, (setf counter-categories): Internal functions
Function, (setf counter-counts): Internal functions
Function, (setf print-state-first-line-and-column): Internal functions
Function, (setf print-state-n-retries): Internal functions
Function, (setf print-state-trial): Internal functions
Function, (setf sub-new-form): Exported functions
Function, (setf sub-subform): Exported functions
Function, (setf sub-valuesp): Exported functions
Function, (setf sub-var): Exported functions
Function, abort-check: Exported functions
Function, abort-trial: Exported functions
Function, add-to-counter: Internal functions
Function, add-to-recent-trials: Internal functions
Function, ancestor-trial-names: Internal functions
Function, ancestors-from-oldest: Internal functions
Function, ascii-std-categories: Exported functions
Function, bool=: Internal functions
Function, bump-counter: Internal functions
Function, call-lambda-trial: Internal functions
Function, call-named-trial: Internal functions
Function, call-test: Internal functions
Function, call-testable: Internal functions
Function, call-trial: Internal functions
Function, call-try-trial: Internal functions
Function, call-with-wrapper: Internal functions
Function, canonicalize-format-specifier-form: Exported functions
Function, capture-explicitp: Internal functions
Function, capture-subform: Internal functions
Function, capture-value: Internal functions
Function, capture-valuesp: Internal functions
Function, category-marker: Internal functions
Function, check-event-type: Internal functions
Function, check-fails: Internal functions
Function, check-invokes-debugger: Internal functions
Function, check-invokes-debugger-not: Internal functions
Function, check-printer-arg: Internal functions
Function, check-signals: Internal functions
Function, check-signals-not: Internal functions
Function, check-trial-running: Internal functions
Function, child-trials: Internal functions
Function, clean-up-cancelled-nlx-of-retry-for-end-trial: Internal functions
Function, clear-trial-restarts: Internal functions
Function, combine-superclasses: Internal functions
Function, compile-wrapper: Exported functions
Function, compiler-policy: Internal functions
Function, compiler-policy-quantity: Internal functions
Function, constantishp: Internal functions
Function, copy-%collector: Internal functions
Function, copy-capture: Internal functions
Function, copy-counter: Internal functions
Function, copy-print-state: Internal functions
Function, copy-sub: Internal functions
Function, count-and-collect-leaf: Internal functions
Function, count-and-collect-verdict: Internal functions
Function, count-collected-leaf: Internal functions
Function, count-collected-verdict: Internal functions
Function, count-non-collected-leaf: Internal functions
Function, count-non-collected-verdict: Internal functions
Function, count-trial-start: Internal functions
Function, counter-categories: Internal functions
Function, counter-counts: Internal functions
Function, counter-p: Internal functions
Function, current-trial: Exported functions
Function, deftest-registry-var-name: Internal functions
Function, describe-condition: Internal functions
Function, describe-to-be-described: Internal functions
Function, determine-outcome-type: Internal functions
Function, different-elements: Exported functions
Function, double-float-~=: Internal functions
Function, end-trial: Internal functions
Function, ensure-deftest-registry: Internal functions
Function, ensure-list: Internal functions
Function, ensure-rest-arg: Internal functions
Function, event-category: Internal functions
Function, event-print-depth: Internal functions
Function, expand-with-trial-in-deftest-p: Internal functions
Function, failedp: Exported functions
Function, fancy-std-categories: Exported functions
Function, float-~<: Exported functions
Function, float-~=: Exported functions
Function, float-~>: Exported functions
Function, force-expected-failure: Exported functions
Function, force-expected-success: Exported functions
Function, force-unexpected-failure: Exported functions
Function, force-unexpected-success: Exported functions
Function, get-deftest-registry: Internal functions
Function, get-elapsed-seconds: Internal functions
Function, intern-hyphenated: Internal functions
Function, invoke-test-interactively: Internal functions
Function, invokes-debugger-default-ctx: Internal functions
Function, invokes-debugger-default-msg: Internal functions
Function, invokes-debugger-not-default-msg: Internal functions
Function, lambda-list-to-arglist-form: Internal functions
Function, lambda-list-with-&rest-to-arglist-form: Internal functions
Function, lambda-trial-p: Internal functions
Function, list-function-designators: Internal functions
Function, list-package-tests: Exported functions
Function, make-%collector: Internal functions
Function, make-capture: Internal functions
Function, make-counter: Internal functions
Function, make-gensym: Internal functions
Function, make-print-state: Internal functions
Function, make-sub: Exported functions
Function, make-trial: Internal functions
Function, maybe-backtrace: Internal functions
Function, maybe-mark-test-run: Internal functions
Function, mismatch%: Exported functions
Function, named-trial-p: Internal functions
Function, passedp: Exported functions
Function, present-body: Internal functions
Function, print-duration: Internal functions
Function, print-event-header: Internal functions
Function, print-state-first-line-and-column: Internal functions
Function, print-state-n-retries: Internal functions
Function, print-state-p: Internal functions
Function, print-state-trial: Internal functions
Function, print-state-trial-printed-p: Internal functions
Function, printer-depth: Internal functions
Function, read-argument-list: Internal functions
Function, read-try-debug: Internal functions
Function, recent-trial: Exported functions
Function, record-event: Exported functions
Function, register-deftest: Internal functions
Function, replay-events: Exported functions
Function, report-change-outcome-to: Internal functions
Function, reset-counter: Internal functions
Function, retry-check: Exported functions
Function, retry-trial: Exported functions
Function, runningp: Exported functions
Function, safe-subtypep: Internal functions
Function, safe-typep: Internal functions
Function, same-but-different-implicit-captures-p: Internal functions
Function, say-how-to-end: Internal functions
Function, scrub-captures: Internal functions
Function, set-try-debug: Exported functions
Function, set-up-trial-restarts: Internal functions
Function, shuffle: Internal functions
Function, shuffle!: Internal functions
Function, shuffle-vector!: Internal functions
Function, signal-error*: Internal functions
Function, signal-outcome: Internal functions
Function, signal-with-record-event: Internal functions
Function, single-float-~=: Internal functions
Function, skip-check: Exported functions
Function, skip-trial: Exported functions
Function, start-retry-for-trial: Internal functions
Function, start-trial: Internal functions
Function, stream-line-column*: Internal functions
Function, strip-outer-%-and-%%-from-implicit-captures: Internal functions
Function, sub-new-form: Exported functions
Function, sub-p: Internal functions
Function, sub-subform: Exported functions
Function, sub-valuesp: Exported functions
Function, sub-var: Exported functions
Function, subseq*: Internal functions
Function, substitute-args: Internal functions
Function, substitute-in-subs: Internal functions
Function, substitute-is-form: Internal functions
Function, substitute-tilde-percent: Internal functions
Function, sync-stream-line-column: Internal functions
Function, test-bound-p: Exported functions
Function, trial-call-=: Internal functions
Function, trial-has-event-of-type-p: Internal functions
Function, trial-printed-p: Internal functions
Function, trialp: Internal functions
Function, try: Exported functions
Function, try-trial-p: Internal functions
Function, try-trial-testable: Internal functions
Function, try/implicit: Internal functions
Function, valid-type-specifier-p: Internal functions
Function, verdict-for-trial-p: Internal functions
Function, write-trial-counts: Internal functions

G
Generic Function, (setf abort-restart): Internal generic functions
Generic Function, (setf column): Internal generic functions
Generic Function, (setf how-to-end): Internal generic functions
Generic Function, (setf line): Internal generic functions
Generic Function, (setf print-form-memoization-data): Internal generic functions
Generic Function, (setf retry-restart): Internal generic functions
Generic Function, (setf skip-restart): Internal generic functions
Generic Function, (setf to-be-described): Internal generic functions
Generic Function, abort-restart: Internal generic functions
Generic Function, backtrace-of: Exported generic functions
Generic Function, captures: Internal generic functions
Generic Function, categories: Internal generic functions
Generic Function, cform: Internal generic functions
Generic Function, check: Internal generic functions
Generic Function, children: Exported generic functions
Generic Function, column: Internal generic functions
Generic Function, count-of: Internal generic functions
Generic Function, counter: Internal generic functions
Generic Function, ctx: Internal generic functions
Generic Function, debugger-invoked-p: Exported generic functions
Generic Function, defer-describe: Internal generic functions
Generic Function, depth: Internal generic functions
Generic Function, describe-leaf: Internal generic functions
Generic Function, describe-type: Internal generic functions
Generic Function, elapsed-seconds: Internal generic functions
Generic Function, extra-message: Internal generic functions
Generic Function, finish-printing: Internal generic functions
Generic Function, has-non-collected-failed-child-p: Internal generic functions
Generic Function, how-it-ended: Internal generic functions
Generic Function, how-to-end: Internal generic functions
Generic Function, indentation: Internal generic functions
Generic Function, inner-stream: Internal generic functions
Generic Function, line: Internal generic functions
Generic Function, msg: Internal generic functions
Generic Function, n-retries: Exported generic functions
Generic Function, nested-condition: Exported generic functions
Generic Function, nested-error: Internal generic functions
Generic Function, non-collected-counter: Internal generic functions
Generic Function, parent: Internal generic functions
Generic Function, print-captures: Internal generic functions
Generic Function, print-compactly: Internal generic functions
Generic Function, print-duration-p: Internal generic functions
Generic Function, print-event: Internal generic functions
Generic Function, print-form-memoization-data: Internal generic functions
Generic Function, print-parent: Internal generic functions
Generic Function, print-type: Internal generic functions
Generic Function, retry-restart: Internal generic functions
Generic Function, skip-restart: Internal generic functions
Generic Function, stream-column: Internal generic functions
Generic Function, stream-line: Internal generic functions
Generic Function, stream-of: Internal generic functions
Generic Function, substitute-is-list-form: Exported generic functions
Generic Function, test-name: Exported generic functions
Generic Function, to-be-described: Internal generic functions
Generic Function, trial: Exported generic functions
Generic Function, trial-print-states: Internal generic functions
Generic Function, trial-start: Exported generic functions
Generic Function, verdict: Exported generic functions
Generic Function, write-event: Internal generic functions
get-deftest-registry: Internal functions
get-elapsed-seconds: Internal functions

H
has-non-collected-failed-child-p: Internal generic functions
has-non-collected-failed-child-p: Internal generic functions
how-it-ended: Internal generic functions
how-it-ended: Internal generic functions
how-to-end: Internal generic functions
how-to-end: Internal generic functions

I
in-time: Exported macros
indentation: Internal generic functions
indentation: Internal generic functions
inner-stream: Internal generic functions
inner-stream: Internal generic functions
intern-hyphenated: Internal functions
invoke-test-interactively: Internal functions
invokes-debugger: Exported macros
invokes-debugger-default-ctx: Internal functions
invokes-debugger-default-msg: Internal functions
invokes-debugger-not: Exported macros
invokes-debugger-not-default-msg: Internal functions
is: Exported macros

L
lambda-list-to-arglist-form: Internal functions
lambda-list-with-&rest-to-arglist-form: Internal functions
lambda-trial-p: Internal functions
line: Internal generic functions
line: Internal generic functions
list-function-designators: Internal functions
list-package-tests: Exported functions

M
Macro, %unwind-protect: Internal macros
Macro, capture: Exported macros
Macro, capture-values: Exported macros
Macro, condition-match-checker: Internal macros
Macro, dbg: Internal macros
Macro, define-combi-event: Internal macros
Macro, define-macrolet: Internal macros
Macro, deftest: Exported macros
Macro, fails: Exported macros
Macro, in-time: Exported macros
Macro, invokes-debugger: Exported macros
Macro, invokes-debugger-not: Exported macros
Macro, is: Exported macros
Macro, match-values: Exported macros
Macro, match-values%: Internal macros
Macro, on-finish: Internal macros
Macro, on-nlx: Internal macros
Macro, on-return: Internal macros
Macro, on-values: Exported macros
Macro, remembering-most-recent-trials: Internal macros
Macro, restart-bind: Internal macros
Macro, restart-case: Internal macros
Macro, signals: Exported macros
Macro, signals-not: Exported macros
Macro, try-default-unspecified-args: Internal macros
Macro, warn-on-tests-not-run: Exported macros
Macro, with-bindings: Internal macros
Macro, with-circularity-detection: Internal macros
Macro, with-condition-matching: Internal macros
Macro, with-current-debug: Internal macros
Macro, with-debugger-hook: Internal macros
Macro, with-debugger-hook-form: Internal macros
Macro, with-error*-handled: Internal macros
Macro, with-expected-outcome: Exported macros
Macro, with-failure-expected: Exported macros
Macro, with-gensyms: Internal macros
Macro, with-internal-errors: Internal macros
Macro, with-retry: Internal macros
Macro, with-retry/catch: Internal macros
Macro, with-shuffling: Exported macros
Macro, with-skip: Exported macros
Macro, with-test: Exported macros
Macro, with-tests-run: Exported macros
Macro, with-timing: Internal macros
Macro, with-trial: Internal macros
Macro, with-trial-restarts: Internal macros
Macro, with-try-context: Internal macros
Macro, without-tail-call: Internal macros
Macro, wrap-trial-body-for-return: Internal macros
make-%collector: Internal functions
make-capture: Internal functions
make-counter: Internal functions
make-gensym: Internal functions
make-print-state: Internal functions
make-sub: Exported functions
make-trial: Internal functions
match-values: Exported macros
match-values%: Internal macros
maybe-backtrace: Internal functions
maybe-mark-test-run: Internal functions
Method, (setf abort-restart): Internal generic functions
Method, (setf column): Internal generic functions
Method, (setf how-to-end): Internal generic functions
Method, (setf line): Internal generic functions
Method, (setf print-form-memoization-data): Internal generic functions
Method, (setf retry-restart): Internal generic functions
Method, (setf skip-restart): Internal generic functions
Method, (setf to-be-described): Internal generic functions
Method, abort-restart: Internal generic functions
Method, backtrace-of: Exported generic functions
Method, captures: Internal generic functions
Method, categories: Internal generic functions
Method, cform: Internal generic functions
Method, check: Internal generic functions
Method, children: Exported generic functions
Method, column: Internal generic functions
Method, count-of: Internal generic functions
Method, counter: Internal generic functions
Method, ctx: Internal generic functions
Method, debugger-invoked-p: Exported generic functions
Method, defer-describe: Internal generic functions
Method, depth: Internal generic functions
Method, describe-leaf: Internal generic functions
Method, describe-type: Internal generic functions
Method, elapsed-seconds: Internal generic functions
Method, elapsed-seconds: Internal generic functions
Method, elapsed-seconds: Internal generic functions
Method, extra-message: Internal generic functions
Method, finish-printing: Internal generic functions
Method, finish-printing: Internal generic functions
Method, has-non-collected-failed-child-p: Internal generic functions
Method, how-it-ended: Internal generic functions
Method, how-to-end: Internal generic functions
Method, indentation: Internal generic functions
Method, inner-stream: Internal generic functions
Method, line: Internal generic functions
Method, msg: Internal generic functions
Method, n-retries: Exported generic functions
Method, nested-condition: Exported generic functions
Method, nested-error: Internal generic functions
Method, non-collected-counter: Internal generic functions
Method, parent: Internal generic functions
Method, print-captures: Internal generic functions
Method, print-compactly: Internal generic functions
Method, print-duration-p: Internal generic functions
Method, print-event: Internal generic functions
Method, print-event: Internal generic functions
Method, print-event: Internal generic functions
Method, print-form-memoization-data: Internal generic functions
Method, print-parent: Internal generic functions
Method, print-type: Internal generic functions
Method, retry-restart: Internal generic functions
Method, skip-restart: Internal generic functions
Method, stream-column: Internal generic functions
Method, stream-line: Internal generic functions
Method, stream-of: Internal generic functions
Method, substitute-is-list-form: Exported generic functions
Method, substitute-is-list-form: Exported generic functions
Method, substitute-is-list-form: Exported generic functions
Method, substitute-is-list-form: Exported generic functions
Method, substitute-is-list-form: Exported generic functions
Method, test-name: Exported generic functions
Method, test-name: Exported generic functions
Method, to-be-described: Internal generic functions
Method, trial: Exported generic functions
Method, trial-print-states: Internal generic functions
Method, trial-start: Exported generic functions
Method, verdict: Exported generic functions
Method, write-event: Internal generic functions
Method, write-event: Internal generic functions
Method, write-event: Internal generic functions
Method, write-event: Internal generic functions
Method, write-event: Internal generic functions
Method, write-event: Internal generic functions
mismatch%: Exported functions
msg: Internal generic functions
msg: Internal generic functions

N
n-retries: Exported generic functions
n-retries: Exported generic functions
named-trial-p: Internal functions
nested-condition: Exported generic functions
nested-condition: Exported generic functions
nested-error: Internal generic functions
nested-error: Internal generic functions
non-collected-counter: Internal generic functions
non-collected-counter: Internal generic functions

O
on-finish: Internal macros
on-nlx: Internal macros
on-return: Internal macros
on-values: Exported macros

P
parent: Internal generic functions
parent: Internal generic functions
passedp: Exported functions
present-body: Internal functions
print-captures: Internal generic functions
print-captures: Internal generic functions
print-compactly: Internal generic functions
print-compactly: Internal generic functions
print-duration: Internal functions
print-duration-p: Internal generic functions
print-duration-p: Internal generic functions
print-event: Internal generic functions
print-event: Internal generic functions
print-event: Internal generic functions
print-event: Internal generic functions
print-event-header: Internal functions
print-form-memoization-data: Internal generic functions
print-form-memoization-data: Internal generic functions
print-parent: Internal generic functions
print-parent: Internal generic functions
print-state-first-line-and-column: Internal functions
print-state-n-retries: Internal functions
print-state-p: Internal functions
print-state-trial: Internal functions
print-state-trial-printed-p: Internal functions
print-type: Internal generic functions
print-type: Internal generic functions
printer-depth: Internal functions

R
read-argument-list: Internal functions
read-try-debug: Internal functions
recent-trial: Exported functions
record-event: Exported functions
register-deftest: Internal functions
remembering-most-recent-trials: Internal macros
replay-events: Exported functions
report-change-outcome-to: Internal functions
reset-counter: Internal functions
restart-bind: Internal macros
restart-case: Internal macros
retry-check: Exported functions
retry-restart: Internal generic functions
retry-restart: Internal generic functions
retry-trial: Exported functions
runningp: Exported functions

S
safe-subtypep: Internal functions
safe-typep: Internal functions
same-but-different-implicit-captures-p: Internal functions
say-how-to-end: Internal functions
scrub-captures: Internal functions
set-try-debug: Exported functions
set-up-trial-restarts: Internal functions
shuffle: Internal functions
shuffle!: Internal functions
shuffle-vector!: Internal functions
signal-error*: Internal functions
signal-outcome: Internal functions
signal-with-record-event: Internal functions
signals: Exported macros
signals-not: Exported macros
single-float-~=: Internal functions
skip-check: Exported functions
skip-restart: Internal generic functions
skip-restart: Internal generic functions
skip-trial: Exported functions
start-retry-for-trial: Internal functions
start-trial: Internal functions
stream-column: Internal generic functions
stream-column: Internal generic functions
stream-line: Internal generic functions
stream-line: Internal generic functions
stream-line-column*: Internal functions
stream-of: Internal generic functions
stream-of: Internal generic functions
strip-outer-%-and-%%-from-implicit-captures: Internal functions
sub-new-form: Exported functions
sub-p: Internal functions
sub-subform: Exported functions
sub-valuesp: Exported functions
sub-var: Exported functions
subseq*: Internal functions
substitute-args: Internal functions
substitute-in-subs: Internal functions
substitute-is-form: Internal functions
substitute-is-list-form: Exported generic functions
substitute-is-list-form: Exported generic functions
substitute-is-list-form: Exported generic functions
substitute-is-list-form: Exported generic functions
substitute-is-list-form: Exported generic functions
substitute-is-list-form: Exported generic functions
substitute-tilde-percent: Internal functions
sync-stream-line-column: Internal functions

T
test-bound-p: Exported functions
test-name: Exported generic functions
test-name: Exported generic functions
test-name: Exported generic functions
to-be-described: Internal generic functions
to-be-described: Internal generic functions
trial: Exported generic functions
trial: Exported generic functions
trial-call-=: Internal functions
trial-has-event-of-type-p: Internal functions
trial-print-states: Internal generic functions
trial-print-states: Internal generic functions
trial-printed-p: Internal functions
trial-start: Exported generic functions
trial-start: Exported generic functions
trialp: Internal functions
try: Exported functions
try-default-unspecified-args: Internal macros
try-trial-p: Internal functions
try-trial-testable: Internal functions
try/implicit: Internal functions

V
valid-type-specifier-p: Internal functions
verdict: Exported generic functions
verdict: Exported generic functions
verdict-for-trial-p: Internal functions

W
warn-on-tests-not-run: Exported macros
with-bindings: Internal macros
with-circularity-detection: Internal macros
with-condition-matching: Internal macros
with-current-debug: Internal macros
with-debugger-hook: Internal macros
with-debugger-hook-form: Internal macros
with-error*-handled: Internal macros
with-expected-outcome: Exported macros
with-failure-expected: Exported macros
with-gensyms: Internal macros
with-internal-errors: Internal macros
with-retry: Internal macros
with-retry/catch: Internal macros
with-shuffling: Exported macros
with-skip: Exported macros
with-test: Exported macros
with-tests-run: Exported macros
with-timing: Internal macros
with-trial: Internal macros
with-trial-restarts: Internal macros
with-try-context: Internal macros
without-tail-call: Internal macros
wrap-trial-body-for-return: Internal macros
write-event: Internal generic functions
write-event: Internal generic functions
write-event: Internal generic functions
write-event: Internal generic functions
write-event: Internal generic functions
write-event: Internal generic functions
write-event: Internal generic functions
write-trial-counts: Internal functions

Jump to:   %   (  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   R   S   T   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   !   *   @  
A   B   C   D   E   F   H   I   L   M   N   P   R   S   T   V  
Index Entry  Section

!
!: Exported special variables
!!: Exported special variables
!!!: Exported special variables

*
*best-matching-condition*: Exported special variables
*call-test*: Internal special variables
*call-test-fn*: Internal special variables
*categories*: Exported special variables
*collect*: Exported special variables
*condition-matched-p*: Exported special variables
*count*: Exported special variables
*dbg*: Internal special variables
*debug*: Exported special variables
*defer-describe*: Exported special variables
*describe*: Exported special variables
*dummy*: Internal special variables
*event-print-bindings*: Exported special variables
*expected-outcome*: Internal special variables
*gather-backtrace*: Exported special variables
*in-time-elapsed-seconds*: Exported special variables
*internal-error*: Internal special variables
*invoking-debugger*: Internal special variables
*is-captures*: Exported special variables
*is-form*: Exported special variables
*max-diff-in-ulp*: Exported special variables
*max-diff-in-value*: Exported special variables
*n-recent-trials*: Exported special variables
*print*: Exported special variables
*print-backtrace*: Internal special variables
*print-compactly*: Exported special variables
*print-duration*: Exported special variables
*print-indentation*: Exported special variables
*print-parent*: Exported special variables
*printer*: Exported special variables
*recent-trials*: Internal special variables
*record-event*: Internal special variables
*rerun*: Exported special variables
*run-deftest-when*: Exported special variables
*skip*: Internal special variables
*start-time*: Internal special variables
*stream*: Exported special variables
*testing-timing*: Internal special variables
*tests-run*: Internal special variables
*trial*: Internal special variables
*trial-initargs*: Internal special variables
*try-collect*: Exported special variables
*try-count*: Exported special variables
*try-debug*: Exported special variables
*try-describe*: Exported special variables
*try-id*: Internal special variables
*try-print*: Exported special variables
*try-printer*: Exported special variables
*try-rerun*: Exported special variables
*try-stream*: Exported special variables

@
@cancelled-nlx: Internal special variables
@funcallable-instance: Internal special variables
@function-designator: Internal special variables
@non-local-exit: Internal special variables
@try-manual: Exported special variables
@try/automatic-captures: Exported special variables
@try/captures: Exported special variables
@try/categories: Exported special variables
@try/check-library: Exported special variables
@try/check-restarts: Exported special variables
@try/check-utilities: Exported special variables
@try/checking-conditions: Exported special variables
@try/checks: Exported special variables
@try/collect: Exported special variables
@try/comparing-floats: Exported special variables
@try/concrete-events: Exported special variables
@try/count: Exported special variables
@try/errors: Exported special variables
@try/event-glue: Exported special variables
@try/event-restarts: Exported special variables
@try/events: Exported special variables
@try/explicit-captures: Exported special variables
@try/explicit-try: Exported special variables
@try/format-specifier-forms: Exported special variables
@try/glossary: Exported special variables
@try/implementation-notes: Exported special variables
@try/implicit-try: Exported special variables
@try/implicit-try-implementation: Exported special variables
@try/is: Exported special variables
@try/links: Exported special variables
@try/middle-layer-of-events: Exported special variables
@try/misc-checks: Exported special variables
@try/outcome-restarts: Exported special variables
@try/outcomes: Exported special variables
@try/print: Exported special variables
@try/printing-events: Exported special variables
@try/replay: Exported special variables
@try/rerun: Exported special variables
@try/testables: Exported special variables
@try/tests: Exported special variables
@try/trial-events: Exported special variables
@try/trial-restarts: Exported special variables
@try/trial-verdicts: Exported special variables
@try/trials: Exported special variables
@try/tutorial: Exported special variables
@try/writing-automatic-capture-rules: Exported special variables

A
abort-restart: Exported classes

B
backtrace: Exported conditions

C
captures: Exported conditions
categories: Exported classes
categories: Internal structures
cform: Exported classes
check: Exported conditions
children: Exported classes
collect-type: Internal structures
column: Internal classes
count: Exported classes
count-type: Internal structures
counter: Exported classes
counts: Internal structures
ctx: Exported conditions

D
debugger-invoked-p: Exported conditions
defer-describe: Exported classes
depth: Exported classes
describe-type: Internal classes

E
elapsed-seconds: Exported conditions
elapsed-seconds: Exported conditions
elapsed-seconds: Exported classes
error: Internal conditions
extra-message: Exported conditions

F
first-line-and-column: Internal structures
fn: Internal classes

H
has-non-collected-failed-child-p: Exported classes
how-it-ended: Exported classes
how-to-end: Exported classes

I
indentation: Exported classes
inner-stream: Internal classes

L
line: Internal classes

M
msg: Exported conditions

N
n-retries: Exported classes
n-retries: Internal structures
nested-condition: Exported conditions
new-form: Exported structures
non-collected-counter: Exported classes

P
parent: Exported classes
print-captures: Exported conditions
print-compactly: Exported classes
print-duration-p: Exported classes
print-form-memoization-data: Exported conditions
print-parent: Internal classes
print-type: Internal classes

R
retry-restart: Exported classes

S
skip-restart: Exported classes
Slot, abort-restart: Exported classes
Slot, backtrace: Exported conditions
Slot, captures: Exported conditions
Slot, categories: Exported classes
Slot, categories: Internal structures
Slot, cform: Exported classes
Slot, check: Exported conditions
Slot, children: Exported classes
Slot, collect-type: Internal structures
Slot, column: Internal classes
Slot, count: Exported classes
Slot, count-type: Internal structures
Slot, counter: Exported classes
Slot, counts: Internal structures
Slot, ctx: Exported conditions
Slot, debugger-invoked-p: Exported conditions
Slot, defer-describe: Exported classes
Slot, depth: Exported classes
Slot, describe-type: Internal classes
Slot, elapsed-seconds: Exported conditions
Slot, elapsed-seconds: Exported conditions
Slot, elapsed-seconds: Exported classes
Slot, error: Internal conditions
Slot, extra-message: Exported conditions
Slot, first-line-and-column: Internal structures
Slot, fn: Internal classes
Slot, has-non-collected-failed-child-p: Exported classes
Slot, how-it-ended: Exported classes
Slot, how-to-end: Exported classes
Slot, indentation: Exported classes
Slot, inner-stream: Internal classes
Slot, line: Internal classes
Slot, msg: Exported conditions
Slot, n-retries: Exported classes
Slot, n-retries: Internal structures
Slot, nested-condition: Exported conditions
Slot, new-form: Exported structures
Slot, non-collected-counter: Exported classes
Slot, parent: Exported classes
Slot, print-captures: Exported conditions
Slot, print-compactly: Exported classes
Slot, print-duration-p: Exported classes
Slot, print-form-memoization-data: Exported conditions
Slot, print-parent: Internal classes
Slot, print-type: Internal classes
Slot, retry-restart: Exported classes
Slot, skip-restart: Exported classes
Slot, stream: Internal classes
Slot, subform: Exported structures
Slot, test-name: Exported conditions
Slot, test-name: Exported classes
Slot, to-be-described: Exported classes
Slot, trial: Exported conditions
Slot, trial: Internal structures
Slot, trial-print-states: Internal classes
Slot, trial-start: Exported classes
Slot, valuesp: Exported structures
Slot, var: Exported structures
Slot, variable-bindings: Internal classes
Slot, verdict: Exported classes
Special Variable, !: Exported special variables
Special Variable, !!: Exported special variables
Special Variable, !!!: Exported special variables
Special Variable, *best-matching-condition*: Exported special variables
Special Variable, *call-test*: Internal special variables
Special Variable, *call-test-fn*: Internal special variables
Special Variable, *categories*: Exported special variables
Special Variable, *collect*: Exported special variables
Special Variable, *condition-matched-p*: Exported special variables
Special Variable, *count*: Exported special variables
Special Variable, *dbg*: Internal special variables
Special Variable, *debug*: Exported special variables
Special Variable, *defer-describe*: Exported special variables
Special Variable, *describe*: Exported special variables
Special Variable, *dummy*: Internal special variables
Special Variable, *event-print-bindings*: Exported special variables
Special Variable, *expected-outcome*: Internal special variables
Special Variable, *gather-backtrace*: Exported special variables
Special Variable, *in-time-elapsed-seconds*: Exported special variables
Special Variable, *internal-error*: Internal special variables
Special Variable, *invoking-debugger*: Internal special variables
Special Variable, *is-captures*: Exported special variables
Special Variable, *is-form*: Exported special variables
Special Variable, *max-diff-in-ulp*: Exported special variables
Special Variable, *max-diff-in-value*: Exported special variables
Special Variable, *n-recent-trials*: Exported special variables
Special Variable, *print*: Exported special variables
Special Variable, *print-backtrace*: Internal special variables
Special Variable, *print-compactly*: Exported special variables
Special Variable, *print-duration*: Exported special variables
Special Variable, *print-indentation*: Exported special variables
Special Variable, *print-parent*: Exported special variables
Special Variable, *printer*: Exported special variables
Special Variable, *recent-trials*: Internal special variables
Special Variable, *record-event*: Internal special variables
Special Variable, *rerun*: Exported special variables
Special Variable, *run-deftest-when*: Exported special variables
Special Variable, *skip*: Internal special variables
Special Variable, *start-time*: Internal special variables
Special Variable, *stream*: Exported special variables
Special Variable, *testing-timing*: Internal special variables
Special Variable, *tests-run*: Internal special variables
Special Variable, *trial*: Internal special variables
Special Variable, *trial-initargs*: Internal special variables
Special Variable, *try-collect*: Exported special variables
Special Variable, *try-count*: Exported special variables
Special Variable, *try-debug*: Exported special variables
Special Variable, *try-describe*: Exported special variables
Special Variable, *try-id*: Internal special variables
Special Variable, *try-print*: Exported special variables
Special Variable, *try-printer*: Exported special variables
Special Variable, *try-rerun*: Exported special variables
Special Variable, *try-stream*: Exported special variables
Special Variable, @cancelled-nlx: Internal special variables
Special Variable, @funcallable-instance: Internal special variables
Special Variable, @function-designator: Internal special variables
Special Variable, @non-local-exit: Internal special variables
Special Variable, @try-manual: Exported special variables
Special Variable, @try/automatic-captures: Exported special variables
Special Variable, @try/captures: Exported special variables
Special Variable, @try/categories: Exported special variables
Special Variable, @try/check-library: Exported special variables
Special Variable, @try/check-restarts: Exported special variables
Special Variable, @try/check-utilities: Exported special variables
Special Variable, @try/checking-conditions: Exported special variables
Special Variable, @try/checks: Exported special variables
Special Variable, @try/collect: Exported special variables
Special Variable, @try/comparing-floats: Exported special variables
Special Variable, @try/concrete-events: Exported special variables
Special Variable, @try/count: Exported special variables
Special Variable, @try/errors: Exported special variables
Special Variable, @try/event-glue: Exported special variables
Special Variable, @try/event-restarts: Exported special variables
Special Variable, @try/events: Exported special variables
Special Variable, @try/explicit-captures: Exported special variables
Special Variable, @try/explicit-try: Exported special variables
Special Variable, @try/format-specifier-forms: Exported special variables
Special Variable, @try/glossary: Exported special variables
Special Variable, @try/implementation-notes: Exported special variables
Special Variable, @try/implicit-try: Exported special variables
Special Variable, @try/implicit-try-implementation: Exported special variables
Special Variable, @try/is: Exported special variables
Special Variable, @try/links: Exported special variables
Special Variable, @try/middle-layer-of-events: Exported special variables
Special Variable, @try/misc-checks: Exported special variables
Special Variable, @try/outcome-restarts: Exported special variables
Special Variable, @try/outcomes: Exported special variables
Special Variable, @try/print: Exported special variables
Special Variable, @try/printing-events: Exported special variables
Special Variable, @try/replay: Exported special variables
Special Variable, @try/rerun: Exported special variables
Special Variable, @try/testables: Exported special variables
Special Variable, @try/tests: Exported special variables
Special Variable, @try/trial-events: Exported special variables
Special Variable, @try/trial-restarts: Exported special variables
Special Variable, @try/trial-verdicts: Exported special variables
Special Variable, @try/trials: Exported special variables
Special Variable, @try/tutorial: Exported special variables
Special Variable, @try/writing-automatic-capture-rules: Exported special variables
stream: Internal classes
subform: Exported structures

T
test-name: Exported conditions
test-name: Exported classes
to-be-described: Exported classes
trial: Exported conditions
trial: Internal structures
trial-print-states: Internal classes
trial-start: Exported classes

V
valuesp: Exported structures
var: Exported structures
variable-bindings: Internal classes
verdict: Exported classes

Jump to:   !   *   @  
A   B   C   D   E   F   H   I   L   M   N   P   R   S   T   V  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   %  
A   B   C   D   E   F   L   N   O   P   R   S   T   U   V   W  
Index Entry  Section

%
%collector: Internal structures

A
abort*: Exported conditions

B
basic-error*-outcome: Internal types
basic-outcome: Internal types

C
Class, dummy-with-print-object: Internal classes
Class, line/column-character-output-stream: Internal classes
Class, printer: Internal classes
Class, tree-printer: Exported classes
Class, trial: Exported classes
Class, wrapped-stream: Internal classes
Condition, abort*: Exported conditions
Condition, dismissal: Exported conditions
Condition, error*: Exported conditions
Condition, event: Exported conditions
Condition, expected: Exported conditions
Condition, expected-result-failure: Exported conditions
Condition, expected-result-success: Exported conditions
Condition, expected-verdict-failure: Exported conditions
Condition, expected-verdict-success: Exported conditions
Condition, failure: Exported conditions
Condition, leaf: Exported conditions
Condition, nlx: Exported conditions
Condition, outcome: Exported conditions
Condition, result: Exported conditions
Condition, result-abort*: Exported conditions
Condition, result-failure: Internal conditions
Condition, result-skip: Exported conditions
Condition, result-success: Internal conditions
Condition, skip: Exported conditions
Condition, success: Exported conditions
Condition, trial-event: Exported conditions
Condition, trial-start: Exported conditions
Condition, try-internal-error: Internal conditions
Condition, unexpected: Exported conditions
Condition, unexpected-result-failure: Exported conditions
Condition, unexpected-result-success: Exported conditions
Condition, unexpected-verdict-failure: Exported conditions
Condition, unexpected-verdict-success: Exported conditions
Condition, unhandled-error: Exported conditions
Condition, verdict: Exported conditions
Condition, verdict-abort*: Exported conditions
Condition, verdict-failure: Internal conditions
Condition, verdict-skip: Exported conditions
Condition, verdict-success: Internal conditions
counter: Internal structures

D
dismissal: Exported conditions
dummy-with-print-object: Internal classes

E
error*: Exported conditions
event: Exported conditions
expected: Exported conditions
expected-failure: Exported types
expected-result-failure: Exported conditions
expected-result-success: Exported conditions
expected-success: Exported types
expected-verdict-failure: Exported conditions
expected-verdict-success: Exported conditions

F
fail: Exported types
failure: Exported conditions

L
leaf: Exported conditions
line/column-character-output-stream: Internal classes

N
nlx: Exported conditions

O
outcome: Exported conditions

P
Package, try: The try package
Package, try/asdf: The try/asdf package
pass: Exported types
print-state: Internal structures
printer: Internal classes

R
result: Exported conditions
result-abort*: Exported conditions
result-failure: Internal conditions
result-skip: Exported conditions
result-success: Internal conditions

S
skip: Exported conditions
Structure, %collector: Internal structures
Structure, counter: Internal structures
Structure, print-state: Internal structures
Structure, sub: Exported structures
sub: Exported structures
success: Exported conditions
System, try: The try system
System, try.asdf: The try․asdf system

T
tree-printer: Exported classes
trial: Exported classes
trial-event: Exported conditions
trial-start: Exported conditions
try: The try system
try: The try package
try-internal-error: Internal conditions
try.asdf: The try․asdf system
try/asdf: The try/asdf package
Type, basic-error*-outcome: Internal types
Type, basic-outcome: Internal types
Type, expected-failure: Exported types
Type, expected-success: Exported types
Type, fail: Exported types
Type, pass: Exported types
Type, unexpected-failure: Exported types
Type, unexpected-success: Exported types
Type, valid-type-specifier: Internal types

U
unexpected: Exported conditions
unexpected-failure: Exported types
unexpected-result-failure: Exported conditions
unexpected-result-success: Exported conditions
unexpected-success: Exported types
unexpected-verdict-failure: Exported conditions
unexpected-verdict-success: Exported conditions
unhandled-error: Exported conditions

V
valid-type-specifier: Internal types
verdict: Exported conditions
verdict-abort*: Exported conditions
verdict-failure: Internal conditions
verdict-skip: Exported conditions
verdict-success: Internal conditions

W
wrapped-stream: Internal classes

Jump to:   %  
A   B   C   D   E   F   L   N   O   P   R   S   T   U   V   W