FiveAM

https://fiveam.common-lisp.dev/docs
Admin
FiveAM is a Common Lisp testing framework for defining, running, and analyzing tests, offering...
Tokens:45,823
Snippets:164
Trust Score:5.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### FiveAM Example Functions

Source: https://fiveam.common-lisp.dev/docs/index/permutated

API documentation for example functions within the FiveAM framework, such as DUMMY-ADD and DUMMY-STRCAT, likely used for demonstration or basic operations.

```APIDOC
DUMMY-ADD:
  (DUMMY-ADD a b)
  Adds two numbers.
  Parameters:
    a: The first number.
    b: The second number.
  Returns: The sum of a and b.

DUMMY-STRCAT:
  (DUMMY-STRCAT str1 str2)
  Concatenates two strings.
  Parameters:
    str1: The first string.
    str2: The second string.
  Returns: The concatenated string.
```

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

### Example Add Functions

Source: https://fiveam.common-lisp.dev/docs/index/function

Placeholder functions for examples, including ADD-4, ADD-2, DUMMY-ADD, and DUMMY-STRCAT.

```common-lisp
ADD-4
ADD-2
DUMMY-ADD
DUMMY-STRCAT
```

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

### Define Example Package

Source: https://fiveam.common-lisp.dev/docs/FiveAM_0020Example_0020_0028poor_0020man_0027s_0020tutorial_0029

Defines a new package named 'it.bese.FiveAM.example' that uses Common Lisp and the FiveAM testing library. This sets up the environment for writing tests.

```common-lisp
(defpackage :it.bese.FiveAM.example
  (:use :common-lisp
	:it.bese.FiveAM))
```

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

### FiveAM Initialization Variable

Source: https://fiveam.common-lisp.dev/docs/index/permutated

A variable related to the initial state or setup of the FiveAM testing framework.

```APIDOC
INITIAL-!*:
  A variable likely used during the initialization phase of the FiveAM framework.
```

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

### FiveAM DEF-FIXTURE Macro

Source: https://fiveam.common-lisp.dev/docs/index/permutated

The DEF-FIXTURE macro is used to define test fixtures in the FiveAM framework. Fixtures provide a setup and teardown environment for tests.

```common-lisp
DEF-FIXTURE
```

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

### FiveAM API Documentation

Source: https://fiveam.common-lisp.dev/docs/Running_0020Tests

Provides API documentation for FiveAM functions and variables related to running tests, managing dependencies, and handling test results. This includes descriptions of functions like RUN, RUN!, EXPLAIN, and variables like *DEBUG-ON-ERROR*.

```APIDOC
RUN
  Executes a number of tests and collects the results of each individual check into a list which is then returned.

RUN!, !, !! and !!!
  Convenient wrappers around RUN and EXPLAIN.

*DEBUG-ON-ERROR*
  T if we should drop into a debugger on error, NIL otherwise.

*DEBUG-ON-FAILURE*
  T if we should drop into a debugger on a failing check, NIL otherwise.

IMPORT-TESTING-SYMBOLS
  Imports symbols related to testing.

*RUN-QUEUE*
  List of test waiting to be run.

RUN-RESOLVING-DEPENDENCIES TEST-CASE
  Given a dependency spec determine if the spec is satisfied or not, this will generally involve running other tests.
  Returns true if this test, and its dependencies, are satisfied, NIL otherwise.

RESOLVE-DEPENDENCIES SYMBOL
  A test which depends on a symbol is interpreted as `(AND ,DEPENDS-ON)`.

RESOLVE-DEPENDENCIES LIST
  Return true if the dependency spec DEPENDS-ON is satisfied, nil otherwise.

RESULTS-STATUS
  Given a list of test results (generated while running a test) return true if all of the results are of type TEST-PASSED, faile otherwise.

RETURN-RESULT-LIST
  Run the test function TEST-LAMBDA and return a list of all test results generated, does not modify the special environment variable RESULT-LIST.

%RUN TEST-CASE
  Internal method for running a test.

%RUN TEST-SUITE
  Internal method for running a test suite.

%RUN SYMBOL
  Internal method for running a test associated with a symbol.
```

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

### Define Test Suite and Add Tests

Source: https://fiveam.common-lisp.dev/docs/FiveAM_0020Example_0020_0028poor_0020man_0027s_0020tutorial_0029

Defines a test suite named 'example-suite' and sets it as the default suite. It then defines tests for 'add-4' and redefines 'add-2' to be part of this suite. Finally, it runs the entire suite.

```common-lisp
(def-suite example-suite :description "The example test suite.")
```

