Module `QCheck2.Test`Source

A test is a pair of a generator and a property that all generated values must satisfy.

The main features of this module are:

make to create a test
make_neg to create a negative test that is expected not to satisfy the tested property
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 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 framework
QCheck_ounit to convert to OUnit framework

Sourcetype 'a cell

A single property test on a value of type 'a. A Test.t wraps a cell and hides its type parameter.

Source

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 Print.t ->
  ?collect:('a -> string) ->
  ?stats:'a stat list ->
  'a Gen.t ->
  ('a -> bool) ->
  'a cell

make_cell gen prop builds a test that checks property prop on instances of the generator gen.

parameter name
the name of the test.

parameter count
number of test cases to run, counting only the test cases which satisfy preconditions.

parameter long_factor
the factor by which to multiply count, max_gen and max_fail when running a long test (default: 1).

parameter negative
whether the test is expected not to satisfy the tested property.

parameter max_gen
maximum number of times the generation function is called in total to replace inputs that do not satisfy preconditions (should be >= count).

parameter max_fail
maximum number of failures before we stop generating inputs. This is useful if shrinking takes too much time.

parameter retries
number of times to retry the tested property while shrinking.

parameter 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)

parameter print
used in Print to display generated values failing the prop

parameter collect
(* collect values by tag, useful to display distribution of generated *)

parameter stats
on a distribution of values of type 'a

Source

val 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:(Random.State.t -> 'a) ->
  ?shrink:('a -> ('a -> unit) -> unit) ->
  ?print:('a -> string) ->
  ?collect:('a -> string) ->
  stats:'a stat list ->
  ('a -> bool) ->
  'a cell

⚠️ Do not use, this is exposed for internal reasons only. ⚠️

deprecated
Migrate to QCheck2 and use make_cell instead.

Sourceval get_law : 'a cell -> 'a -> bool

Sourceval get_name : _ cell -> string

Sourceval get_gen : 'a cell -> 'a Gen.t

Sourceval get_print_opt : 'a cell -> 'a Print.t option

Sourceval get_collect_opt : 'a cell -> ('a -> string) option

Sourceval get_stats : 'a cell -> 'a stat list

Sourceval set_name : _ cell -> string -> unit

Sourceval get_count : _ cell -> int

Get the count of a cell.

since 0.5.3

Sourceval get_long_factor : _ cell -> int

Get the long factor of a cell.

since 0.5.3

Sourceval get_positive : _ 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.

Sourcetype t =

| Test : 'a cell -> t
(*
Same as 'a cell, but masking the type parameter. This allows to put tests on different types in the same list of tests.
*)

Source

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 Print.t ->
  ?collect:('a -> string) ->
  ?stats:'a stat list ->
  'a Gen.t ->
  ('a -> bool) ->
  t

make gen prop builds a test that checks property prop on instances of the generator gen. See make_cell for a description of the parameters.

Source

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 Print.t ->
  ?collect:('a -> string) ->
  ?stats:'a stat list ->
  'a 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 make_cell for a description of the parameters.

Sourceval test_get_count : t -> int

Sourceval test_get_long_factor : t -> int

Sourceval fail_report : string -> 'a

Fail the test with some additional message that will be reported.

since 0.7

Sourceval fail_reportf : ('a, Format.formatter, unit, 'b) format4 -> 'a

Format version of fail_report.

Example:

  Test.fail_reportf
    "Value N = %i should be greater than M = %i for Foo = %a" n m pp_foo foo

since 0.7

Running the test

include module type of Test_exceptions

Sourceexception Test_fail of string * string list

Exception raised when a test failed, with the list of counter-examples. Test_fail (name, l) means test name failed on elements of l.

Sourceexception Test_error of string * string * exn * string

Exception raised when a test raised an exception e, with the sample that triggered the exception. Test_error (name, i, e, st) means name failed on i with exception e, and st is the stacktrace (if enabled) or an empty string.

Sourceexception Test_unexpected_success of string

Exception raised when a negative test failed. Test_unexpected_success name means test name failed to find an expected counter example.

Sourceval print_instance : 'a cell -> 'a -> string

Sourceval print_c_ex : 'a cell -> 'a TestResult.counter_ex -> string

Sourceval print_fail : 'a cell -> string -> 'a TestResult.counter_ex list -> string

Sourceval print_fail_other : string -> msg:string -> string

Sourceval print_expected_failure : 'a cell -> 'a TestResult.counter_ex list -> string

Source

val print_error : 
  ?st:string ->
  'a cell ->
  string ->
  ('a TestResult.counter_ex * exn) ->
  string

Sourceval print_test_fail : string -> string list -> string

Sourceval print_test_error : string -> string -> exn -> string -> string

Sourceval print_collect : (string, int) Hashtbl.t -> string

Print "collect" results.

since 0.6

Sourceval print_stat : ('a stat * (int, int) Hashtbl.t) -> string

Print statistics.

since 0.6

Sourceval check_result : 'a cell -> 'a 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.

raises Test_fail
if the test is positive and res = Failed _

raises Test_unexpected_success
if the test is negative and res = Ok _

raises Test_error
if res = Error _

Sourcetype res =

| Success
| Failure
| FalseAssumption
| Error of exn * string

Sourcetype 'a event =

| Generating
| Collecting of 'a
| Testing of 'a
| Shrunk of int * 'a
| Shrinking of int * int * 'a

Sourcetype 'a handler = string -> 'a cell -> 'a event -> unit

Handler executed after each event during testing of an instance.

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

Sourcetype 'a callback = string -> 'a cell -> 'a TestResult.t -> unit

Callback executed after each test has been run. f name cell res means test cell, named name, gave res.

Source

val check_cell : 
  ?long:bool ->
  ?call:'a callback ->
  ?step:'a step ->
  ?handler:'a handler ->
  ?rand:Random.State.t ->
  'a cell ->
  'a 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.

parameter long
if true then multiply the number of instances to generate by the cell's long_factor.

parameter call
function called on each test case, with the result.

parameter step
function called on each instance of the test case, with the result.

returns
the result of the test.

Source

val check_cell_exn : 
  ?long:bool ->
  ?call:'a callback ->
  ?step:'a step ->
  ?handler:'a handler ->
  ?rand:Random.State.t ->
  'a cell ->
  unit

Same as check_cell but calls 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.

raises Test_fail
if the test is positive and res = Failed _

raises Test_unexpected_success
if the test is negative and res = Success _

raises Test_error
if res = Error _

Sourceval check_exn : ?long:bool -> ?rand:Random.State.t -> t -> unit

Checks the property against some test cases, and calls 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.

raises Test_fail
if the test is positive and res = Failed _

raises Test_unexpected_success
if the test is negative and res = Success _

raises Test_error
if res = Error _

Install

Dune Dependency

Authors

Maintainers

Sources

doc/qcheck-core/QCheck2/Test/index.html

Module `QCheck2.Test`Source

Running the test

package qcheck-core

Install

Dune Dependency

Authors

Maintainers

Sources

doc/qcheck-core/QCheck2/Test/index.html

Module QCheck2.TestSource

Running the test

Module `QCheck2.Test`Source