The cl-quickcheck Reference Manual
Table of Contents
The cl-quickcheck Reference Manual
This is the cl-quickcheck Reference Manual, version 0.4,
generated automatically by Declt version 2.4 "Will Decker"
on Wed Jun 20 11:20:35 2018 GMT+0.
1 Introduction
cl-quickcheck - a Common Lisp port of the QuickCheck unit test framework
EXAMPLE
$ clisp example.lisp
Starting tests with seed #S(RANDOM-STATE #*1111111000010000101001011100110101100110011101010000110100110111)
...
ERROR (ISNT MONEY= (DOLLARS 'M) (FRANCS M))
=: M is not a number
with values #S(MONEY :AMOUNT M :CURRENCY USD) #S(MONEY :AMOUNT -2 :CURRENCY FRANC)
for ((M -2))
100/100 counterexamples.
FAIL (IS MONEY= (DOLLARS M) (DOLLARS N))
with values #S(MONEY :AMOUNT 11 :CURRENCY USD) #S(MONEY :AMOUNT -19 :CURRENCY USD)
for ((M 11) (N -19))
98/100 counterexamples.
0 cases checked and passed in 100 attempts.
95 tests submitted; 2 FAILED.
See example.lisp for more information.
INSTALL
$ clisp
> (ql:quickload 'cl-quickcheck)
REQUIREMENTS
Optional
DEVELOPMENT
Testing
Ensure the example script works as expected:
$ bundle
$ cucumber
Feature: Run example tests
Scenario: Running example tests # features/run_example_tests.feature:3
Given the program has finished # features/step_definitions/steps.rb:1
Then the output is correct for each test # features/step_definitions/steps.rb:5
1 scenario (1 passed)
2 steps (2 passed)
0m4.913s
Guard can automatically run testing when the code changes:
$ bundle
$ guard -G Guardfile-cucumber
...
Linting
Keep the code tidy:
$ npm install
$ rake lint
...
2 Systems
The main system appears first, followed by any subsystem dependency.
2.1 cl-quickcheck
- Author
Andrew Pennebaker <andrew.pennebaker@gmail.com>
- License
MIT
- Description
Common Lisp port of the QuickCheck unit test framework
- Version
0.4
- Source
cl-quickcheck.asd (file)
- Component
cl-quickcheck.lisp (file)
3 Files
Files are sorted by type and then listed depth-first from the systems
components trees.
3.1 Lisp
3.1.1 cl-quickcheck.asd
- Location
cl-quickcheck.asd
- Systems
cl-quickcheck (system)
3.1.2 cl-quickcheck/cl-quickcheck.lisp
- Parent
cl-quickcheck (system)
- Location
cl-quickcheck.lisp
- Packages
cl-quickcheck
- Exported Definitions
-
- Internal Definitions
-
4 Packages
Packages are listed by definition order.
4.1 cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Use List
common-lisp
- Exported Definitions
-
- Internal Definitions
-
5 Definitions
Definitions are sorted by export status, category, package, and then by
lexicographic order.
5.1 Exported definitions
5.1.1 Special variables
- Special Variable: *break-on-failure*
-
When true, test failures jump us immediately into the debugger.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: *loud*
-
When true, we show progress as tests are run with dots to stdout.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: *num-trials*
-
Number of random trials we want to see pass in FOR-ALL tests.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: *size*
-
Bounds the size of random test cases in a generator-dependent way.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: *testing*
-
When true, we’re in the dynamic extent of a quickcheck form.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: a-boolean
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: a-real
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: an-index
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: an-integer
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: k-generator
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: m-generator
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Special Variable: n-generator
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
5.1.2 Macros
- Macro: define BINDING &body BODY
-
Like Scheme’s top-level DEFINE, more or less.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: for-all BINDINGS &body BODY
-
Perform the test in BODY for random values of BINDINGS.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: is FN &rest OPERANDS
-
Test that FN applied to OPERANDS is true, with the failure message
detailing the failing arguments.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: is= X Y
-
Test that X is EQUAL to Y.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: isnt FN &rest OPERANDS
-
Test that FN applied to OPERANDS is false.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: isnt= X Y
-
Test that X is not EQUAL to Y.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: named NAME &body TESTS
-
Perform the given TESTS with all the test names set to NAME.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: only-if FLAG TEST
-
Perform the TEST only if FLAG is true, otherwise return a SKIPPED
test result whose name is TEST quoted.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: pick-weighted &body CHOICES
-
Given CHOICES with constant weights, pick a random one at runtime.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: quickcheck &body BODY
-
Run BODY and report the results of any tests.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: should-signal CONDITION &body BODY
-
Test that evaluating BODY signals (a subtype of) CONDITION.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: test FLAG
-
Test that FLAG is true.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: wrap-each WRAPPER &body WRAPPEES
-
Perform each of the WRAPPEES as if surrounded by WRAPPER (with
the literal symbol WRAPPEE inside WRAPPER being the hole where the
wrappee appears). This is useful for factoring out common setup/teardown
code for a sequence of tests without compromising their isolation.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
5.1.3 Functions
- Function: a-char ()
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: a-list GENERATOR
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: a-member &rest GENERATORS
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: a-string ()
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: a-symbol ()
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: a-tuple &rest GENERATORS
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: collect-test-results FN
-
Call FN with *TESTING* true, and return a list of the test results.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: generate GENERATOR
-
Ask GENERATOR to produce a value.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: report TEST-CASES
-
Print out the interesting test results in longer form.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-bindings INSTANCE
-
- Function: (setf test-bindings) VALUE INSTANCE
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-detail INSTANCE
-
- Function: (setf test-detail) VALUE INSTANCE
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-flopped INSTANCE
-
- Function: (setf test-flopped) VALUE INSTANCE
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-name INSTANCE
-
- Function: (setf test-name) VALUE INSTANCE
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
5.1.4 Structures
- Structure: test ()
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Direct superclasses
structure-object (structure)
- Direct slots
- Slot: name
-
- Readers
test-name (function)
- Writers
(setf test-name) (function)
- Slot: flopped
-
- Readers
test-flopped (function)
- Writers
(setf test-flopped) (function)
- Slot: detail
-
- Readers
test-detail (function)
- Writers
(setf test-detail) (function)
- Slot: bindings
-
- Readers
test-bindings (function)
- Writers
(setf test-bindings) (function)
5.2 Internal definitions
5.2.1 Special variables
- Special Variable: *logger*
-
Function to do whatever’s appropriate with the result of each test
as it completes.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
5.2.2 Macros
- Macro: capture-stdout &body BODY
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Macro: let-dfv ((NAME PARAMS &body BODY1)) &body BODY2
-
Bind a dynamic function variable, with CALL-NEXT-FUNCTION in its
body calling the same variable as bound in the enclosing dynamic scope.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
5.2.3 Functions
- Function: answer NAME FLOPPED &optional DETAIL
-
Log a test outcome, with appropriate interactive side effects.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: call-tester PASSP-FN
-
Call PASSP-FN and return whether it flopped.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: classify FLOPPED
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: collect-dups TESTS
-
Return a hashtable from names of elements of TESTS to lists of the
elements with the same name.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: concat-symbol &rest PARTS
-
Intern a symbol by catenating PARTS.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: copy-test INSTANCE
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: default-generator NAME
-
Give a generator expression for a name that’s missing an explicit one.
You’ll have to define the meaning of this shorthand elsewhere.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: distribution TESTS
-
Count test cases failed, skipped, passed, and total.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: hash-table-values TABLE
-
Return a list of TABLE’s values in arbitrary order.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: intercept-errors FN
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: is-macro FORM FN OPERANDS
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: judgedp OPT-COUNT
-
OPT-COUNT describes a repeated test: NIL if it ever failed,
otherwise a count of passed trials. Return true iff the test has
either passed *NUM-TRIALS* times or failed at least once.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: make-test &key (NAME NAME) (FLOPPED FLOPPED) (DETAIL DETAIL) (BINDINGS BINDINGS)
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: normalize-binding BINDING
-
Return BINDING’s pair of name and generator expression.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: print-test TEST
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: random-element LIST
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-for-all TEST-FN VARS &rest GENERATORS
-
Repeatedly call TEST-FN with VARS bound to values from GENERATORS.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-is-tester NAME FN-FN
-
Return a test outcome from the result of FN-FN, which returns a
list of a function to call for the actual test, plus its arguments.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-named NAME FN
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-only-if FLAG-NAME FLAG-FN NAME TEST-FN
-
Behavior of the ONLY-IF macro.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-quickcheck FN
-
Call FN to run a test suite, and report the result.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-should-signal NAME EXPECTED-CONDITION FN
-
Test that calling FN signals (a subtype of) EXPECTED-CONDITION.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-tester NAME PASSP-FN
-
Return a test outcome from calling PASSP-FN.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: run-trial TEST-FN VARS GENERATORS
-
Run one trial of a FOR-ALL test.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: show-progress FLOPPED
-
Write a single character as a bird’s-eye view of a test result.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: sort-out TESTS
-
Collect the test cases of TESTS into separate lists by name, and
return them in order of the first appearance of a case with that name.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: summarize-all VERDICTS
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: summarize-test CASES
-
Report the results of the test cases of a test, if they’re interesting.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: tally TEST OPT-COUNT
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-failed TEST
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-p OBJECT
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-passed TEST
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: test-skipped TEST
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: unique-names TESTS
-
Return the test-names of TESTS, in order of first appearance.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: update-bindings TEST BINDINGS
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: update-name TEST NAME
-
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
- Function: verdict TESTS
-
Choose the most significant result from TESTS: failed, passed, or
skipped, in that order.
- Package
cl-quickcheck
- Source
cl-quickcheck.lisp (file)
Appendix A Indexes
A.1 Concepts
A.2 Functions
| Index Entry | | Section |
|
( | | |
| (setf test-bindings) : | | Exported functions |
| (setf test-detail) : | | Exported functions |
| (setf test-flopped) : | | Exported functions |
| (setf test-name) : | | Exported functions |
|
A | | |
| a-char : | | Exported functions |
| a-list : | | Exported functions |
| a-member : | | Exported functions |
| a-string : | | Exported functions |
| a-symbol : | | Exported functions |
| a-tuple : | | Exported functions |
| answer : | | Internal functions |
|
C | | |
| call-tester : | | Internal functions |
| capture-stdout : | | Internal macros |
| classify : | | Internal functions |
| collect-dups : | | Internal functions |
| collect-test-results : | | Exported functions |
| concat-symbol : | | Internal functions |
| copy-test : | | Internal functions |
|
D | | |
| default-generator : | | Internal functions |
| define : | | Exported macros |
| distribution : | | Internal functions |
|
F | | |
| for-all : | | Exported macros |
| Function, (setf test-bindings) : | | Exported functions |
| Function, (setf test-detail) : | | Exported functions |
| Function, (setf test-flopped) : | | Exported functions |
| Function, (setf test-name) : | | Exported functions |
| Function, a-char : | | Exported functions |
| Function, a-list : | | Exported functions |
| Function, a-member : | | Exported functions |
| Function, a-string : | | Exported functions |
| Function, a-symbol : | | Exported functions |
| Function, a-tuple : | | Exported functions |
| Function, answer : | | Internal functions |
| Function, call-tester : | | Internal functions |
| Function, classify : | | Internal functions |
| Function, collect-dups : | | Internal functions |
| Function, collect-test-results : | | Exported functions |
| Function, concat-symbol : | | Internal functions |
| Function, copy-test : | | Internal functions |
| Function, default-generator : | | Internal functions |
| Function, distribution : | | Internal functions |
| Function, generate : | | Exported functions |
| Function, hash-table-values : | | Internal functions |
| Function, intercept-errors : | | Internal functions |
| Function, is-macro : | | Internal functions |
| Function, judgedp : | | Internal functions |
| Function, make-test : | | Internal functions |
| Function, normalize-binding : | | Internal functions |
| Function, print-test : | | Internal functions |
| Function, random-element : | | Internal functions |
| Function, report : | | Exported functions |
| Function, run-for-all : | | Internal functions |
| Function, run-is-tester : | | Internal functions |
| Function, run-named : | | Internal functions |
| Function, run-only-if : | | Internal functions |
| Function, run-quickcheck : | | Internal functions |
| Function, run-should-signal : | | Internal functions |
| Function, run-tester : | | Internal functions |
| Function, run-trial : | | Internal functions |
| Function, show-progress : | | Internal functions |
| Function, sort-out : | | Internal functions |
| Function, summarize-all : | | Internal functions |
| Function, summarize-test : | | Internal functions |
| Function, tally : | | Internal functions |
| Function, test-bindings : | | Exported functions |
| Function, test-detail : | | Exported functions |
| Function, test-failed : | | Internal functions |
| Function, test-flopped : | | Exported functions |
| Function, test-name : | | Exported functions |
| Function, test-p : | | Internal functions |
| Function, test-passed : | | Internal functions |
| Function, test-skipped : | | Internal functions |
| Function, unique-names : | | Internal functions |
| Function, update-bindings : | | Internal functions |
| Function, update-name : | | Internal functions |
| Function, verdict : | | Internal functions |
|
G | | |
| generate : | | Exported functions |
|
H | | |
| hash-table-values : | | Internal functions |
|
I | | |
| intercept-errors : | | Internal functions |
| is : | | Exported macros |
| is-macro : | | Internal functions |
| is= : | | Exported macros |
| isnt : | | Exported macros |
| isnt= : | | Exported macros |
|
J | | |
| judgedp : | | Internal functions |
|
L | | |
| let-dfv : | | Internal macros |
|
M | | |
| Macro, capture-stdout : | | Internal macros |
| Macro, define : | | Exported macros |
| Macro, for-all : | | Exported macros |
| Macro, is : | | Exported macros |
| Macro, is= : | | Exported macros |
| Macro, isnt : | | Exported macros |
| Macro, isnt= : | | Exported macros |
| Macro, let-dfv : | | Internal macros |
| Macro, named : | | Exported macros |
| Macro, only-if : | | Exported macros |
| Macro, pick-weighted : | | Exported macros |
| Macro, quickcheck : | | Exported macros |
| Macro, should-signal : | | Exported macros |
| Macro, test : | | Exported macros |
| Macro, wrap-each : | | Exported macros |
| make-test : | | Internal functions |
|
N | | |
| named : | | Exported macros |
| normalize-binding : | | Internal functions |
|
O | | |
| only-if : | | Exported macros |
|
P | | |
| pick-weighted : | | Exported macros |
| print-test : | | Internal functions |
|
Q | | |
| quickcheck : | | Exported macros |
|
R | | |
| random-element : | | Internal functions |
| report : | | Exported functions |
| run-for-all : | | Internal functions |
| run-is-tester : | | Internal functions |
| run-named : | | Internal functions |
| run-only-if : | | Internal functions |
| run-quickcheck : | | Internal functions |
| run-should-signal : | | Internal functions |
| run-tester : | | Internal functions |
| run-trial : | | Internal functions |
|
S | | |
| should-signal : | | Exported macros |
| show-progress : | | Internal functions |
| sort-out : | | Internal functions |
| summarize-all : | | Internal functions |
| summarize-test : | | Internal functions |
|
T | | |
| tally : | | Internal functions |
| test : | | Exported macros |
| test-bindings : | | Exported functions |
| test-detail : | | Exported functions |
| test-failed : | | Internal functions |
| test-flopped : | | Exported functions |
| test-name : | | Exported functions |
| test-p : | | Internal functions |
| test-passed : | | Internal functions |
| test-skipped : | | Internal functions |
|
U | | |
| unique-names : | | Internal functions |
| update-bindings : | | Internal functions |
| update-name : | | Internal functions |
|
V | | |
| verdict : | | Internal functions |
|
W | | |
| wrap-each : | | Exported macros |
|
A.3 Variables
| Index Entry | | Section |
|
* | | |
| *break-on-failure* : | | Exported special variables |
| *logger* : | | Internal special variables |
| *loud* : | | Exported special variables |
| *num-trials* : | | Exported special variables |
| *size* : | | Exported special variables |
| *testing* : | | Exported special variables |
|
A | | |
| a-boolean : | | Exported special variables |
| a-real : | | Exported special variables |
| an-index : | | Exported special variables |
| an-integer : | | Exported special variables |
|
B | | |
| bindings : | | Exported structures |
|
D | | |
| detail : | | Exported structures |
|
F | | |
| flopped : | | Exported structures |
|
K | | |
| k-generator : | | Exported special variables |
|
M | | |
| m-generator : | | Exported special variables |
|
N | | |
| n-generator : | | Exported special variables |
| name : | | Exported structures |
|
S | | |
| Slot, bindings : | | Exported structures |
| Slot, detail : | | Exported structures |
| Slot, flopped : | | Exported structures |
| Slot, name : | | Exported structures |
| Special Variable, *break-on-failure* : | | Exported special variables |
| Special Variable, *logger* : | | Internal special variables |
| Special Variable, *loud* : | | Exported special variables |
| Special Variable, *num-trials* : | | Exported special variables |
| Special Variable, *size* : | | Exported special variables |
| Special Variable, *testing* : | | Exported special variables |
| Special Variable, a-boolean : | | Exported special variables |
| Special Variable, a-real : | | Exported special variables |
| Special Variable, an-index : | | Exported special variables |
| Special Variable, an-integer : | | Exported special variables |
| Special Variable, k-generator : | | Exported special variables |
| Special Variable, m-generator : | | Exported special variables |
| Special Variable, n-generator : | | Exported special variables |
|
A.4 Data types