```common-lisp
(in-suite example-suite)
```

```common-lisp
(test add-4
  (is (= 0 (add-4 -4))))
```

```common-lisp
(run! 'add-4)
```

```common-lisp
(run! 'example-suite)
```

```common-lisp
(test add-2 "Test the ADD-2 function"
 (is (= 2 (add-2 0)))
 (is (= 0 (add-2 -2))))
```

```common-lisp
(run! 'example-suite)
```

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

### FiveAM Test Status and Reporting

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Utilities for checking the status of tests and retrieving test results. This includes checking if a test is skipped and getting the status of test results.

```APIDOC
TEST-SKIPPED
  - Class representing a skipped test.

TEST-SKIPPED-P
  - Generic function to check if a test is skipped.
  - Parameters:
    - TEST-RESULT: The test result object.
  - Returns: T if the test is skipped, NIL otherwise.

RESULTS-STATUS
  - Function to get the status of test results.
  - Parameters:
    - RESULTS: The test results.
  - Returns: The status of the results.
```

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

### Set Current Package

Source: https://fiveam.common-lisp.dev/docs/FiveAM_0020Example_0020_0028poor_0020man_0027s_0020tutorial_0029

Sets the current package to 'it.bese.FiveAM.example'. All subsequent definitions and operations will occur within this package.

```common-lisp
(in-package :it.bese.FiveAM.example)
```

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

### Test with Failing Assertion

Source: https://fiveam.common-lisp.dev/docs/FiveAM_0020Example_0020_0028poor_0020man_0027s_0020tutorial_0029

Redefines the 'add-2' test to include a failing assertion. This demonstrates how FiveAM handles test failures, showing an example where an expected value does not match the actual output.

```common-lisp
(test add-2 "Test the ADD-2 function"
 (is (= 2 (add-2 0)))
 (is (= 0 (add-2 -2)))
 (is (= 0 (add-2 0))))
```

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

### Simple Text Explainer Results

Source: https://fiveam.common-lisp.dev/docs/api/method_005FIT.BESE.FIVEAM_003A_003A_0028EXPLAIN_0020SIMPLE-TEXT-EXPLAINER_0020T_0029

This Common Lisp method formats and prints the results of a test execution. It partitions the results to count passed, skipped, failed, and unknown outcomes, then presents this summary in a human-readable format to a specified stream.

```common-lisp
(defmethod explain ((exp simple-text-explainer) results
                    &optional (stream *test-dribble*) (recursive-depth 0))
  (multiple-value-bind (num-checks passed num-passed passed%
			   skipped num-skipped skipped%
			   failed num-failed failed%
			   unknown num-unknown unknown%)
      (partition-results results)
    (declare (ignore passed passed% skipped skipped% failed failed% unknown unknown%))
    (format stream "~&~vTRan ~D checks, ~D passed" recursive-depth num-checks num-passed)
    (when (plusp num-skipped)
      (format stream ", ~D skipped " num-skipped))
    (format stream " and ~D failed.~%" num-failed)
    (when (plusp num-unknown)
      (format stream "~vT~D UNKNOWN RESULTS.~%" recursive-depth num-unknown))))
```

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

### FiveAM Explanation Methods

Source: https://fiveam.common-lisp.dev/docs/index/permutated

API documentation for the EXPLAIN method in FiveAM, used for providing explanations, potentially for different explainer types like SIMPLE-TEXT-EXPLAINER and DETAILED-TEXT-EXPLAINER.

```APIDOC
EXPLAIN (simple-text-explainer t):
  Provides a simple text explanation.
  Parameters:
    simple-text-explainer: The explainer object.
    t: The type of object to explain.
  Returns: A string explanation.

EXPLAIN (detailed-text-explainer t):
  Provides a detailed text explanation.
  Parameters:
    detailed-text-explainer: The explainer object.
    t: The type of object to explain.
  Returns: A detailed string explanation.
```

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

### FiveAM Suite Creation and Configuration

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Functions and variables for creating test suites and configuring the testing environment. MAKE-SUITE creates a new test suite, while variables like MAX-TRIALS*, NUM-TRIALS*, DEBUG-ON-ERROR*, and DEBUG-ON-FAILURE* control test execution behavior.

```APIDOC
MAKE-SUITE:
  (MAKE-SUITE name &rest test-cases)
  Creates a new test suite with the given name and test cases.

MAX-TRIALS*:
  A variable that sets the maximum number of trials for property-based testing.

NUM-TRIALS*:
  A variable that sets the number of trials for property-based testing.

DEBUG-ON-ERROR*:
  A variable that, when non-nil, enables debugging on encountering an error during test execution.

DEBUG-ON-FAILURE*:
  A variable that, when non-nil, enables debugging on encountering a test failure.
```

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

