Parachute

https://shinmera.github.io/parachute/
Admin
Parachute is an extensible and cross-compatible testing framework for Common Lisp with support for...
Tokens:13,976
Snippets:158
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### WITH-FIXTURES

Source: https://shinmera.github.io/parachute

Shorthand macro to evaluate the body with the fixtures saved away.

```APIDOC
## WITH-FIXTURES

### Description
Shorthand macro to evaluate the body with the fixtures saved away.

### Parameters
- **FIXTURES** - Required
- **BODY** - Required
```

--------------------------------

### PACKAGE-FIXTURES Function

Source: https://shinmera.github.io/parachute

Returns a list of fixtures for all symbols accessible within a given package.

```APIDOC
## PACKAGE-FIXTURES Function

### Description
Returns a list of fixtures for all symbols accessible in the given package.
```

--------------------------------

### DEFINE-TEST+RUN

Source: https://shinmera.github.io/parachute

Defines a test and runs it immediately if the form is executed.

```APIDOC
## DEFINE-TEST+RUN

### Description
Defines a test using DEFINE-TEST and runs it if the form is executed. Returns a plain report of the test execution. On failure, returns a list of failed expressions as a second value.

### Method
MACRO

### Endpoint
N/A (Macro definition)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **NAME** (string | symbol | list) - The name of the test.
- **ARGS-AND-BODY** - Arguments and body for DEFINE-TEST.
- **&REST** - Additional arguments.

### Request Example
```lisp
(DEFINE-TEST+RUN "My Test" (IS (= 1 1)))
```

### Response
#### Success Response (200)
- **report** (list) - A plain report of the test execution.
- **failed-expressions** (list) - A list of all failed expressions (on failure).

#### Response Example
```lisp
(T "Test executed successfully.")
;; Or on failure:
(NIL "Test failed.")
(list "(= 1 2)")
```
```

--------------------------------

### TEST-PACKAGES

Source: https://shinmera.github.io/parachute

Returns a list of all packages that define tests.

```APIDOC
## TEST-PACKAGES

### Description
Returns a list of all packages that define tests.

See *TEST-INDEXES*

### Method
Not applicable (function)

### Endpoint
Not applicable (function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(TEST-PACKAGES)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### TESTS

Source: https://shinmera.github.io/parachute

Retrieves the list of functions to execute for a test.

```APIDOC
## TESTS

### Description
The list of functions to execute in order to actually perform the tests. Note that the return value of this will be shuffled randomly if the test is marked as non-serial.

### Parameters
#### Arguments
- **OBJECT** - The test object.
- **&REST** - Additional arguments.
```

--------------------------------

### REPORT-ON

Source: https://shinmera.github.io/parachute

Prints a result to standard output using the formatting defined by the report.

```APIDOC
## REPORT-ON

### Description
Causes the result to be printed to standard output under the formatting of the report.

### Parameters
#### Path Parameters
- **THING** (object) - Required - The result object to report.
- **REPORT** (object) - Required - The report object defining the output format.
```

--------------------------------

### DEFINE-FIXTURE-CAPTURE

Source: https://shinmera.github.io/parachute

Defines a macro to capture symbol bindings for fixtures.

```APIDOC
## DEFINE-FIXTURE-CAPTURE

### Description
Defines a capture function to fix a symbol binding. A capture function should take a symbol and return a value to capture for it, and T as the secondary value if anything should be captured at all for the kind of binding the function handles.

### Parameters
#### Arguments
- **NAME** - Name of the capture function.
- **ARGS** - Arguments for the function.
- **BODY** - The body of the function.
- **&REST** - Additional arguments.
```

--------------------------------

### DEPENDENCIES

Source: https://shinmera.github.io/parachute

Generic function that returns the logical combination of dependant tests.

```APIDOC
## DEPENDENCIES

### Description
The logical combination of dependant tests. DEPENDENCIES ::= (LOGOP DEPENDENCY*) LOGOP ::= :OR | :AND | :NOT DEPENDENCY ::= test-object | DEPENDENCIES. If a dependency is referenced that does not exist, an error is signalled. Dependant tests must be evaluated before the test itself.

See REFERENCED-DEPENDENCIES
See CHECK-DEPENDENCY-COMBINATION
See EVAL-DEPENDENCY-COMBINATION
See RESOLVE-DEPENDENCY-COMBINATION
See TEST

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(DEPENDENCIES test)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### DEFINE-FIXTURE-RESTORE

Source: https://shinmera.github.io/parachute

Defines a macro to restore symbol bindings for fixtures.

```APIDOC
## DEFINE-FIXTURE-RESTORE

### Description
Defines a restore function to fix a symbol binding. A restoration function should take a symbol and a value and make sure to restore the binding it handles to the given value.

### Parameters
#### Arguments
- **NAME** - Name of the restore function.
- **ARGS** - Arguments for the function.
- **BODY** - The body of the function.
- **&REST** - Additional arguments.
```

--------------------------------

### SERIAL

Source: https://shinmera.github.io/parachute

Determines the execution order of tests and children.

