type 'a printer = Format.formatter -> 'a -> unit
pretty-printers for items generated by Crowbar; useful for the user in translating test failures into bugfixes.
val int : int gen
int generates an integer ranging from min_int to max_int, inclusive. If you need integers from a smaller domain, consider using
val uint8 : int gen
uint8 generates an unsigned byte, ranging from 0 to 255 inclusive.
val int8 : int gen
int8 generates a signed byte, ranging from -128 to 127 inclusive.
val uint16 : int gen
uint16 generates an unsigned 16-bit integer, ranging from 0 to 65535 inclusive.
val int16 : int gen
int16 generates a signed 16-bit integer, ranging from -32768 to 32767 inclusive.
val float : float gen
float generates a double-precision floating-point number.
val char : char gen
char generates a char.
val bytes : string gen
bytes generates a string of arbitrary length (including zero-length strings).
val bytes_fixed : int -> string gen
bytes_fixed length generates a string of the specified length.
val bool : bool gen
bool generates a yes or no answer.
val range : ?min:int -> int -> int gen
range ?min n is a generator for integers between
min (inclusive) and
min + n (exclusive). Default
min value is 0.
range ?min n will raise
n <= 0.
map gens map_fn provides a means for creating generators using other generators' output. For example, one might generate a Char.t from a
open Crowbar let char_gen : Char.t gen = map [uint8] Char.chr
unlazy gen forces the generator
gen. It is useful when defining generators for recursive data types:
open Crowbar type a = A of int | Self of a let rec a_gen = lazy ( choose [ map [int] (fun i -> A i); map [(unlazy a_gen)] (fun s -> Self s); ]) let lazy a_gen = a_gen
fix fn applies the function
fn. It is useful when defining generators for recursive data types:
open Crowbar type a = A of int | Self of a let rec a_gen = fix (fun a_gen -> choose [ map [int] (fun i -> A i); map [a_gen] (fun s -> Self s); ])
val const : 'a -> 'a gen
const a always generates
option gen generates either
Some x, where
x is the item generated by
pair gena gen generates (a, b) where
a is generated by
result gena genb generates either
Ok va or
Error vb, where
vb are generated by
list gen makes a generator for lists using
gen. Lists may be empty; for non-empty lists, use
list1 gen makes non-empty list generators. For potentially empty lists, use
val shuffle : 'a list -> 'a list gen
shuffle l generates random permutations of
concat_gen_list sep l concatenates a list of string gen
l inserting the separator
sep between each
with_printer printer gen generates the same values as
gen is used to create a failing test case and the test was reached by calling
printer will be used to print the failing test case.
dynamic_bind gen f is a monadic bind, it allows to express the generation of a value whose generator itself depends on a previously generated value. This is in contrast with
map gen f, where no further generation happens in
gen has generated an element.
An typical example where this sort of dependencies is required is a serialization library exporting combinators letting you build values of the form
'a serializer. You may want to test this library by first generating a pair of a serializer and generator
'a serializer * 'a gen for arbitrary
'a, and then generating values of type
'a depending on the (generated) generator to test the serializer. There is such an example in the
examples/serializer/ directory of the Crowbar implementation.
Because the structure of a generator built with
dynamic_bind is opaque/dynamic (it depends on generated values), the Crowbar library cannot analyze its statically (without generating anything) -- the generator is opaque to the library, hidden in a function. In particular, many optimizations or or fuzzing techniques based on generator analysis are impossible. As a client of the library, you should avoid
dynamic_bind whenever it is not strictly required to express a given generator, so that you can take advantage of these features (present or future ones). Use the least powerful/complex combinators that suffice for your needs.
val pp_int : int printer
val pp_float : float printer
val pp_bool : bool printer
val pp_string : string printer
val add_test : ?name:string -> ( 'f, unit ) gens -> 'f -> unit
add_test name generators test_fn adds
test_fn to the list of eligible tests to be run when the program is invoked. At runtime, random data will be sent to
generators to create the input necessary to run
test_fn. Any failures will be printed annotated with
guard b aborts a test if
b is false. The test will not be recorded or reported as a failure.
bad_test () aborts a test. The test will not be recorded or reported as a failure.
nonetheless o aborts a test if
o is None. The test will not be recorded or reported as a failure.
failf format ... generates a test failure and prints the message specified by the format string
format and the following arguments. It is set up so that
%a calls for an
'a printer and an
check b generates a test failure if
b is false. No useful information will be printed in this case.
val check_eq : ?pp:'a printer -> ?cmp:( 'a -> 'a -> int ) -> ?eq:( 'a -> 'a -> bool ) -> 'a -> 'a -> unit
check_eq pp cmp eq x y evaluates whether x and y are equal, and if they are not, raises a failure and prints an error message. Equality is evaluated as follows:
- use a provided
- if no
eqis provided, use a provided
- if neither
cmpis provided, use Stdlib.compare
pp is provided, use this to print
y if they are not equal. If
pp is not provided, a best-effort printer will be generated from the printers for primitive generators and any printers registered with
with_printer and used.