### FiveAM Core Functions and Macros

Source: https://fiveam.common-lisp.dev/docs/index/permutated

This section details core functions and macros in the FiveAM testing framework. It includes EXPLAIN! for detailing test results, FAIL for asserting failures, IS-FALSE for checking falsity, FINISHES for timing operations, and WITH-FIXTURE/DEF-FIXTURE for managing test fixtures.

```APIDOC
EXPLAIN!
  (format "~a" format-string &rest args)
  - Explains a test result, providing detailed information.
  - Parameters:
    - format-string: The format string for the explanation.
    - args: Arguments to be formatted into the string.
  - Returns: The formatted explanation string.
```

```APIDOC
FAIL
  (format "~a" format-string &rest args)
  - Macro to assert a test failure with a given message.
  - Parameters:
    - format-string: The format string for the failure message.
    - args: Arguments to be formatted into the message.
  - Usage:
    (FAIL "Expected value to be ~a but got ~a" expected actual)
```

```APIDOC
IS-FALSE
  (form)
  - Macro to assert that a form evaluates to false.
  - Parameters:
    - form: The form to evaluate.
  - Usage:
    (IS-FALSE (= 1 2))
```

```APIDOC
FINISHES
  (form)
  - Macro that times the execution of a form.
  - Parameters:
    - form: The form to time.
  - Returns: The result of the form.
```

```APIDOC
WITH-FIXTURE
  (name &body body)
  - Macro to establish a test fixture context.
  - Parameters:
    - name: The name of the fixture to use.
    - body: The code to execute within the fixture context.
  - Usage:
    (WITH-FIXTURE :my-fixture
      (TEST "My test case")
      ...)
```

```APIDOC
DEF-FIXTURE
  (name setup teardown &body body)
  - Macro to define a new test fixture.
  - Parameters:
    - name: The name of the fixture.
    - setup: Code to run before the test.
    - teardown: Code to run after the test.
    - body: The test case itself.
```

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

### FiveAM Test Execution Functions

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Documentation for functions related to performing and importing tests, including PERFORM-RANDOM-TESTING, IMPORT-TESTING-SYMBOLS, and PERFORM-RANDOM-TESTING/RUN-ONCE.

```APIDOC
Function PERFORM-RANDOM-TESTING:
  Description: Executes tests in a random order.

Function IMPORT-TESTING-SYMBOLS:
  Description: Imports symbols related to testing.

Function PERFORM-RANDOM-TESTING/RUN-ONCE:
  Description: Performs random testing and runs it once.
```

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

### FiveAM Assertion and Test Macros

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Documentation for the IS-TRUE macro for assertions and WITH-TEST-DRIBBL* and WITH-FIXTURE for test execution context management.

```APIDOC
Macro IS-TRUE:
  Description: Asserts that a condition is true.

Macro WITH-TEST-DRIBBL*:
  Description: Manages test dribbling context.

Macro WITH-FIXTURE:
  Description: Sets up and tears down test fixtures.
```

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

### Result Explanation

Source: https://fiveam.common-lisp.dev/docs/index/function

EXPLAIN! explains the results of a RESULT-LIST using a detailed text explainer, directing output to *test-dribble*.

```common-lisp
EXPLAIN!
```

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

### Symbol Importing

Source: https://fiveam.common-lisp.dev/docs/index/function

IMPORT-TESTING-SYMBOLS imports necessary symbols for testing.

```common-lisp
IMPORT-TESTING-SYMBOLS
```

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

### FiveAM API Documentation

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Comprehensive API documentation for the FiveAM Common Lisp testing framework. This section details various functions, methods, classes, and variables used for test execution and result management.

