Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the org.melusina.confidence Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 04:37:15 2022 GMT+0.
Next: Systems, Previous: The org.melusina.confidence Reference Manual, Up: The org.melusina.confidence Reference Manual [Contents][Index]
Confidence is a test framework for Common Lisp that focuses on simplicty. It avoids bureacracy and makes it easy to work interactively, without a complicated setup, and with explicit functions and decisions.
This software is Copyright © 2019–2022 Michaël Le Barbier and is distributed under the terms described in the LICENSE file.
A file featuring evaluable toplevel forms allows new users to test Confidence and learn how to use it. It is located under example/example.lisp in the repository.
There is a reference manual which can be built locally using TexInfo and
the development/makedoc script or downloaded from GitHub actions:
https://github.com/melusina-org/cl-confidence/actions
Look for the artefacts on a recent workflow run, three files are available: PDF, HTML and INFO.
;;
Here is a list of public repositories using Confidence:
Next: Modules, Previous: Introduction, Up: The org.melusina.confidence Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Next: Files, Previous: Systems, Up: The org.melusina.confidence Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
org.melusina.confidence (system).
Next: Packages, Previous: Modules, Up: The org.melusina.confidence Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: org.melusina.confidence/src/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
org.melusina.confidence (system).
Next: org.melusina.confidence/src/utilities.lisp, Previous: org.melusina.confidence/org.melusina.confidence.asd, Up: Lisp [Contents][Index]
src (module).
Next: org.melusina.confidence/src/assertion.lisp, Previous: org.melusina.confidence/src/package.lisp, Up: Lisp [Contents][Index]
src (module).
Next: org.melusina.confidence/src/result.lisp, Previous: org.melusina.confidence/src/utilities.lisp, Up: Lisp [Contents][Index]
src (module).
Next: org.melusina.confidence/src/testcase.lisp, Previous: org.melusina.confidence/src/assertion.lisp, Up: Lisp [Contents][Index]
src (module).
Next: org.melusina.confidence/src/entrypoint.lisp, Previous: org.melusina.confidence/src/result.lisp, Up: Lisp [Contents][Index]
src (module).
Previous: org.melusina.confidence/src/testcase.lisp, Up: Lisp [Contents][Index]
src (module).
Next: Definitions, Previous: Files, Up: The org.melusina.confidence Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The org.melusina.confidence Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
The precision used to compare of double precision floats.
This number can be understood as the number of matching digits in the binary representation
of the fractional part of float numbers, yet distinct tests interpret this value differently.
The precision used to compare of single precision floats.
This number can be understood as the number of matching digits in the binary representation
of the fractional part of float numbers, yet distinct tests interpret this value differently.
Flag governing the interactive mode of testcases.
When the flag is a generalised boolean, a failed assertion can be retried. When
the flag is NIL, the toplevel testcase is exiting the program when done.
The default value of the parameter is based on the :SWANK feature.
A unique identfier for the current testsuite run batch.
The basename for the testsuite.
Usually TESTSUITE but commonly used values are ACCEPTANCE, INTEGRATION, PREFLIGHT, etc.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Assert that the evaluation of FORM signals a CONDITION.
It is possible to perform arbitrary checks on the condition by providing SLOTS,
which are bound to the generated condition slots as in WITH-SLOTS and the given
BODY yielding a boolean validating details of the assertion. When this boolean
is NIL, a string must be returned as second value to explain why the validation
failed.
Define an assertion function NAME, accepting LAMBDA-LIST with BODY.
The BODY is interpreted as computing a generalised boolean value,
which determines if the assertion is a success or failure. When it is a success,
a single value T is returned. When it is a failure, two values NIL and a descriptive
string are returned.
The NAME must start with ASSERT-, ASSERT<, ASSERT> or ASSERT=.
When the first BODY form is a string, this string is used as an informational message
when reporting the corresponding error condition. It is also used as a documentaion
string for the created function.
When the next BODY form starts with the keyword :REPORT, then the rest of that form must be function of a STREAM. This function is then used to generate an informational message when reporting the corresponding error condition. This allows to add dynamic context to this informational messsage, like the value of some variables.
Define a test case function TESTCASE-NAME, accepting TESTCASE-ARGS with BODY.
The BODY is examined and assertions spotted in it are wrapped with extra code
installing restarts and aggregating results for assertions and nested testcases..
The return value of a testcase is a RESULT, holding a precise description of test that
ran and their outcomes.
When *TESTCASE-INTERACTIVE-P* is NIL, batch mode is assumed and a summary of
failures is printed on stdout and the program is exited with a status
reflecting the failure or success of tests.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Assert that A and B satisfy the EQ predicate.
Assert that A and B satisfy the EQL predicate.
Assert that A and B satisfy the EQUAL predicate.
Assert that FLOAT1 is approximately equal to FLOAT2.
This means that FLOAT1 and FLOAT2 are in a neighbourhood whose size is based
on the magnitude orders of FLOAT1 and FLOAT2 and the floating point precision.
A specific FLOAT-TYPE of ’SINGLE-FLOAT or ’DOUBLE-FLOAT can be explicitly supplied.
Assert that FLOAT1 is defintely greater than FLOAT2.
This means that FLOAT1 is greater than FLOAT2 and not in a neighbourhood of FLOAT2
whose diameter is controlled by the INACCURACY, the magnitude orders of FLOAT1 and
FLOAT2 and the floating point precision.
A specific FLOAT-TYPE of ’SINGLE-FLOAT or ’DOUBLE-FLOAT can be explicitly supplied.
Assert that FLOAT1 is definetely less than FLOAT2
This means that FLOAT2 is greater than FLOAT1 and not in a neighbourhood of FLOAT1
whose diameter is controlled by the INACCURACY, the magnitude orders of FLOAT1 and
FLOAT2 and the floating point precision.
A specific FLOAT-TYPE of ’SINGLE-FLOAT or ’DOUBLE-FLOAT can be explicitly supplied.
Asssert that FLOAT1 is essentially equal to FLOAT2.
This means that FLOAT1 and FLOAT2 are in a neighbourhood whose size is based
on the magnitude orders of FLOAT1 and FLOAT2 and the floating point precision.
A specific FLOAT-TYPE of ’SINGLE-FLOAT or ’DOUBLE-FLOAT can be explicitly supplied.
Assert that LIST1 and LIST2 are equal.
Lists are equal if they have the same length and have equal elements at each
index. The equality predicate used to compare elements is either EQL or the predicate
provided by the :TEST keyword argument.
Assert that EXPR is NIL.
Assert that LIST1 denotes the same set as LIST2.
Assert that STRING1 and STRING2 satisfy the STRING-EQUAL predicate. This assertion supports the same keyword parameters as STRING-EQUAL.
Assert that TEXT matches globbing PATTERN.
Assert that STRING1 and STRING2 satisfy the STRING< predicate. This assertion supports the same keyword parameters as STRING<.
Assert that STRING1 and STRING2 satisfy the STRING<= predicate. This assertion supports the same keyword parameters as STRING<=.
Assert that STRING1 and STRING2 satisfy the STRING= predicate. This assertion supports the same keyword parameters as STRING=.
Assert that STRING1 and STRING2 satisfy the STRING> predicate. This assertion supports the same keyword parameters as STRING>.
Assert that STRING1 and STRING2 satisfy the STRING>= predicate. This assertion supports the same keyword parameters as STRING>=.
Assert that the set represented by LIST1 is a subset of LIST2.
Assert that EXPR is T.
This does not compare EXPR to T as a generalised boolean, cf. ASSERT-T*.
Assert that EXPR is true as a generalised boolean.
Assert that EXPR evaluates to a value of type TYPE.
Assert that VECTOR1 and VECTOR2 are equal.
Vectors are equal if they have the same length and have equal elements at each
index. The equality predicate used to compare elements is either EQL or the predicate
provided by the :TEST keyword argument.
Assert that A and B satisfy the < predicate.
Assert that A and B satisfy the <= predicate.
Assert that A and B satisfy the = predicate.
Assert that A and B satisfy the > predicate.
Assert that A and B satisfy the >= predicate.
List assertions exported by PACKAGE-DESIGNATOR.
List testcases exported by PACKAGE-DESIGNATOR.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Next: Classes, Previous: Generic functions, Up: Public Interface [Contents][Index]
Previous: Standalone methods, Up: Public Interface [Contents][Index]
A class capturing an assertion that signaled a condition instead of returning normally.
common-lisp.
(error "an assertion-condition requires a :condition.")
:condition
A class capturing an assertion failure.
A detailed description on why the assertion failed.
(error "an assertion-failure requires a :description.")
:description
A class capturing an assertion success.
A class capturing a testcase result.
(error "a testcase-result requires a :name.")
:name
The list of evaluated arguments for the testcase.
:argument-values
The total number of assertions in the testcase and its descendants.
0
The total number of assertions that yielded a success in the testcase and its descendants.
0
The total number of assertions that yielded a failure in the testcase and its descendants.
0
The total number of assertions that yielded a condition in the testcase and its descendants.
common-lisp.
0
The list of testcase results and assertions results yielded by descendants.
(error "a testcase-result requires a list of :results.")
:results
Previous: Public Interface, Up: Definitions [Contents][Index]
The set of characters used for base 36 encoding.
The set of characters used for base 64 encoding.
The set of hexadecimal characters.
The result of the current testcase.
The current path in the testcase hierarchy.
This is a list of symbols designating the argument-less testcases in the call stack.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Supervise the execution of the assertion FORM and return ASSERTION evaluation details. This makes sure that the returned type for FORM is an instance of RESULT and guarantees that conditions triggered by the evaluation of arguments are recorded.
Walks through BODY-FORMS and wrap assertion forms in a RESTART-CASE.
Export RESULT description.
Guess which CI/CD tool this process is running under.
The returned value is one of:
NIL, :GOCD, :JENKINS, :GITHUB-ACTIONS, :CIRCLECI
References:
* GoCD: https://docs.gocd.org/current/faq/dev_use_current_revision_in_build.html
* Jenkins: https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#using-environment-variables
* GitHub Actions: https://docs.github.com/en/actions/learn-github-actions/environment-variables
* CircleCI: https://circleci.com/docs/2.0/env-vars/
Make a good value for *TESTSUITE-ID* based on *TESTSUITE-NAME* and CI/CD tool used.
Maybe print details about RESULT and exit the program.
When *TESTCASE-INTERACTIVE-P* is NIL, batch mode is assumed and a summary of failures is printed on stdout and the program is exited with a status reflecting the failure or success of tests.
Prepare a random alphabetic string of given LENGTH.
The returned string contains LENGTH characters chosen from
the vector ALPHABET. When ALPHABET is one of the keywords
:HEXADECIMAL :BASE36 and :BASE64
the corresponding alphabet is used.
This uses a very weak method that does not try to avoid collisions.x
Record RESULT in TESTCASE-RESULT.
Predicate recognising TEXT matching a globbing PATTERN.
Concatenate STRINGS.
This is a shortand which is useful in combination to reader macros.
Supervise the execution of ARGUMENTS-LAMBDA and ASSERTION-LAMBDA.
The pathname used to write RESULT description.
Previous: Ordinary functions, Up: Internals [Contents][Index]
A class capturing an assertion result.
One of the keywords :FUNCTION or :MACRO according to the nature of the assertion.
common-lisp.
:function
:type
The symbol designating the assertion that yielded this result. This is the first element of the FORM.
(error "an assertion-result requires a :name.")
:name
The list of evaluated arguments for the assertion.
(error "an assertion-result requires an :argument-values list.")
:argument-values
The list of argument names for the assertion.
(error "an assertion-result requires an :argument-names list.")
:argument-names
The form for the assertion invocation.
(error "an assertion-result requires a :form.")
:form
The abstract class of testcase results.
The path of the result in the test hierarchy.
This is the stack of preceding testcases in the test hierarchy.
:path
Previous: Definitions, Up: The org.melusina.confidence Reference Manual [Contents][Index]
| Jump to: | A D E F G I L M P R S T |
|---|
| Jump to: | A D E F G I L M P R S T |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
A C D F N P R S T |
|---|
| Jump to: | *
A C D F N P R S T |
|---|
| Jump to: | A C E F M O P R S T U |
|---|
| Jump to: | A C E F M O P R S T U |
|---|