The test-utils Reference Manual

Table of Contents

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

The test-utils Reference Manual

This is the test-utils Reference Manual, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 15:08:37 2019 GMT+0.


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

1 Introduction

Test Utils

:test-utils provides convenience functions and macros for :prove and :cl-quickcheck. Specifically, its aim is to make it simple to use the two together.

:test-utils is still a work in progress. So, you know, careful. To be fair though, I am using this in some serious projects where testing is going to be important, so it won't be too much of a moving target.

Basic Usage

(tests
 (is (+ 1 2) 3 "Addition works")
 (is (+ 3 3 3 6) 15 "Addition works on more than two numbers")
 (is (+ -1 -1 -1) -3 "Addition works on negative numbers")
 (is (+ -1 2) 1 "Addition works on negative and positive numbers together")

 (for-all ((a a-number) (b a-number))
   (is= (+ a b) (+ b a))
   "Addition is commutative"))

This test suite will pass with flying colors.

; SLIME 2015-06-01
CL-USER> (ql:quickload :test-utils)
To load "test-utils":
  Load 1 ASDF system:
    test-utils
; Loading "test-utils"
..................................................
[package test-utils]
(:TEST-UTILS)
CL-USER> (defpackage :testing (:use :cl :test-utils))
#<PACKAGE "TESTING">
CL-USER> (in-package :testing)
#<PACKAGE "TESTING">
TESTING> (tests
 (is (+ 1 2) 3 "Addition works")
 (is (+ 3 3 3 6) 15 "Addition works on more than two numbers")
 (is (+ -1 -1 -1) -3 "Addition works on negative numbers")
 (is (+ -1 2) 1 "Addition works on negative and positive numbers together")

 (for-all ((a a-number) (b a-number))
   (is= (+ a b) (+ b a))
   "Addition is commutative"))
1..5

  ✓ Addition works
  ✓ Addition works on more than two numbers
  ✓ Addition works on negative numbers
  ✓ Addition works on negative and positive numbers together
  ✓ Addition is commutative

✓ 5 tests completed (3ms)
T
TESTING>

It combines four prove tests, and one cl-quickcheck test.

Exported Symbols

In addition to the below, test-utils exports all test symbols from prove, and all symbols from cl-quickcheck except for cl-quickcheck:is and cl-quickcheck:isnt. Instead, you should use is= inside of for-all blocks.

Re-exported Generators

test-utils exports cl-quickcheck symbols for all primitive generators. These are

They work exactly the same way as the direct cl-quickcheck generators, but are exported in the variable namespace so that you don't have to randomly prefix some of them with #' when composing or calling generate.

The compound generators

are also re-exported, but remain in the function namespace for easier composition.

New Generators

Lets get the obvious ones out of the way first. New primitve generators are

They generate lisp ratios, arbitrary lisp numerics, symbols in the :keyword package, and arbitrary atomic values respectively.

New compound generators are

a-pair generates cons cells, a-vector generates vectors and a-hash generates hash-tables.

New generators that require some notes are

tests (&rest forms)

A macro that counts off the given tests and calls prove:finalize after all tests. It automates some otherwise manual book-keeping required by prove. It takes any number of prove tests.

qchecks (quickcheck-test &optional message)

Runs a cl-quickcheck test in the context of a prove test suite, with optional message.

quiet-check (&body body)

Runs a cl-quickcheck suite, but squelches initial random seed reporting, and only sends to *standard-output* on failure, rather than unconditionally.

for-all ((&rest bindings) test &optional message)

Shorthand for a single-clause (qchecks (for-all (...) ...)) with optional message. This is a common enough use case for me that went ahead and put in the shortcut.

TODOs/Thoughts


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 test-utils

Author

inaimathi <leo.zovic@gmail>

License

MIT Expat <http://directory.fsf.org/wiki/License:Expat>

Description

Convenience functions and macros for testing Common Lisp applications via Prove and Quickcheck

Dependencies
Source

test-utils.asd (file)

Components

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 test-utils.asd

Location

test-utils.asd

Systems

test-utils (system)


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

3.1.2 test-utils/package.lisp

Parent

test-utils (system)

Location

package.lisp

Packages

test-utils


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

3.1.3 test-utils/test-utils.lisp

Dependency

package.lisp (file)

Parent

test-utils (system)

Location

test-utils.lisp

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 test-utils

Source

package.lisp (file)

Use List
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: a-keyword
Package

test-utils

Source

test-utils.lisp (file)

Special Variable: a-number
Package

test-utils

Source

test-utils.lisp (file)

Special Variable: a-ratio
Package

test-utils

Source

test-utils.lisp (file)

Special Variable: a-value
Package

test-utils

Source

test-utils.lisp (file)

Special Variable: an-atom
Package

test-utils

Source

test-utils.lisp (file)


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

5.1.2 Macros