```APIDOC
RESULTS-STATUS:
  (RESULTS-STATUS)
  Returns the status of the test results.
  Parameters: None
  Returns: The status of the test results.

RETURN-RESULT-LIST:
  (RETURN-RESULT-LIST)
  Returns the list of test results.
  Parameters: None
  Returns: A list containing the test results.

RUN:
  (RUN)
  Executes tests.
  Parameters: None
  Returns: The result of running the tests.

RUN (Method for SYMBOL):
  (RUN (SYMBOL))
  Runs tests associated with a symbol.
  Parameters:
    SYMBOL: The symbol representing the tests to run.
  Returns: The result of running the specified tests.

RUN (Method for TEST-SUITE):
  (RUN (TEST-SUITE))
  Runs a test suite.
  Parameters:
    TEST-SUITE: The test suite to run.
  Returns: The result of running the test suite.

RUN (Method for TEST-CASE):
  (RUN (TEST-CASE))
  Runs a specific test case.
  Parameters:
    TEST-CASE: The test case to run.
  Returns: The result of running the test case.

RUN (Generic Function):
  (RUN)
  A generic function for running tests.
  Parameters: Varies based on the method specialization.
  Returns: The result of the test execution.

FOR-ALL-TEST-NEVER-RUN (Class):
  Represents a class for tests that have never been run.

RUN!:
  (RUN!)
  Executes tests and potentially modifies state.
  Parameters: None
  Returns: The result of running the tests.

RUN-ONCE:
  (RUN-ONCE)
  Performs random testing by running tests once.
  Parameters: None
  Returns: The result of a single random test execution.

RUN-QUEUE* (Variable):
  A global variable representing the run queue.

RUN-RESOLVING-DEPENDENCIES (Method for TEST-CASE):
  (RUN-RESOLVING-DEPENDENCIES (TEST-CASE))
  Runs a test case while resolving dependencies.
  Parameters:
    TEST-CASE: The test case to run with dependency resolution.
  Returns: The result of running the test case with resolved dependencies.

RUN-RESOLVING-DEPENDENCIES (Generic Function):
  (RUN-RESOLVING-DEPENDENCIES)
  A generic function for running tests with dependency resolution.
  Parameters: Varies based on the method specialization.
  Returns: The result of the test execution with dependency resolution.
```

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

### Define and Run Single Test (add-2)

Source: https://fiveam.common-lisp.dev/docs/FiveAM_0020Example_0020_0028poor_0020man_0027s_0020tutorial_0029

Defines a test named 'add-2' that verifies the 'add-2' function. It includes assertions using 'is' to check the function's output for different inputs. The test is then executed using 'run!'.

```common-lisp
(test add-2
 "Test the ADD-2 function" ;; a short description
 ;; the checks
 (is (= 2 (add-2 0)))
 (is (= 0 (add-2 -2))))
```

```common-lisp
(run 'add-2)
```

```common-lisp
(explain! (run 'add-2))
```

```common-lisp
(run! 'add-2)
```

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

### FiveAM API Documentation

Source: https://fiveam.common-lisp.dev/docs/Test_0020Suites

API documentation for FiveAM test suite management functions and macros.

```APIDOC
Macro DEF-SUITE:
  Define a new test-suite named NAME.

Function MAKE-SUITE:
  Create a new test suite object.

Variable *SUITE*:
  The current test suite object.

Macro IN-SUITE:
  Set the *suite* special variable so that all tests defined after the execution of this form are, unless specified otherwise, in the test-suite named SUITE-NAME.
```

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

### Define Variable *!*

Source: https://fiveam.common-lisp.dev/docs/api/variable_005FIT.BESE.FIVEAM_003A_003A_002A_0021_002A

Defines a global variable named *!* and initializes it with the value of *initial-!*.

```common-lisp
(defvar *!* *initial-!*)
```

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

### Load FiveAM ASDF Operation

Source: https://fiveam.common-lisp.dev/docs/FiveAM_0020Example_0020_0028poor_0020man_0027s_0020tutorial_0029

Loads the FiveAM testing framework using ASDF, the Common Lisp build system. This is a prerequisite for using FiveAM functionalities.

```common-lisp
(asdf:oos 'asdf:load-op :FiveAM)
```

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

### FiveAM Macros: DEF-SUITE and DEFGENERATOR

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Documentation for DEF-SUITE and DEFGENERATOR macros used in FiveAM for defining test suites and generators. These are fundamental for structuring tests.

```APIDOC
DEF-SUITE:
  (DEF-SUITE suite-name &rest body)
  Defines a new test suite.
  suite-name: The name of the test suite.
  body: Forms to be evaluated within the suite.

DEFGENERATOR:
  (DEFGENERATOR generator-name (args...) &rest body)
  Defines a test data generator.
  generator-name: The name of the generator.
  args: Arguments for the generator.
  body: Forms to be evaluated to produce test data.
```

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

### Define Global Test Suite (*SUITE*)

Source: https://fiveam.common-lisp.dev/docs/api/variable_005FIT.BESE.FIVEAM_003A_003A_002ASUITE_002A

Defines the global test suite object '*SUITE*' for the FiveAM testing framework. This variable holds the current test suite, initialized with a description.

```common-lisp
(defvar *suite* (setf (get-test 'NIL)
		      (make-suite 'NIL :description "Global Suite"))
  "The current test suite object")
```

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

### Property-Based Testing with Dummy Functions