```APIDOC
## SERIAL

### Description
Whether the tests and children should be evaluated in order, or randomly. This affects the return values of TESTS and CHILDREN.

### Parameters
#### Arguments
- **OBJECT** - The test object.
- **&REST** - Additional arguments.
```

--------------------------------

### (SETF CHILDREN)

Source: https://shinmera.github.io/parachute

Generic function for setting the list of child test instances.

```APIDOC
## (SETF CHILDREN)

### Description
Sets the list of child test instances.

See SERIAL
See TEST

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(SETF (CHILDREN object) new-list)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### System Information

Source: https://shinmera.github.io/parachute

Information about the Parachute system, including its version, dependencies, author, license, and links to its homepage, bug tracker, and source code.

```APIDOC
## System Information

### Version
1.5.0

### Dependencies
- documentation-utils
- trivial-custom-debugger
- form-fiddle

### Author
Yukari Hafner

### License
zlib

### Homepage
https://Shinmera.github.io/parachute/

### Bug Tracker
https://github.com/Shinmera/parachute/issues

### Sources
https://github.com/Shinmera/parachute.git
```

--------------------------------

### (SETF COMPARISON)

Source: https://shinmera.github.io/parachute

Generic function for setting the comparison function designator.

```APIDOC
## (SETF COMPARISON)

### Description
Sets the comparison function designator that compares the expected and actual values of the test.

See COMPARISON-RESULT

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(SETF (COMPARISON object) new-comparison-function)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### DEFINE-TEST

Source: https://shinmera.github.io/parachute

Defines a test case with various configuration options.

```APIDOC
## DEFINE-TEST

### Description
Defines a test case. NAME can be a string, symbol, or a list of a parent name and a name. BODY consists of keyword arguments (KARG) and forms.

### Method
MACRO

### Endpoint
N/A (Macro definition)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **NAME** (string | symbol | list) - The name of the test.
- **BODY** (KARG* form*) - Initialization arguments and forms for the test.
  - **KARG** (keyword expression) - Keyword arguments for test initialization.
    - **:TEST-CLASS** (symbol) - The class name to use for creating the test instance. Defaults to TEST.
- **&REST** (form*) - Additional forms to be included in the test body.

### Request Example
```lisp
(DEFINE-TEST "My Test" (:TEST-CLASS MY-TEST-CLASS) (IS (= 1 1)))
```

### Response
#### Success Response (200)
N/A (Macro definition)

#### Response Example
N/A
```

--------------------------------

### CAPTURE-FIXTURES Function

Source: https://shinmera.github.io/parachute

Captures and returns a list of fixtures for a given kind. It supports capturing by symbol or by package.

```APIDOC
## CAPTURE-FIXTURES Function

### Description
Returns a list of fixtures for the given kind. If the given name is a symbol that is not a keyword and has a package associated with it, then a list of a single fixture that captures every appropriate binding for the symbol is returned. Otherwise the name is interpreted as a package for which a list of fixtures for every symbol accessible in the package is returned.

See RESTORE-FIXTURES
See PACKAGE-FIXTURES
See DEFINE-FIXTURE-CAPTURE
```

--------------------------------

### Wrap Test Forms in 'with-shuffling'

Source: https://shinmera.github.io/parachute

When test forms need to be executed in a specific environment (e.g., with 'let'), wrap them in 'with-shuffling' to ensure they are still evaluated in a randomized order if ':serial NIL' is set.

```lisp
(define-test random-2
  (let ((a 0))
    (with-shuffling
      (is = 1 (incf a))
      (is = 2 (incf a))
      (is = 3 (incf a)))))
```

--------------------------------

### Skip Tests Conditionally with 'skip-on'

Source: https://shinmera.github.io/parachute

Use 'skip-on' to conditionally skip tests based on implementation or feature combinations. Requires a reason string and the condition.

```lisp
(define-test stuff
  (skip-on (clisp) "Not supported on clisp."
    (is equal #p"a/b/" (merge-pathnames "b/" "a/"))))
```

--------------------------------

### Run tests with different report contexts

Source: https://shinmera.github.io/parachute

Execute tests using standard, quiet, or interactive reporting modes to control output and debugger interaction.

```Common Lisp
(test 'arithmetic)
```

```Common Lisp
(test 'arithmethic :report 'quiet)
```

```Common Lisp
(test 'arithmetic :report 'interactive)
```

--------------------------------

### CALL-WITH-FIXTURES Function

Source: https://shinmera.github.io/parachute

Executes a function with a provided list of fixtures, ensuring proper capture and restoration of fixture values.

```APIDOC
## CALL-WITH-FIXTURES Function

### Description
Calls the function with the given list of fixtures. This ensures that the values are stored before the function is called and restored once the function is completed.

See CAPTURE-FIXTURES
See RESTORE-FIXTURES
See WITH-FIXTURE
```

--------------------------------

### (SETF COMPARISON-GEQ)

Source: https://shinmera.github.io/parachute

Generic function for setting the GEQ value for comparison.

