The cl-quickcheck Reference Manual

Table of Contents

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

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.


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

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

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

2 Systems

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


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

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)


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

3 Files

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


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

3.1 Lisp


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

3.1.1 cl-quickcheck.asd

Location

cl-quickcheck.asd

Systems

cl-quickcheck (system)


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

3.1.2 cl-quickcheck/cl-quickcheck.lisp

Parent

cl-quickcheck (system)

Location

cl-quickcheck.lisp

Packages

cl-quickcheck

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-quickcheck

Source

cl-quickcheck.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


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

5.1.1 Special variables

Special Variable: *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)


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

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)


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

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)


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

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)


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

5.2 Internal definitions


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

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)


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

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)


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

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-quickcheck.asd: The cl-quickcheck<dot>asd file
cl-quickcheck/cl-quickcheck.lisp: The cl-quickcheck/cl-quickcheck<dot>lisp file

F
File, Lisp, cl-quickcheck.asd: The cl-quickcheck<dot>asd file
File, Lisp, cl-quickcheck/cl-quickcheck.lisp: The cl-quickcheck/cl-quickcheck<dot>lisp file

L
Lisp File, cl-quickcheck.asd: The cl-quickcheck<dot>asd file
Lisp File, cl-quickcheck/cl-quickcheck.lisp: The cl-quickcheck/cl-quickcheck<dot>lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   (  
A   C   D   F   G   H   I   J   L   M   N   O   P   Q   R   S   T   U   V   W  
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

Jump to:   (  
A   C   D   F   G   H   I   J   L   M   N   O   P   Q   R   S   T   U   V   W  

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

A.3 Variables

Jump to:   *  
A   B   D   F   K   M   N   S  
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

Jump to:   *  
A   B   D   F   K   M   N   S  

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

A.4 Data types

Jump to:   C   P   S   T  
Index Entry  Section

C
cl-quickcheck: The cl-quickcheck system
cl-quickcheck: The cl-quickcheck package

P
Package, cl-quickcheck: The cl-quickcheck package

S
Structure, test: Exported structures
System, cl-quickcheck: The cl-quickcheck system

T
test: Exported structures

Jump to:   C   P   S   T