Source: https://fiveam.common-lisp.dev/docs/FiveAM_0020Example_0020_0028poor_0020man_0027s_0020tutorial_0029

Demonstrates property-based testing using 'for-all' and generators for integers and strings. It tests 'dummy-add' by verifying properties like commutativity, identity element, and relationship with negation. It also tests 'dummy-strcat' by ensuring string concatenation works as expected.

```common-lisp
(test dummy-add
  (for-all ((a (gen-integer))
            (b (gen-integer)))
    ;; assuming we have an "oracle" to compare our function results to
    ;; we can use it:
    (is (= (+ a b) (dummy-add a b)))
    ;; if we don't have an oracle (as in most cases) we just ensure
    ;; that certain properties hold:
    (is (= (dummy-add a b)
           (dummy-add b a)))
    (is (= a (dummy-add a 0)))
    (is (= 0 (dummy-add a (- a))))
    (is (< a (dummy-add a 1)))
    (is (= (* 2 a) (dummy-add a a)))))

```

```common-lisp
(test dummy-strcat
  (for-all ((result (gen-string))
            (split-point (gen-integer :min 0 :max 10000) 
                         (< split-point (length result))))
    (is (string= result (dummy-strcat (subseq result 0 split-point)
                                      (subseq result split-point))))))

```

```common-lisp
(test random-failure
  (for-all ((result (gen-integer :min 0 :max 1)))
    (is (plusp result))
    (is (= result 0))))

```

```common-lisp
(run! 'example-suite)
```

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

### FiveAM Test Configuration Variables

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Documentation for variables that control the behavior of FiveAM's random testing, specifically MAX-TRIALS and NUM-TRIALS.

```APIDOC
Variable *MAX-TRIALS*:
  Description: The maximum number of trials for random testing.

Variable *NUM-TRIALS*:
  Description: The number of trials to perform for random testing.
```

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

### FiveAM Test Execution Methods

Source: https://fiveam.common-lisp.dev/docs/index/method

This section details methods related to the execution and dependency management of FiveAM tests. It includes functions for resolving dependencies, running tests, and handling test case execution with or without dependency resolution.

```APIDOC
RESOLVE-DEPENDENCIES(DEPENDS-ON LIST)
  - Return true if the dependency spec DEPENDS-ON is satisfied, nil otherwise.

RUN-RESOLVING-DEPENDENCIES(TEST-CASE)
  - Return true if this test, and its dependencies, are satisfied, NIL otherwise.

RUN-TEST-LAMBDA(TEST-CASE)
  - Executes a test case defined as a lambda function.
```

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

### FiveAM Dependency Resolution Methods

Source: https://fiveam.common-lisp.dev/docs/index/permutated

API documentation for methods related to resolving dependencies within the FiveAM testing framework. This includes resolving dependencies for lists, symbols, and test cases.

```APIDOC
RESOLVE-DEPENDENCIES (list):
  Resolves dependencies for a list of items.
  Parameters:
    list: A list of items for which to resolve dependencies.
  Returns: The resolved dependencies.

RESOLVE-DEPENDENCIES (symbol):
  Resolves dependencies for a given symbol.
  Parameters:
    symbol: The symbol for which to resolve dependencies.
  Returns: The resolved dependencies for the symbol.

RUN-RESOLVING-DEPENDENCIES (test-case):
  Runs the dependency resolution process for a specific test case.
  Parameters:
    test-case: The test case object.
  Returns: The result of running dependency resolution.

RUN-RESOLVING-DEPENDENCIES (Generic Function):
  A generic function for running dependency resolution.
  This function dispatches based on the type of input provided.
```

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

### FiveAM FOR-ALL Macros and Classes

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Includes macros and classes related to the 'FOR-ALL' functionality in FiveAM. This covers iterating through tests, handling test failures, and managing different test execution states.

```common-lisp
FOR-ALL (Macro)
FOR-ALL-TEST-FAILED (Class)
FOR-ALL-TEST-FAILED-P (Generic Function)
FOR-ALL-TEST-NEVER-RUN (Class)
FOR-ALL-TEST-NO-TESTS (Class)
FOR-ALL-TEST-PASSED (Class)
FOR-ALL-TEST-RESULT (Class)
```

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

### FiveAM Test Dribbling and Debugging Variables

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Documentation for FiveAM utilities related to test dribbling and debugging. This includes macros for controlling dribbling and variables for debugging on error.