```APIDOC
## (SETF COMPARISON-GEQ)

### Description
Sets the value to which the comparison result must be GEQ to.

See COMPARISON-RESULT
See GEQ

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(SETF (COMPARISON-GEQ object) new-value)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### RESTORE-FIXTURES

Source: https://shinmera.github.io/parachute

Restores bindings stored in fixtures to their saved values.

```APIDOC
## RESTORE-FIXTURES

### Description
Restores the bindings stored in the fixtures to their saved values.

See CAPTURE-FIXTURES
See DEFINE-FIXTURE-RESTORE

### Method
Not applicable (function)

### Endpoint
Not applicable (function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(RESTORE-FIXTURES)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### Configure test compilation timing

Source: https://shinmera.github.io/parachute

Use the :compile-at :execute option to defer test form compilation until the test is evaluated.

```Common Lisp
(define-test compare-numbers
  :compile-at :execute
  (fail (= :5 5)))
```

--------------------------------

### Define a Basic Test with Test Forms

Source: https://shinmera.github.io/parachute

Define a test named 'numbers' with various test forms like 'of-type', 'true', 'false', and 'is-values'. Ensure imports are handled by the testing framework.

```lisp
(define-test numbers
  (of-type integer 5)
  (true (numberp 2/3))
  (false (numberp :keyword))
  (is-values (values 0 "1")
    (= 0)
    (equal "1")))
```

--------------------------------

### FINISH

Source: https://shinmera.github.io/parachute

A tester that succeeds if the form returns without escaping.

```APIDOC
## FINISH

### Description
A tester that succeeds if the form returns without escaping.

### Parameters
- **FORM** - Required
- **DESCRIPTION** - Optional
- **FORMAT-ARGS** - Optional
```

--------------------------------

### PACKAGE-TESTS Function

Source: https://shinmera.github.io/parachute

Retrieves a list of all tests defined within a specified package.

```APIDOC
## PACKAGE-TESTS Function

### Description
Returns a list of all the tests defined in the given package. Signals an error if the PACKAGE cannot be resolved to a package object.

See *TEST-INDEXES*
```

--------------------------------

### Define Tests with Combined Dependencies

Source: https://shinmera.github.io/parachute

Complex dependency logic can be achieved by combining dependencies using ':and', ':or', and ':not'. This allows for more nuanced control over test execution.

```lisp
(define-test unexpected-failure-backup-test
  :depends-on (:and equality (:not arithmetic))
  (of-type number (+ 2 3))) ; Maybe everything broke?
```

--------------------------------

### TEST-TOPLEVEL

Source: https://shinmera.github.io/parachute

Runs tests as the toplevel, causing the implementation to quit after completion.

```APIDOC
## TEST-TOPLEVEL

### Description
Run tests as the toplevel. This function calls TEST for each of the given test/s and the provided arguments. Once all tests have been completed, it will cause the implementation to quit. The exit code will be 100 if any of the tests failed, and 0 if all of them passed. This is useful for cases like in automated continuous integration environments where the exit code determines success or failure of the build.

See TEST

### Method
Not applicable (function)

### Endpoint
Not applicable (function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(TEST-TOPLEVEL 'test1 'test2 :REPORT 'my-report)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### TEST Class

Source: https://shinmera.github.io/parachute

Manages test collections, their relationships, and options. It handles registration, parent-child relationships, and dependencies.

```APIDOC
## TEST Class

### Description
Container for test collections. Manages all the data that ties different collections together and manages the various options you might want to have for tests.

Note that merely initializing a test instance will not register it to be found by FIND-TEST. It will also not tie it in with the rest of the tests. An error will be signalled, if a parent is designated that does not exist, and warnings will be signalled if dependencies are designated that do not exist. The PARENT may be either a test designator name, which will be resolved within HOME, or a list of a package designator to use as the HOME and a name.

In order for the test to be tied in and registered to be findable, use (SETF (FIND-TEST name home) test). In order to remove it, simply use REMOVE-TEST.

See NAME
See HOME
See DESCRIPTION
See PARENT
See CHILDREN
See DEPENDENCIES
See REFERENCED-DEPENDENCIES
See FIXTURES
See TIME-LIMIT
See SKIPPED-CHILDREN
See REFERENCED-SKIPS
See TESTS
See SERIAL
See FIND-TEST
See REMOVE-TEST
See DEFINE-TEST
```

--------------------------------

### Use 'with-fixtures' for Local Fixing

Source: https://shinmera.github.io/parachute

Employ 'with-fixtures' to locally fix variables within a specific test or block. It takes an evaluated list of bindings to fix.

```lisp
(define-test float-format2
  (with-fixtures '(*read-default-float-format*)
    (setf *read-default-float-format* 'double-float)
    (of-type double-float (read-from-string "0.5")))
  (of-type single-float (read-from-string "0.5")))
```

--------------------------------

### Define Custom Fixture Capture and Restore

Source: https://shinmera.github.io/parachute

Define custom fixture capture and restore functions for user-defined bindings. This allows Parachute to manage the state of your custom variables.

```lisp
(define-fixture-capture my-binding (symbol)
  (when (my-binding-bound-p symbol)
    (values (my-binding-value symbol) T)))

(define-fixture-restore my-binding (symbol value)
  (setf (my-binding-value symbol) value))
```

--------------------------------

### Emit a comparison-result evaluation

Source: https://shinmera.github.io/parachute

Macros for test forms like 'is' emit this form to evaluate results within the current context.

```Common Lisp
(eval-in-context *context* (make-instance 'comparison-result #|...|#))
```

--------------------------------

### Integrate Parachute with ASDF

Source: https://shinmera.github.io/parachute

Configure main and test systems in ASDF to enable test execution via the test-op operation.

```Common Lisp
(asdf:defsystem main-system
  #|...|#
  :in-order-to ((asdf:test-op (asdf:test-op :test-system))))

(asdf:defsystem test-system
  #|...|#
  :perform (asdf:test-op (op c) (uiop:symbol-call :parachute :test :test-package)))
```

--------------------------------

### FALSE

Source: https://shinmera.github.io/parachute

A tester that succeeds if the specified form returns NIL.

```APIDOC
## FALSE

### Description
A tester that succeeds if the FORM returns NIL as the value.

### Method
MACRO

### Endpoint
N/A (Macro definition)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **FORM** (form) - The form to evaluate and check if it returns NIL.
- **&OPTIONAL DESCRIPTION** (string) - An optional description of the test.
- **&REST FORMAT-ARGS** - Arguments for formatting the description.

### Request Example
```lisp
(FALSE (= 1 2))
```

### Response
#### Success Response (200)
N/A (Macro definition)

#### Response Example
N/A
```

--------------------------------

### Define Tests with Parent in Another Package

Source: https://shinmera.github.io/parachute

Specify a parent test suite from a different package using the '(package-name suite-name)' syntax.

```lisp
(define-test test-a
  :parent (some/other/package suite)
  #|...|#)
```

--------------------------------

### TIME-LIMIT

Source: https://shinmera.github.io/parachute

Sets or retrieves the time limit for a test.

```APIDOC
## TIME-LIMIT

### Description
The time limit of the test, if any. In order for the test to succeed, the evaluation must succeed before the time limit is reached. Otherwise the test is marked as having failed.

### Parameters
#### Arguments
- **OBJECT** - The test object.
- **&REST** - Additional arguments.
```

--------------------------------

### TEST

Source: https://shinmera.github.io/parachute

Runs a test, resolving a designator to a list of tests to run under a single report.

```APIDOC
## TEST

### Description
Run a test. DESIGNATOR is resolved to a list of tests to run under a single report. You can specify the report class by the REPORT keyword argument. All other arguments are used as initargs for the REPORT creation. After the report has been created, each test is run via EVAL-IN-CONTEXT. Finally SUMMARIZE is called on the report.

See REPORT
See RESOLVE-TESTS
See EVAL-IN-CONTEXT
See SUMMARIZE

### Method
Not applicable (function)

### Endpoint
Not applicable (function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(TEST 'my-test-designator :REPORT 'my-report-class)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### SUMMARIZE

Source: https://shinmera.github.io/parachute

Triggers a summary report for a given report object.

```APIDOC
## SUMMARIZE

### Description
Should cause the report to produce some kind of summary. How this summary is presented and what is contained in it is up to the report itself.

### Parameters
#### Arguments
- **REPORT** - The report object.
- **&REST** - Additional arguments.
```

--------------------------------

### Define Tests with Dependencies

Source: https://shinmera.github.io/parachute

Tests can declare dependencies on other tests using ':depends-on'. If a dependency fails, the dependent test is skipped. Dependencies can be single symbols or lists.

```lisp
(define-test equality
  :depends-on (numbers)
  (is = 0 1))             ; Bogus

(define-test arithmetic
  :depends-on (equality)
  (is = 5 (+ 2 3)))
```

--------------------------------

### DEFINE-TEST+RUN-INTERACTIVELY

Source: https://shinmera.github.io/parachute

Defines a test and runs it interactively if the form is executed.

```APIDOC
## DEFINE-TEST+RUN-INTERACTIVELY

### Description
Defines a test using DEFINE-TEST and runs it with the :REPORT option set to INTERACTIVE if the form is executed.

### Method
MACRO

### Endpoint
N/A (Macro definition)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **NAME** (string | symbol | list) - The name of the test.
- **ARGS-AND-BODY** - Arguments and body for DEFINE-TEST.
- **&REST** - Additional arguments.

### Request Example
```lisp
(DEFINE-TEST+RUN-INTERACTIVELY "My Interactive Test" (IS (= 1 1)))
```

### Response
#### Success Response (200)
N/A (Interactive report is displayed directly)

#### Response Example
N/A
```

--------------------------------

### (SETF FIND-TEST) Function

Source: https://shinmera.github.io/parachute

Sets a test instance, removing any existing test with the same name and updating parent/child relationships and the test index.

```APIDOC
## (SETF FIND-TEST) Function

### Description
No documentation provided.
```

--------------------------------

### TRUE

Source: https://shinmera.github.io/parachute

A tester that succeeds if the form returns a non-NIL value.

```APIDOC
## TRUE

### Description
A tester that succeeds if the form returns a non-NIL value.

### Parameters
- **FORM** - Required
- **DESCRIPTION** - Optional
- **FORMAT-ARGS** - Optional
```

--------------------------------

### (SETF BODY)

Source: https://shinmera.github.io/parachute

Generic function for setting the value obtained from evaluating a result.

```APIDOC
## (SETF BODY)

### Description
The function that will be called to set the value obtained from evaluating the result.

See VALUE
See VALUE-RESULT

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(SETF (BODY object) new-value)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### Define a Test with a String Name

Source: https://shinmera.github.io/parachute

Tests can be named using strings, which are internally converted to strings. This is useful for more descriptive test names.

```lisp
(define-test "A more descriptive name, perhaps")
```

--------------------------------

### IS

Source: https://shinmera.github.io/parachute

A tester that succeeds if the value the form returns is equal to the expected value under the given comparator.

```APIDOC
## IS

### Description
A tester that succeeds if the value the form returns is equal to the expected value under the given comparator.

### Parameters
- **COMP** - Required
- **EXPECTED** - Required
- **FORM** - Required
- **DESCRIPTION** - Optional
- **FORMAT-ARGS** - Optional
```

--------------------------------

### CHILDREN

Source: https://shinmera.github.io/parachute

Generic function that returns the list of child test instances.

```APIDOC
## CHILDREN

### Description
The list of child test instances. Note that the return value of this will be shuffled randomly if the test is marked as non-serial. Child tests will be evaluated after the test itself.

See SERIAL
See TEST

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(CHILDREN object)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### Define Hierarchical Tests and Suites

Source: https://shinmera.github.io/parachute

Tests can be organized hierarchically using ':parent' or by nesting 'define-test' forms. This is useful for creating test suites and structuring tests.

```lisp
(define-test suite)

(define-test test-a
  :parent suite
  #|...|#)

(define-test (suite test-b)
  #|...|#)

(define-test other-suite
  #|...|#
  (define-test other-test
     #|...|#))
```

--------------------------------

### GROUP

Source: https://shinmera.github.io/parachute

Group the provided tests together under a name.

```APIDOC
## GROUP

### Description
Group the provided tests together under a name. This is similar to defining a test, but allows the body to share the lexical context with the rest of the test forms.

### Parameters
- **NAME** - Required
- **DESCRIPTION** - Optional
- **FORMAT-ARGS** - Optional
- **TESTS** - Required (Body)
```

--------------------------------

### BODY

Source: https://shinmera.github.io/parachute

Generic function called to evaluate the result and obtain a value.

```APIDOC
## BODY

### Description
The function that will be called to evaluate the result and obtain a value.

See VALUE
See VALUE-RESULT

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(BODY object)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### External Classes

Source: https://shinmera.github.io/parachute

Documentation for external classes used within the Parachute system, explaining their purpose and related concepts.

```APIDOC
## EXTERNAL CLASS

### COMPARISON-RESULT

#### Description
A result that compares against an expected value by some kind of comparator.

This result sets its status based on the boolean return value of a test of its value against an expected, preset value.

See VALUE-FORM
See EXPECTED
See COMPARISON
See COMPARISON-GEQ
See VALUE-RESULT
See VALUE-EXPECTED-P
```

--------------------------------

### FORMAT-RESULT

Source: https://shinmera.github.io/parachute

Formats a test result into a string representation.

```APIDOC
## FORMAT-RESULT

### Description
Formats the result into the requested representation as a string. Default types include :ONELINE or :EXTENSIVE.

### Parameters
#### Path Parameters
- **RESULT** (object) - Required - The result object to format.
- **TYPE** (keyword) - Required - The representation type (e.g., :ONELINE, :EXTENSIVE).
```

--------------------------------

### COMPARISON

Source: https://shinmera.github.io/parachute

Generic function that returns the comparison function designator for comparing expected and actual values.

```APIDOC
## COMPARISON

### Description
The comparison function designator that compares the expected and actual values of the test.

See COMPARISON-RESULT

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(COMPARISON object)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### SKIP-ON

Source: https://shinmera.github.io/parachute

Skips the tests in the body if any of the given feature expressions match.

```APIDOC
## SKIP-ON

### Description
Skips the tests in the body if any of the given feature expressions match. If one of the feature expression matches, the evaluation of the tests in the body is skipped and the status of these tests is forced to :SKIPPED.

### Parameters
- **FEATURES** - Required
- **DESC** - Required
- **TESTS** - Required (Body)
```

--------------------------------

### Enforce test execution time limits

Source: https://shinmera.github.io/parachute

Specify a :time-limit in seconds to ensure tests complete within a defined duration.

```Common Lisp
(define-test too-slow
  :time-limit 0.5
  (sleep 1))
```

--------------------------------

### External Special Variables

Source: https://shinmera.github.io/parachute

Documentation for external special variables used within the Parachute system, explaining their purpose and behavior.

```APIDOC
## EXTERNAL SPECIAL-VARIABLE

### *ABORT-ON-TIMEOUT-P*

#### Description
Whether the implementation should try to abort tests that exceed their time-limit.

This defaults to NIL and will only abort on supported implementations. Note that using this switch will basically cause unwinds to happen whenever the time limit exceeds, which can cause all sorts of problems, as it is unpredictable exactly where in the code it occurs.

See TIME-LIMIT

### *CONTEXT*

#### Description
Variable storing the current context of the evaluation.

While EVAL-IN-CONTEXT already carries the context as an argument, in certain situations like when opaque functions are evaluated, testers within the execution context must be able to access the context object in order to evaluate properly.

### *FIXTURE-CAPTURES*

#### Description
A map of names to fixture capture functions.

See DEFINE-FIXTURE-CAPTURE

### *FIXTURE-RESTORES*

#### Description
A map of names to fixture restore functions.

See DEFINE-FIXTURE-RESTORE

### *PARENT*

#### Description
Variable storing the immediate parent in the current evaluation context.

This is used in order to register a result within its parent.

### *SILENCE-PLAIN-COMPILATION-ERRORS-P*

#### Description
Whether PLAIN report should silence errors.

See DEFINE-TEST+RUN

### *STATUS-INDICATORS*

#### Description
A plist which maps status values to a strings used in reports. Should have the status values of :passed, :failed, :skipped, :tentative and :unknown.
```

--------------------------------

### Skip Child Tests within a Suite

Source: https://shinmera.github.io/parachute

Use the ':skip' option to selectively skip child tests within a parent suite. This is useful for temporarily disabling faulty or incomplete tests.

```lisp
(define-test suite
  :skip (test-a))
```

--------------------------------

### (SETF CHILD-STATUS)

Source: https://shinmera.github.io/parachute

Generic function for setting the child status of a controlling result.

```APIDOC
## (SETF CHILD-STATUS)

### Description
Sets the status that the children of a controlling-result should be set to.

See CONTROLLING-RESULT

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(SETF (CHILD-STATUS object) new-value)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### DESCRIPTION

Source: https://shinmera.github.io/parachute

Generic function that returns the description of a test or result.

```APIDOC
## DESCRIPTION

### Description
The description of what the test/result is about as a string or NIL.

See RESULT
See TEST

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(DESCRIPTION object)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### OF-TYPE

Source: https://shinmera.github.io/parachute

A tester that succeeds if the form returns a value that is of the requested type.

```APIDOC
## OF-TYPE

### Description
A tester that succeeds if the form returns a value that is of the requested type.

### Parameters
- **TYPE** - Required
- **FORM** - Required
- **DESCRIPTION** - Optional
- **FORMAT-ARGS** - Optional
```

--------------------------------

### Report Generation

Source: https://shinmera.github.io/parachute

Details on how to generate reports and interact with the evaluation process in Parachute. This includes information on the `quiet` report object, customizing reports by specializing `eval-in-context`, and handling test results.

```APIDOC
## Report Generation

### Description
Provides mechanisms for generating reports and interacting with the evaluation process. It details the `quiet` report object, how to extend reporting behavior by specializing `eval-in-context`, and customizing test result formatting.

### Key Concepts
- **`quiet` report object**: A basic report that catches stray errors.
- **`eval-in-context`**: A method that can be specialized to customize reporting behavior.
- **`report-on` and `summarize`**: Functions to customize output for plain reports.
- **`result-for-testable`**: Function to return appropriate result objects for testables.
- **`test-result`**: The standard result instance returned by default tests.
- **`format-result`**: Methods to specialize for customizing how new result types are formatted in reports (e.g., `:oneline`, `:extensive`).
```

--------------------------------

### FEATUREP Function

Source: https://shinmera.github.io/parachute

Checks if a given feature expression matches the current set of *FEATURES*.

```APIDOC
## FEATUREP Function

### Description
Returns T if the given feature expression matches the set of *FEATURES*. The expression follows the standard feature syntax. See 24.1.2.1 in the CLHS.
```

--------------------------------

### FAIL-COMPILE

Source: https://shinmera.github.io/parachute

A tester that succeeds if the specified form fails to compile.

```APIDOC
## FAIL-COMPILE

### Description
A tester that succeeds if the FORM fails to compile. The form will not be executed, only compiled.

### Method
MACRO

### Endpoint
N/A (Macro definition)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **FORM** (form) - The form to attempt to compile.
- **&OPTIONAL TYPE** (symbol) - The type of compilation error to expect. Defaults to ERROR.
- **DESCRIPTION** (string) - An optional description of the test.
- **&REST FORMAT-ARGS** - Arguments for formatting the description.

### Request Example
```lisp
(FAIL-COMPILE (lambda (x) x y))
```

### Response
#### Success Response (200)
N/A (Macro definition)

#### Response Example
N/A
```

--------------------------------

### ISNT

Source: https://shinmera.github.io/parachute

A tester that succeeds if the value the form returns is not equal to the expected value under the given comparator.

```APIDOC
## ISNT

### Description
A tester that succeeds if the value the form returns is not equal to the expected value under the given comparator.

### Parameters
- **COMP** - Required
- **EXPECTED** - Required
- **FORM** - Required
- **DESCRIPTION** - Optional
- **FORMAT-ARGS** - Optional
```

--------------------------------

### Skip Individual Test Forms

Source: https://shinmera.github.io/parachute

Use the 'skip' test form to skip individual test forms within a test. Provide a reason string for skipping.

```lisp
(define-test stuff
  (true :pass)
  (skip "Not ready yet"
    (is = 5 (some-unimplemented-function 10))))
```

--------------------------------

### FAIL

Source: https://shinmera.github.io/parachute

A tester that succeeds if the specified form signals an error.

```APIDOC
## FAIL

### Description
A tester that succeeds if the FORM signals an error of the requested TYPE, defaulting to ERROR.

### Method
MACRO

### Endpoint
N/A (Macro definition)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **FORM** (form) - The form to evaluate and check for errors.
- **&OPTIONAL TYPE** (symbol) - The type of error to expect. Defaults to ERROR.
- **DESCRIPTION** (string) - An optional description of the test.
- **&REST FORMAT-ARGS** - Arguments for formatting the description.

### Request Example
```lisp
(FAIL (error "Something went wrong"))
```

### Response
#### Success Response (200)
N/A (Macro definition)

#### Response Example
N/A
```

--------------------------------

### WITH-SHUFFLING

Source: https://shinmera.github.io/parachute

Causes each form in the body to be evaluated in random order each time the with-shuffling form is evaluated.

```APIDOC
## WITH-SHUFFLING

### Description
Causes each form in the body to be evaluated in random order each time the with-shuffling form is evaluated.

### Parameters
- **BODY** - Required
```

--------------------------------

### Disable Sequential Execution with ':serial NIL'

Source: https://shinmera.github.io/parachute

Set ':serial NIL' to randomize the order of test forms and children within a test. This helps uncover hidden sequential dependencies.

```lisp
(define-test random
  :serial NIL
  (true 1)
  (true 2)
  (true 3)
  (true 4)
  (true 5))
```

--------------------------------

### COMPARISON-GEQ

Source: https://shinmera.github.io/parachute

Generic function that returns the value to which the comparison result must be GEQ.

```APIDOC
## COMPARISON-GEQ

### Description
The value to which the comparison result must be GEQ to. Defaults to T.

See COMPARISON-RESULT
See GEQ

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(COMPARISON-GEQ object)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### TESTS-WITH-STATUS

Source: https://shinmera.github.io/parachute

Retrieves evaluated test objects matching a specific status.

```APIDOC
## TESTS-WITH-STATUS

### Description
Returns a list of TEST objects that have been evaluated and whose reports have the requested status.

### Parameters
#### Arguments
- **STATUS** - The status to filter by.
- **REPORT** - The report object.
- **&REST** - Additional arguments.
```

--------------------------------

### FIND-TEST Function

Source: https://shinmera.github.io/parachute

Finds a test by its name, with options for specifying the package. It can also be used as a place to register tests.

```APIDOC
## FIND-TEST Function

### Description
Finds the test by name if possible. If the name is a symbol, the package defaults to the symbol's package. If the name is a string, the package defaults to *PACKAGE*. If no explicit package has been given and no test has been found, the search is automatically retried with the package set to *PACKAGE*. This should avoid confusion in the case of imported symbols and tests defined under the local package.

This function can also be used as a place in order to register a test. When a test is set, the preexisting test if any is first removed by REMOVE-TEST. This ensures that potentially removed options need to be properly updated within other affected tests. After that, the test is added to the list of children within its parent, if one is set. Finally the test is registered within the test index.

See REMOVE-TEST
See *TEST-INDEX*
```

--------------------------------

### RESULTS-WITH-STATUS

Source: https://shinmera.github.io/parachute

Retrieves a list of results that are children of a given result and match a specific status.

```APIDOC
## RESULTS-WITH-STATUS

### Description
Returns a list of results that are a child of the result and have the requested status.

### Parameters
#### Arguments
- **STATUS** - The status to filter by.
- **RESULT** - The parent result object.
- **&REST** - Additional arguments.
```

--------------------------------

### SKIPPED-CHILDREN

Source: https://shinmera.github.io/parachute

Manages the list of children that should be skipped during test evaluation.

```APIDOC
## SKIPPED-CHILDREN

### Description
The list of the children that should be skipped. If a child is referenced that does not exist, an error is signalled. If a child is within this list, it will not be evaluated after the test and instead be marked as skipped automatically.

### Parameters
#### Arguments
- **TEST** - The test object.
- **&REST** - Additional arguments.
```

--------------------------------

### STATUS-CHARACTER

Source: https://shinmera.github.io/parachute

Returns the appropriate status indicator for a specific result status.

```APIDOC
## STATUS-CHARACTER

### Description
Return the appropriate status indicator for a specific result status.

See *STATUS-INDICATORS*

### Method
Not applicable (function)

### Endpoint
Not applicable (function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(STATUS-CHARACTER :success)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### IS-VALUES

Source: https://shinmera.github.io/parachute

A tester that succeeds if each value the form returns is equal to the corresponding expected value under the corresponding comparator.

```APIDOC
## IS-VALUES

### Description
A tester that succeeds if each value the form returns is equal to the corresponding expected value under the corresponding comparator. The body consists of lists of two values, the first being the comparator, the second being the expected value.

### Parameters
- **FORM** - Required
- **BODY** - Required
```

--------------------------------

### ISNT-VALUES

Source: https://shinmera.github.io/parachute

A tester that succeeds if each value the form returns is not equal to the corresponding expected value under the corresponding comparator.

```APIDOC
## ISNT-VALUES

### Description
A tester that succeeds if each value the form returns is not equal to the corresponding expected value under the corresponding comparator. The body consists of lists of two values, the first being the comparator, the second being the expected value.

### Parameters
- **FORM** - Required
- **BODY** - Required
```

--------------------------------

### EVAL-IN-CONTEXT

Source: https://shinmera.github.io/parachute

Evaluates a test within a given context, typically used for customizable evaluation behavior during test reporting.

```APIDOC
## EVAL-IN-CONTEXT

### Description
Evaluates the thing within the given context. This is used to provide customizable evaluation behavior during the evaluation of tests under a given report.

### Parameters
#### Path Parameters
- **CONTEXT** (object) - Required - The context (usually a report object) in which to evaluate.
- **TEST** (object) - Required - The test instance or result to be evaluated.
```

--------------------------------

### TEST-RESULT Class

Source: https://shinmera.github.io/parachute

Represents the result of a test, handling the evaluation process including dependencies and child tests.

```APIDOC
## TEST-RESULT Class

### Description
A result object for tests. This takes care of properly evaluating the test by following these steps:
1. Run all tests in the test's DEPENDENCIES as per EVAL-DEPENDENCY-COMBINATION
2. Check that all dependencies have a :PASSED status as per the dependency combination by running CHECK-DEPENDENCY-COMBINATION
3. For each child in the test's CHILDREN
   create a result by RESULT-FOR-TESTABLE
   if the child is part of the test's SKIPPED-CHILDREN
   mark its result as :SKIPPED and EVAL-IN-CONTEXT it.
   Otherwise EVAL-IN-CONTEXT the child's result directly.

The methods implemented by PARENT-RESULT and RESULT will in turn take care to implement proper status setting and avoiding duplicate evaluation.

See PARENT-RESULT
See EVAL-DEPENDENCY-COMBINATION
See CHECK-DEPENDENCY-COMBINATION
```

--------------------------------

### WITH-FORCED-STATUS

Source: https://shinmera.github.io/parachute

Forces the requested status upon the tests in the body without evaluating any value-results.

```APIDOC
## WITH-FORCED-STATUS

### Description
Forces the requested status upon the tests in the body without evaluating any value-results.

### Parameters
- **STATUS** - Required
- **DESCRIPTION** - Optional
- **FORMAT-ARGS** - Optional
- **TESTS** - Required (Body)
```

--------------------------------

### VALUE-RESULT Class

Source: https://shinmera.github.io/parachute

A result object that stores a value, typically set after evaluation. The body is not run if the value is already bound.

```APIDOC
## VALUE-RESULT Class

### Description
A result that carries some kind of test result value. Typically the VALUE slot is only set once the result is evaluated. Note that if the VALUE slot is bound at the time that the result is evaluated, the BODY will not be run.

See BODY
See VALUE
See RESULT
```

--------------------------------

### SKIP

Source: https://shinmera.github.io/parachute

Skips the tests in the body by avoiding their evaluation and marking their status as :SKIPPED.

```APIDOC
## SKIP

### Description
Skips the tests in the body by avoiding their evaluation and marking their status as :SKIPPED.

### Parameters
- **DESC** - Required
- **TESTS** - Required (Body)
```

--------------------------------

### CHECK-EVALUATABLE

Source: https://shinmera.github.io/parachute

Checks if a test is evaluatable in a given context and signals an error if not.

```APIDOC
## CHECK-EVALUATABLE

### Description
Checks whether the thing is evaluatable in the context and signals an error if not. This is primarily used to error out early on tests that are specified wrong.

See EVAL-IN-CONTEXT

### Method
Not applicable (generic function)

### Endpoint
Not applicable (generic function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(CHECK-EVALUATABLE context test)
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### REMOVE-ALL-TESTS-IN-PACKAGE

Source: https://shinmera.github.io/parachute

Removes all tests from a specified package.

```APIDOC
## REMOVE-ALL-TESTS-IN-PACKAGE

### Description
Remove all tests from PACKAGE (*package* by default).

### Method
Not applicable (function)

### Endpoint
Not applicable (function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(REMOVE-ALL-TESTS-IN-PACKAGE "my-package")
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### STATUS

Source: https://shinmera.github.io/parachute

Accesses or modifies the status of a result object.

```APIDOC
## STATUS

### Description
The status of the result object. Should be one of :UNKNOWN :FAILED :PASSED :SKIPPED. By default after initialization the status is :UNKNOWN. The status is automatically changed to :PASSED if the result is still :UNKNOWN after EVAL-IN-CONTEXT completes.

### Parameters
#### Arguments
- **OBJECT** - The result object.
- **&REST** - Additional arguments.
```
Tokens:
Raw