Module QCheck2

Introduction

This library takes inspiration from Haskell's QuickCheck library. The rough idea is that the programmer describes invariants that values of a certain type need to satisfy ("properties"), as functions from this type to bool. They also need to describe how to generate random values of the type, so that the property is tried and checked on a number of random instances.

This explains the organization of this module:

• Gen is used to describe how to generate random values. Auxiliary module Print can be used along with Test.make to build one's own generator instances.

• Test is used to describe a single test, that is, a property of type 'a -> bool combined with an 'a Gen.t that is used to generate the test cases for this property. Optional parameters allow to specify the random generator state, number of instances to generate and test, etc.

💡 If you are migrating from QCheck, check the migration guide below.

Examples

• "List.rev is involutive" (the test passes so check_exn returns ()):

let test =
  QCheck2.(Test.make ~count:1000
            ~print:Print.(list int)
            Gen.(list int)
            (fun l -> List.rev (List.rev l) = l));;

QCheck2.Test.check_exn test;;

• "All lists are sorted" (false property that will fail):

  • QCheck tests this property on random lists and finds a counter-example
  • QCheck then looks for the smallest counter-example possible (here [1; 0]) to help you find the problem (called "shrinking")

let test = QCheck2.(
    Test.make
      ~name:"All lists are sorted"
      ~count:10_000
      ~print:Print.(list int)
      Gen.(list small_nat)
      (fun l -> l = List.sort compare l));;

QCheck2.Test.check_exn test;;

Exception:
  test `All lists are sorted` failed on ≥ 1 cases:
  [1; 0] (after 5 shrink steps)

• Generate 20 random trees using Gen.fix :

type tree = Leaf of int | Node of tree * tree

let leaf x = Leaf x
let node x y = Node (x,y)

let tree_gen = QCheck2.Gen.(sized @@ fix
                              (fun self n -> match n with
                                 | 0 -> map leaf nat
                                 | n ->
                                   frequency
                                     [1, map leaf nat;
                                      2, map2 node (self (n/2)) (self (n/2))]
                              ));;

QCheck2.Gen.generate ~n:20 tree_gen;;

since

0.18

Tests

A test is a universal property of type foo -> bool for some type foo, with an object of type foo Gen.t used to generate values of type foo.

See Test.make to build a test, and Test.check_exn to run one test simply. For more serious testing, it is better to create a testsuite and use QCheck_runner.

Migration to QCheck2

QCheck2 is a major release and as such, there are (as few as possible) breaking changes, as well as functional changes you should be aware of.