```APIDOC
WITH-*TEST-DRIBBLE*:
  (WITH-*TEST-DRIBBLE* value &body body)
  A macro to control the *TEST-DRIBBL* variable within a dynamic scope.
  value: The value to set for *TEST-DRIBBL*.
  body: Forms to be evaluated.

*TEST-DRIBBL*:
  A dynamic variable used to control test dribbling output.

*DEBUG-ON-ERROR*:
  A dynamic variable that, when non-nil, enables debugging when an error occurs during test execution.
```

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

### Variable Definition: *!!*

Source: https://fiveam.common-lisp.dev/docs/api/variable_005FIT.BESE.FIVEAM_003A_003A_002A_0021_0021_002A

Defines the special variable *!!* and initializes it with the value of *initial-!*.

```common-lisp
(defvar *!!* *initial-!*)
```

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

### Define Test Suite (DEF-SUITE)

Source: https://fiveam.common-lisp.dev/docs/api/macro_005FIT.BESE.FIVEAM_003A_003ADEF-SUITE

Defines a new test suite with an optional description and the ability to nest it within another suite. It utilizes the make-suite function to create the suite.

```common-lisp
(defmacro def-suite (name &key description in)
  "Define a new test-suite named NAME.

  IN (a symbol), if provided, causes this suite te be nested in the
  suite named by IN."
  `(progn
     (make-suite ',name
		 ,@(when description `(:description ,description))
		 ,@(when in `(:in ',in)))
     ',name))
```

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

### TEST Macro Definition

Source: https://fiveam.common-lisp.dev/docs/api/macro_005FIT.BESE.FIVEAM_003A_003ATEST

Defines the TEST macro for creating test suites. It parses test names, handles dependencies (AND, OR, NOT), and associates test functions with their descriptions and suite information. The macro registers the test case within the testing framework.

```common-lisp
(defmacro test (name &body body)
  "Create a suite named NAME. If NAME is a list it must be of the
  form:

  (name &key depends-on suite)

  NAME is the symbol which names the test.

  DEPENDS-ON is a list of the form:

   (AND . test-names) - This test is run only if all of the tests
   in TEST-NAMES have passed, otherwise a single test-skipped
   result is generated.

   (OR . test-names) - If any of TEST-NAMES has passed this test is
   run, otherwise a test-skipped result is generated.

   (NOT test-name) - This is test is run only if TEST-NAME failed.

   AND, OR and NOT can be combined to produce complex dependencies.

   If DEPENDS-ON is a symbol it is interpreted as `(AND
   ,depends-on), this is accomadate the common case of one test
   depending on another.

   SUITE defaults to the current value of *SUITE*."
  (destructuring-bind (name &key depends-on (suite nil suite-supplied-p))
      (ensure-list name)
    (let (lambda description)
      (setf description (if (stringp (car body))
			    (pop body)
			    "")
	    lambda body)
      `(progn
	 (setf (get-test ',name)
	       (make-instance 'test-case
			      :name ',name
			      :test-lambda (lambda () ,@lambda)
			      :description ,description
			      :depends-on ',depends-on))
	 ,(if suite-supplied-p
	      `(setf (gethash ',name (tests (get-test ',suite)))
		     ',name)
	      `(setf (gethash ',name (tests (or *suite* (get-test 'NIL))))
		     ',name))
	 ',name)))))

```

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

### Enabling FiveAM Feature

Source: https://fiveam.common-lisp.dev/docs/Introduction

Adds the :5am keyword to the *features* list, allowing FiveAM test-defining code to be included inline with other code without requiring FiveAM to be loaded for package execution.

```common-lisp
(pushnew :5am *features*)
```

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

### FiveAM Run Queue Variable

Source: https://fiveam.common-lisp.dev/docs/index/permutated

The global variable `*RUN-QUEUE*` used for managing the test run queue.

```APIDOC
*RUN-QUEUE*
  A variable representing the test run queue.
```

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

### EXPLAIN! Function

Source: https://fiveam.common-lisp.dev/docs/api/function_005FIT.BESE.FIVEAM_003A_003AEXPLAIN_0021

Explains the results of a given result-list using a detailed-text-explainer. The output is directed to the *test-dribble* stream. This function is part of the fiveam testing framework.

```common-lisp
(defun explain! (result-list)
  "Explain the results of RESULT-LIST using a
detailed-text-explainer with output going to *test-dribble*"
  (explain (make-instance 'detailed-text-explainer) result-list *test-dribble*))
```

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

### FiveAM Test Suite Management

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Functions and macros for creating, defining, and managing test suites in FiveAM. This includes creating new suites, defining them, and associating tests with suites.

```APIDOC
IN-SUITE
  - Macro to specify the current test suite.
  - Usage: (IN-SUITE "My Suite" ...)

MAKE-SUITE
  - Function to create a new test suite.
  - Returns: A new test suite object.

DEF-SUITE
  - Macro to define a test suite.
  - Usage: (DEF-SUITE "My Suite" ...)

*SUITE*
  - Variable representing the current test suite.
```

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

### Result Partitioning

Source: https://fiveam.common-lisp.dev/docs/index/function

PARTITION-RESULTS is used for partitioning test results.

```common-lisp
PARTITION-RESULTS
```

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

### FiveAM Test Result Handling

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Classes and functions for managing test results, including adding results, partitioning them, and returning result lists. Covers `ADD-RESULT`, `PARTITION-RESULTS`, and `RETURN-RESULT-LIST`.

```APIDOC
ADD-RESULT
  Adds a test result.

PARTITION-RESULTS
  Partitions test results.

RETURN-RESULT-LIST
  Returns a list of test results.
```

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

### Run Resolving Dependencies

Source: https://fiveam.common-lisp.dev/docs/api/method_005FIT.BESE.FIVEAM_003A_003A_0028RUN-RESOLVING-DEPENDENCIES_0020TEST-CASE_0029

Determines if a test case and its dependencies are satisfied. It handles different states like :unknown, :resolving, and circular dependencies, updating the test status accordingly and potentially skipping tests if dependencies are not met.

```common-lisp
(defmethod run-resolving-dependencies ((test test-case))
  "Return true if this test, and its dependencies, are satisfied,
  NIL otherwise."
  (case (status test)
    (:unknown
     (setf (status test) :resolving)
     (if (or (not (depends-on test))
             (resolve-dependencies (depends-on test)))
         (progn
           (run-test-lambda test)
           (status test))
         (with-run-state (result-list)
           (unless (eql :circular (status test))
             (push (make-instance 'test-skipped 
                                  :test-case test 
                                  :reason "Dependencies not satisfied") 
                   result-list)
             (setf (status test) :depends-not-satisfied)))))
    (:resolving
     (restart-case
         (error 'circular-dependency :test-case test)
       (skip ()
	 :report (lambda (s)
		   (format s "Skip the test ~S and all its dependencies." (name test)))
	 (with-run-state (result-list)
	   (push (make-instance 'test-skipped :reason "Circular dependencies" :test-case test)
		 result-list))
	 (setf (status test) :circular))))
    (t (status test))))
```

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

### MAKE-SUITE Function Definition

Source: https://fiveam.common-lisp.dev/docs/api/function_005FIT.BESE.FIVEAM_003A_003AMAKE-SUITE

Defines the MAKE-SUITE function which creates a new test suite object. It allows specifying a name, description, and other suites to include. The function handles the creation of the suite, setting its properties, and integrating it into existing suites.

```common-lisp
(defun make-suite (name &key description in)
  "Create a new test suite object."
  (let ((suite (make-instance 'test-suite :name name)))
    (when description
      (setf (description suite) description))
    (loop for i in (ensure-list in)
	  for in-suite = (get-test i)
	  do (progn
	       (when (null in-suite)
		 (cerror "Create a new suite named ~A." "Unknown suite ~A." i)
		 (setf (get-test in-suite) (make-suite i)
		       in-suite (get-test in-suite)))
	       (setf (gethash name (tests in-suite)) suite)))
    (setf (get-test name) suite)
    suite))
```

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

### FiveAM Dependency Resolution

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Methods and generic functions for resolving test dependencies. Covers resolving dependencies for lists and symbols, and running tests with resolved dependencies.

```APIDOC
RESOLVE-DEPENDENCIES (LIST)
  Resolves dependencies for a list of test cases.

RESOLVE-DEPENDENCIES (SYMBOL)
  Resolves dependencies for a single test case symbol.

RUN-RESOLVING-DEPENDENCIES (TEST-CASE)
  Runs a test case after resolving its dependencies.

RUN-RESOLVING-DEPENDENCIES (Generic Function)
  A generic function for running tests with dependency resolution.
```

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

### FiveAM Test Generation Macros

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Documentation for macros used in generating tests within the FiveAM framework. This includes macros for creating float generators and defining test suites.

```APIDOC
GEN-FLOAT-GENERATOR
  Generates a random float.
  Usage:
    (fiveam:gen-float-generator)

FOR-ALL
  A macro for universally quantifying tests.
  Usage:
    (fiveam:for-all (variable range) body)

IN-SUITE
  Defines a test suite.
  Usage:
    (fiveam:in-suite "My Test Suite")
```

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

### WITH-FIXTURE Macro Definition

Source: https://fiveam.common-lisp.dev/docs/api/macro_005FIT.BESE.FIVEAM_003A_003AWITH-FIXTURE

Defines the WITH-FIXTURE macro, which takes a fixture name, arguments, and a body. It asserts the existence of the fixture and then executes the body within the fixture's context. This macro is useful for setting up and tearing down test environments.

```common-lisp
(defmacro with-fixture (fixture-name args &body body)
  "Insert BODY into the fixture named FIXTURE-NAME.

  See Also: DEF-FIXTURE"
  (assert (get-fixture fixture-name)
          (fixture-name)
          "Unknown fixture ~S." fixture-name)
  (destructuring-bind (largs &rest lbody) (get-fixture fixture-name)
    `(macrolet ((&body () '(progn ,@body)))
       (funcall (lambda ,largs ,@lbody) ,@args))))
```

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

### FiveAM Test Execution Functions

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Provides functions for executing tests within the FiveAM framework. Includes running a single test or performing random testing.

```APIDOC
PERFORM-RANDOM-TESTING/RUN-ONCE
  [Function]
  Runs a single random test.

PERFORM-RANDOM-TESTING
  [Function]
  Performs random testing.

PARTITION-RESULTS
  [Function]
  Partitions test results.
```

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

### FiveAM Test Execution Functions

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Functions for performing random testing and running tests with dependency resolution. Includes `PERFORM-RANDOM-TESTING` and `PERFORM-RANDOM-TESTING/RUN-ONCE`.

```APIDOC
PERFORM-RANDOM-TESTING
  Performs random testing.

PERFORM-RANDOM-TESTING/RUN-ONCE
  Performs random testing for a single run.
```

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

### FiveAM Test Execution Functions

Source: https://fiveam.common-lisp.dev/docs/Running_0020Tests

Provides functions for running and explaining test results in the FiveAM framework. RUN! is an alias for (explain (run TEST-SPEC)). EXPLAIN! details results using a text-explainer. RUN executes tests specified by TEST-SPEC. !, !!, and !!! rerun recent tests.

```APIDOC
RUN!:
  (RUN! TEST-SPEC)
  Equivalent to (explain (run TEST-SPEC)).

EXPLAIN!:
  (EXPLAIN! RESULT-LIST)
  Explain the results of RESULT-LIST using a detailed-text-explainer with output going to *test-dribble*.

RUN:
  (RUN TEST-SPEC)
  Run the test specified by TEST-SPEC.

!:
  (!)
  Rerun the most recently run test and explain the results.

!!:
  (!!)
  Rerun the second most recently run test and explain the results.

!!!:
  (!!!)
  Rerun the third most recently run test and explain the results.
```

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

### RUN! Function

Source: https://fiveam.common-lisp.dev/docs/api/function_005FIT.BESE.FIVEAM_003A_003ARUN_0021

The RUN! function is a convenience macro that executes a given test specification. It is equivalent to calling (explain (run TEST-SPEC)). It takes an optional test-spec argument, defaulting to the global *suite*.

```common-lisp
(defun run! (&optional (test-spec *suite*))
  "Equivalent to (explain (run TEST-SPEC))."
  (explain! (run test-spec)))
```

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

### FiveAM Test Execution and Result Handling

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Methods and functions for running tests and managing their results. RUN-TEST-LAMBDA executes a test case, while RETURN-RESULT-LIST and GEN-LIST handle result aggregation.

```APIDOC
RUN-TEST-LAMBDA:
  (RUN-TEST-LAMBDA test-case)
  Executes a given test case.

RETURN-RESULT-LIST:
  (RETURN-RESULT-LIST)
  Returns a list of test results.

GEN-LIST:
  (GEN-LIST)
  Generates a list, likely for test case creation or data structuring.
```

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

### FiveAM Test Execution and Control

Source: https://fiveam.common-lisp.dev/docs/index/permutated

Provides macros and functions for defining and running tests within the FiveAM framework. Includes mechanisms for skipping tests and handling test results.

```APIDOC
RUN-TEST-LAMBDA
  - Executes a test lambda.
  - Parameters:
    - TEST-CASE: The test case to run.
  - Returns: The result of the test execution.

SIGNALS
  - Macro to signal an error or condition.
  - Usage: (SIGNALS (error "message"))

SKIP
  - Macro to skip a test.
  - Usage: (SKIP "Reason for skipping")

TEST
  - Macro to define a test.
  - Usage: (TEST "Test description" (assertion))

WITH-TEST-DRIBBLE*
  - Macro to enable test dribbling.
  - Usage: (WITH-TEST-DRIBBLE* (stream) ...)
```
Tokens:
Raw