Macro: for-all (&rest BINDINGS) TEST &optional MESSAGE
Package

test-utils

Source

test-utils.lisp (file)

Macro: qchecks QUICKCHECK-TEST &optional MESSAGE

Form for calling quickcheck tests from a prove test (this lets you easily execute :quickcheck properties as part of a prove:run)

Package

test-utils

Source

test-utils.lisp (file)

Macro: quiet-check &body BODY

Like :quickcheck, but squelches the initial seed reporting. Useful for running quickcheck properties in the middle of :prove suites.

Package

test-utils

Source

test-utils.lisp (file)

Macro: tests &rest FORMS

This hacks around :prove’s requirement that a number of forms be provided, and #’prove:finalze be called around each set of :prove tests. Pointed out at https://github.com/fukamachi/prove/issues/14, but not yet addressed.

Package

test-utils

Source

test-utils.lisp (file)


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

5.1.3 Functions

Function: a-hash KEY-GENERATOR VALUE-GENERATOR
Package

test-utils

Source

test-utils.lisp (file)

Function: a-pair A-GENERATOR B-GENERATOR
Package

test-utils

Source

test-utils.lisp (file)

Function: a-specific-alist &rest K/GEN-PAIRS
Package

test-utils

Source

test-utils.lisp (file)

Function: a-specific-hash &rest K/GEN-PAIRS
Package

test-utils

Source

test-utils.lisp (file)

Function: a-specific-plist &rest K/GEN-PAIRS
Package

test-utils

Source

test-utils.lisp (file)

Function: a-vector GENERATOR
Package

test-utils

Source

test-utils.lisp (file)

Function: one-of &rest ELEMS
Package

test-utils

Source

test-utils.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Functions

Function: a-plist KEY-GENERATOR VALUE-GENERATOR
Package

test-utils

Source

test-utils.lisp (file)

Function: an-alist KEY-GENERATOR VALUE-GENERATOR
Package

test-utils

Source

test-utils.lisp (file)

Function: an-array DIMENSIONS GENERATOR
Package

test-utils

Source

test-utils.lisp (file)

Function: an-improper-list GENERATOR
Package

test-utils

Source

test-utils.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, test-utils.asd: The test-utils<dot>asd file
File, Lisp, test-utils/package.lisp: The test-utils/package<dot>lisp file
File, Lisp, test-utils/test-utils.lisp: The test-utils/test-utils<dot>lisp file

L
Lisp File, test-utils.asd: The test-utils<dot>asd file
Lisp File, test-utils/package.lisp: The test-utils/package<dot>lisp file
Lisp File, test-utils/test-utils.lisp: The test-utils/test-utils<dot>lisp file

T
test-utils.asd: The test-utils<dot>asd file
test-utils/package.lisp: The test-utils/package<dot>lisp file
test-utils/test-utils.lisp: The test-utils/test-utils<dot>lisp file

Jump to:   F   L   T  

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

A.2 Functions

Jump to:   A   F   M   O   Q   T  
Index Entry  Section

A
a-hash: Exported functions
a-pair: Exported functions
a-plist: Internal functions
a-specific-alist: Exported functions
a-specific-hash: Exported functions
a-specific-plist: Exported functions
a-vector: Exported functions
an-alist: Internal functions
an-array: Internal functions
an-improper-list: Internal functions

F
for-all: Exported macros
Function, a-hash: Exported functions
Function, a-pair: Exported functions
Function, a-plist: Internal functions
Function, a-specific-alist: Exported functions
Function, a-specific-hash: Exported functions
Function, a-specific-plist: Exported functions
Function, a-vector: Exported functions
Function, an-alist: Internal functions
Function, an-array: Internal functions
Function, an-improper-list: Internal functions
Function, one-of: Exported functions

M
Macro, for-all: Exported macros
Macro, qchecks: Exported macros
Macro, quiet-check: Exported macros
Macro, tests: Exported macros

O
one-of: Exported functions

Q
qchecks: Exported macros
quiet-check: Exported macros

T
tests: Exported macros

Jump to:   A   F   M   O   Q   T  

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

A.3 Variables

Jump to:   A   S  
Index Entry  Section

A
a-keyword: Exported special variables
a-number: Exported special variables
a-ratio: Exported special variables
a-value: Exported special variables
an-atom: Exported special variables

S
Special Variable, a-keyword: Exported special variables
Special Variable, a-number: Exported special variables
Special Variable, a-ratio: Exported special variables
Special Variable, a-value: Exported special variables
Special Variable, an-atom: Exported special variables

Jump to:   A   S  

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

A.4 Data types

Jump to:   P   S   T  
Index Entry  Section

P
Package, test-utils: The test-utils package

S
System, test-utils: The test-utils system

T
test-utils: The test-utils system
test-utils: The test-utils package

Jump to:   P   S   T