module Test:sig
..end
A test is a pair of a generator and a property that all generated values must satisfy.
The main features of this module are:
QCheck2.Test.make
to create a testQCheck2.Test.make_neg
to create a negative test that is expected not to satisfy the tested propertyQCheck2.Test.check_exn
to run a single test with a simple runner.A test fails if the property does not hold for a given input. The simple form or the rich form) offer more elaborate forms to fail a test.
Note that while QCheck2.Test.check_exn
is provided for convenience to discover QCheck or to run a single test in utop, to run QCheck tests in your project you probably want to opt for a more advanced runner, or convert
QCheck tests to your favorite test framework:
QCheck_base_runner
for a QCheck-only runner (useful if you don't have or don't need another test framework)QCheck_alcotest
to convert to Alcotest frameworkQCheck_ounit
to convert to OUnit frameworktype 'a
cell
A single property test on a value of type 'a
. A QCheck2.Test.t
wraps a cell
and hides its type parameter.
val make_cell : ?if_assumptions_fail:[ `Fatal | `Warning ] * float ->
?count:int ->
?long_factor:int ->
?negative:bool ->
?max_gen:int ->
?max_fail:int ->
?retries:int ->
?name:string ->
?print:'a QCheck2.Print.t ->
?collect:('a -> string) ->
?stats:'a QCheck2.stat list ->
'a QCheck2.Gen.t -> ('a -> bool) -> 'a cell
make_cell gen prop
builds a test that checks property prop
on instances
of the generator gen
.
if_assumptions_fail
: the minimum
fraction of tests that must satisfy the precondition for a success
to be considered valid.
The fraction should be between 0. and 1.
A warning will be emitted otherwise if
the flag is `Warning
, the test will be a failure if the flag is `Fatal
.
(since 0.10)count
: number of test cases to run, counting only
the test cases which satisfy preconditions.long_factor
: the factor by which to multiply count, max_gen and
max_fail when running a long test (default: 1).negative
: whether the test is expected not to satisfy the tested property.max_gen
: maximum number of times the generation function
is called in total to replace inputs that do not satisfy
preconditions (should be >= count).max_fail
: maximum number of failures before we stop generating
inputs. This is useful if shrinking takes too much time.retries
: number of times to retry the tested property while shrinking.name
: the name of the test.collect
: (* collect values by tag, useful to display distribution of generated *)stats
: on a distribution of values of type 'aval make_cell_from_QCheck1 : ?if_assumptions_fail:[ `Fatal | `Warning ] * float ->
?count:int ->
?long_factor:int ->
?negative:bool ->
?max_gen:int ->
?max_fail:int ->
?retries:int ->
?name:string ->
gen:(Stdlib.Random.State.t -> 'a) ->
?shrink:('a -> ('a -> unit) -> unit) ->
?print:('a -> string) ->
?collect:('a -> string) ->
stats:'a QCheck2.stat list -> ('a -> bool) -> 'a cell
QCheck2.Test.make_cell
instead.⚠️ Do not use, this is exposed for internal reasons only. ⚠️
val get_law : 'a cell -> 'a -> bool
val get_name : 'a cell -> string
val get_gen : 'a cell -> 'a QCheck2.Gen.t
val get_print_opt : 'a cell -> 'a QCheck2.Print.t option
val get_collect_opt : 'a cell -> ('a -> string) option
val get_stats : 'a cell -> 'a QCheck2.stat list
val set_name : 'a cell -> string -> unit
val get_count : 'a cell -> int
Get the count of a cell.
val get_long_factor : 'a cell -> int
Get the long factor of a cell.
val get_positive : 'a cell -> bool
Get the expected mode of a cell: positive indicates expected to satisfy the tested property, negative indicates expected not to satisfy the tested property.
type
t =
| |
Test : |
(* | Same as | *) |
val make : ?if_assumptions_fail:[ `Fatal | `Warning ] * float ->
?count:int ->
?long_factor:int ->
?max_gen:int ->
?max_fail:int ->
?retries:int ->
?name:string ->
?print:'a QCheck2.Print.t ->
?collect:('a -> string) ->
?stats:'a QCheck2.stat list ->
'a QCheck2.Gen.t -> ('a -> bool) -> t
make gen prop
builds a test that checks property prop
on instances
of the generator gen
.
See QCheck2.Test.make_cell
for a description of the parameters.
val make_neg : ?if_assumptions_fail:[ `Fatal | `Warning ] * float ->
?count:int ->
?long_factor:int ->
?max_gen:int ->
?max_fail:int ->
?retries:int ->
?name:string ->
?print:'a QCheck2.Print.t ->
?collect:('a -> string) ->
?stats:'a QCheck2.stat list ->
'a QCheck2.Gen.t -> ('a -> bool) -> t
make_neg gen prop
builds a test that checks property prop
on instances
of the generator gen
.
The test is considered negative, meaning that it is expected not to satisfy the tested property.
This information is recorded in an underlying test cell
entry and interpreted suitably by test runners.
See QCheck2.Test.make_cell
for a description of the parameters.
val test_get_count : t -> int
val test_get_long_factor : t -> int
val fail_report : string -> 'a
Fail the test with some additional message that will be reported.
val fail_reportf : ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a
Format version of QCheck2.Test.fail_report
.
Example:
Test.fail_reportf
"Value N = %i should be greater than M = %i for Foo = %a" n m pp_foo foo
include QCheck2.Test_exceptions
val print_instance : 'a cell -> 'a -> string
val print_c_ex : 'a cell -> 'a QCheck2.TestResult.counter_ex -> string
val print_fail : 'a cell ->
string -> 'a QCheck2.TestResult.counter_ex list -> string
val print_fail_other : string -> msg:string -> string
val print_expected_failure : 'a cell -> 'a QCheck2.TestResult.counter_ex list -> string
val print_error : ?st:string ->
'a cell ->
string -> 'a QCheck2.TestResult.counter_ex * exn -> string
val print_test_fail : string -> string list -> string
val print_test_error : string -> string -> exn -> string -> string
val print_collect : (string, int) Stdlib.Hashtbl.t -> string
Print "collect" results.
val print_stat : 'a QCheck2.stat * (int, int) Stdlib.Hashtbl.t -> string
Print statistics.
val check_result : 'a cell -> 'a QCheck2.TestResult.t -> unit
For a positive test check_result cell res
checks that res
is Ok _
, and returns unit.
For a negative test check_result cell res
checks that res
is Failed _
, and returns unit.
Otherwise, it raises some exception.
Test_fail
if the test is positive and res = Failed _
Test_unexpected_success
if the test is negative and res = Ok _
Test_error
if res = Error _
type
res =
| |
Success |
| |
Failure |
| |
FalseAssumption |
| |
Error of |
type 'a
event =
| |
Generating |
| |
Collecting of |
| |
Testing of |
| |
Shrunk of |
| |
Shrinking of |
type'a
handler =string -> 'a cell -> 'a event -> unit
Handler executed after each event during testing of an instance.
type'a
step =string -> 'a cell -> 'a -> res -> unit
Callback executed after each instance of a test has been run. The callback is given the instance tested, and the current results of the test.
type'a
callback =string -> 'a cell -> 'a QCheck2.TestResult.t -> unit
Callback executed after each test has been run.
f name cell res
means test cell
, named name
, gave res
.
val check_cell : ?long:bool ->
?call:'a callback ->
?step:'a step ->
?handler:'a handler ->
?rand:Stdlib.Random.State.t ->
'a cell -> 'a QCheck2.TestResult.t
check_cell ~long ~rand test
generates up to count
random
values of type 'a
using Gen.t
and the random state st
. The
predicate law
is called on them and if it returns false
or raises an
exception then we have a counter-example for the law
.
Note: check_cell
ignores a test's polarity, acting as
described above regardless of whether the tested cell is a
positive or negative test.
long
: if true
then multiply the number of instances to generate
by the cell's long_factor.call
: function called on each test case, with the result.step
: function called on each instance of the test case, with the result.val check_cell_exn : ?long:bool ->
?call:'a callback ->
?step:'a step ->
?handler:'a handler ->
?rand:Stdlib.Random.State.t -> 'a cell -> unit
Same as QCheck2.Test.check_cell
but calls QCheck2.Test.check_result
on the result.
check_cell test
honors test polarity and thus expects positive tests to succeed
without finding a counterexample and expects negative tests to fail by finding one.
Test_fail
if the test is positive and res = Failed _
Test_unexpected_success
if the test is negative and res = Success _
Test_error
if res = Error _
val check_exn : ?long:bool -> ?rand:Stdlib.Random.State.t -> t -> unit
Checks the property against some test cases, and calls QCheck2.Test.check_result
,
which might raise an exception in case of failure.
check_exn test
honors test polarity and thus expects positive tests to succeed
without finding a counterexample and expects negative tests to fail by finding one.
Test_fail
if the test is positive and res = Failed _
Test_unexpected_success
if the test is negative and res = Success _
Test_error
if res = Error _