Specs

aggregate(test(), sample()) :: test()

Same as collect/2, but accepts a list of categories under which to classify the produced test case.

Specs

aggregate(test(), stats_printer(), sample()) :: test()

Same as collect/3, but accepts a list of categories under which to classify the produced test case.

Specs

check(outer_test(), counterexample(), user_opts()) :: short_result()

Re-checks a specific counterexample cexm against the property outer_test that it previously falsified.

Specs

check_spec(mfa(), user_opts()) :: result()

Tests the accuracy of an exported function's spec.

Specs

check_specs(atom(), user_opts()) :: module_result()

Tests all exported, -speced functions of a module mod against their spec.

Specs

classify(test(), boolean(), any() | sample()) :: test()

Same as collect/2, but can accept both a single category and a list of categories.

count is a boolean flag: when false, the particular test case will not be counted.

Specs

collect(test(), any()) :: test()

Specifies that test cases produced by this property should be categorized under the term category.

This field can be an expression or statement block that evaluates to any term. All produced categories are printed at the end of testing (in case no test fails) along with the percentage of test cases belonging to each category. Multiple collect wrappers are allowed in a single property, in which case the percentages for each collect wrapper are printed separately.

Specs

collect(test(), stats_printer(), any()) :: test()

Same as collect/2, but also accepts a fun printer to be used as the stats printer.

Specs

conjunction([{atom(), test()}]) :: test()

Returns a property that is true only if all of the sub-properties sub_properties are true.

Each sub-property should be tagged with a distinct atom. If this property fails, each failing sub-property will be reported and saved inside the counterexample along with its tag.

Specs

counterexample() :: counterexample() | :undefined

Retrieves the last (simplest) counterexample produced by PropCheck during the most recent testing run.

Specs

counterexample(outer_test(), user_opts()) :: long_result()

Equivalent to quickcheck/2, also accepting a list of options.

Specs

counterexamples() :: [{mfa(), counterexample()}] | :undefined

Returns a counterexample for each failing property of the most recent module testing run.

Delays the evaluation of expr.

Required for defining recursive generators and similar situations.

Specs

equals(any(), any()) :: test()

A custom property that evaluates to true only if a === b, else evaluates to false and prints "A != B" on the screen.

Examples

iex> use PropCheck
iex> quickcheck(equals(:ok, :ok))
:true

iex> use PropCheck
iex> quickcheck(
...> forall x <- :ok do
...>   equals(:ok, x)
...> end)
:true

iex> use PropCheck
iex> quickcheck(
...> forall x <- :not_ok do
...>   equals(:ok, x)
...> end)
:false

Specs

fails(outer_test()) :: outer_test()

Specifies that we expect the property property to fail for some input.

The property will be considered failing if it passes all the tests.

A property that should hold for all values generated.

iex> use PropCheck
iex> quickcheck(
...> forall n <- nat() do
...>   n >= 0
...> end)
true

If you need more than one generator, collect the generator names and the generators definitions in tuples or lists, respectively:

iex> use PropCheck
iex> quickcheck(
...> forall [n, l] <- [nat(), list(nat())] do
...>   n * Enum.sum(l) >= 0
...> end
...>)
true

Similar to let/2, multiple types can also be combined in a list of bindings:

iex> use PropCheck
iex> quickcheck(
...> forall [n <- nat(), l <- list(nat())] do
...>   n * Enum.sum(l) >= 0
...> end
...>)
true

forall allows using ExUnit assertions. By default (:quiet), no output is generated if an assertion does not hold:

iex> use PropCheck
iex> quickcheck(
...> forall n <- nat() do
...>   assert n < 0
...> end
...>)
false

Use :verbose to enable output on failed ExUnit assertions.

Setting Verbosity on the Command Line

Apart from setting :verbose or :quiet explicitly in the source code, the PROPCHECK_VERBOSE environment variable can also be used to set the verbosity. PROPCHECK_VERBOSE=1 sets :verbose, while PROPCHECK_VERBOSE=0 sets :quiet.

A property that is only tested if a condition is true.

This wrapper only makes sense when in the scope of at least one forall. The precondition field must be a boolean expression or a statement block that returns a boolean. If the precondition evaluates to false for the variable instances produced in the enclosing forall wrappers, the test case is rejected (it doesn't count as a failing test case), and PropCheck starts over with a new random test case. Also, in verbose mode, an x is printed on screen.

iex> use PropCheck
iex> require Integer
iex> quickcheck(
...> forall n <- nat() do
...>    implies rem(n, 2) == 0, do: Integer.is_even n
...> end
...>)
true

Mostly internally used macro to create a lazy value for proper.

The parameter delayed_value needs to be an already delayed value.

Binds a generator to a name for use in another generator.

The binding has the generator syntax x <- type. To produce an instance of this type, all appearances of the variables in x are replaced inside generator by their corresponding values in a randomly generated instance of type. It's OK for the gen part to evaluate to a type - in that case, an instance of the inner type is generated recursively.

iex> use PropCheck
iex> even = let n <- nat() do
...>  n * 2
...> end
iex> quickcheck(
...>   forall n <- even do
...>     rem(n, 2) == 0
...>   end)
true

If you require more than one type, put the pairs of variable and type into a list as shown in the example below.

iex> use PropCheck
iex> even_factor = let [n <- nat(), m <- nat()] do
...>  n * m * 2
...> end
iex> quickcheck(
...>   forall n <- even_factor do
...>     rem(n, 2) == 0
...>   end)
true

You also can refer to variables declared in the current let scope with ^. Such variables are not allowed to form a dependency cycle. You cannot apply ^ to variables declared outside of the let macro.

iex> use PropCheck
iex> non_decreasing =
...> let [m <- integer(^l, :inf), l <- integer(), h <- integer(^m, :inf)] do
...>  {l, m, h}
...> end
iex> quickcheck(
...>   forall {l, m, h} <- non_decreasing do
...>     l <= m and m <= h
...>   end)
true

Similar to forall/2, multiple types can also be put into tuples or lists:

iex> use PropCheck
iex> even_factor = let {n, m} <- {nat(), nat()} do
...>  n * m * 2
...> end
iex> quickcheck(
...>   forall n <- even_factor do
...>     rem(n, 2) == 0
...>   end)
true

A combination of a let and a shrink macro.

Instances are generated by applying a randomly generated list of values inside generator (just like a let, with the added constraint that the variables and types must be provided in a list - alternatively, list_of_types may be a list or vector type). When shrinking instances of such a type, the sub-instances that were combined to produce it are first tried in place of the failing instance.

One possible use is shown in the tree example. A recursive tree generator with an efficient shrinking: pick each of the subtrees in place of the tree that fails the property. l and r are assigned smaller versions of the tree thus achieving a better (or more appropriate) shrinking.

  iex> use PropCheck
  iex> tree_gen = fn (0, _, _) -> :leaf
  ...>               (s, g, tree) ->
  ...>      frequency [
  ...>       {1, tree.(0, g, tree)},
  ...>       {9, let_shrink([
  ...>         l <- tree.(div(s, 2), g, tree),
  ...>         r <- tree.(div(s, 2), g, tree)
  ...>         ]) do
  ...>           {:node, g, l, r}
  ...>         end
  ...>        }
  ...>   ]
  ...> end
  iex> tree = fn(g) -> sized(s, tree_gen.(s, g, tree_gen)) end
  iex> quickcheck(
  ...>   forall t <- tree.(int()) do
  ...>     t == :leaf or is_tuple(t)
  ...>   end
  ...>)
  true

Specs

measure(test(), title(), number() | [number()]) :: test()

A function that collects numeric statistics on the produced instances.

The number (or numbers) provided are collected and some statistics over the collected sample are printed at the end of testing (in case no test fails), prepended with title, which should be an atom or string.

Specs

module(atom(), user_opts()) :: module_result()

Tests all properties (i.e., all 0-arity functions whose name begins with prop_) exported from module mod

Specs

numtests(pos_integer(), outer_test()) :: outer_test()

Specifies the number N of tests to run when testing the property property.

Default is 100. This function only changes the number of the tests, but not the size of a test.

Specs

on_output(outer_test(), output_fun()) :: outer_test()

Specifies an output function print to be used by PropCheck for all output printing during the testing of property property.

This wrapper is equivalent to the on_output option.

Sample values from a generator gen.

Example

iex> use PropCheck
iex> produce(1)
{:ok, 1}
iex> nat() |> produce() |> Kernel.elem(1) |> is_integer()
true
iex> nat() |> list() |> produce() |> Kernel.elem(1) |> is_list()
true

Adds a setup function to the property which will be called before the first test.

This function has to return a finalize function of arity 0, which should return the atom :ok, that will be called after the last test. It is possible to use multiple property_setup macros on the same property.

Specs

quickcheck(outer_test()) :: result()

Runs PropEr on the property outer_test.

Specs

quickcheck(outer_test(), user_opts()) :: result()

Same as quickcheck/1, but also accepts a list of options.

Generates a random instance of Type, of size Size, then shrinks it as far as it goes. The value produced on each step of the shrinking process is printed on the screen.

Defines the shrinking of a generator.

shrink creates a type whose instances are generated by evaluating the statement block generator (this may evaluate to a type, which will then be generated recursively). If an instance of such a type is to be shrunk, the generators in alt_gens are first run to produce hopefully simpler instances of the type. Thus, the generators in the second argument should be simpler than the default. The simplest ones should be at the front of the list, since those are the generators preferred by the shrinking subsystem. Like the main generator, the alternatives may also evaluate to a type, which is generated recursively.

    iex> use PropCheck
    iex> quickcheck(
    ...>   forall n <- shrink(pos_integer(), [0]) do
    ...>     rem(n, 2) == 0
    ...>   end)
    false

Changes the maximum size of the generated instances.

sized creates a new type, whose instances are produced by replacing all appearances of the size parameter inside the statement block generator with the value of the size parameter. It's OK for the generator to return a type - in that case, an instance of the inner type is generated recursively.

An example for sized is shown in the documentation of let_shrink/2.

This produces a specialization of a generator, encoded as a binding of form x <- type (as in the let macro).

The specialization of members of type that satisfy the constraint condition - that is, those members for which the function fn(x) -> condition end returns true. If the constraint is very strict - that is, only a small percentage of instances of type pass the test - it will take a lot of tries for the instance generation subsystem to randomly produce a valid instance. This will result in slower testing, and testing may even be stopped short, in case the :constraint_tries limit is reached (see the "Options" section).

It probably will be more appropriate to generate valid instances of the specialized type using the let macro. Also make sure that even small instances can satisfy the constraint, since PropEr will only increase the size of generated instances when it can find an instance passing the constraint test. If this is not possible, you can instruct PropEr to start at a larger size, by supplying a suitable value for the :start_size option (see the "Options" section).

In the second example below, :start_size set to 2 is required, because otherwise PropCheck would first try to generate lists of size 1 (or less), but such a list will never satisfy the length constraint, and after :constraint_tries limit has been reached, PropCheck would give up.

Examples

iex> use PropCheck
iex> even = such_that n <- nat(), when: rem(n, 2) == 0
iex> quickcheck(
...>   forall n <- even do
...>     rem(n, 2) == 0
...>   end)
true

iex> use PropCheck
iex> twofer_list = such_that l <- list(nat()), when: length(l) > 1
iex> quickcheck(
...>   forall [_ | t] <- twofer_list do
...>     Enum.any?(t)
...>   end, [start_size: 2])
true

Equivalent to the such_that macro, but the constraint condition is considered non-strict: if the :constraint_tries limit is reached, the generator will just return an instance of type instead of failing, even if that instance doesn't satisfy the constraint.

iex> use PropCheck
iex> even = such_that_maybe n <- nat(), when: rem(n, 2) == 0
iex> quickcheck(
...>   forall n <- even do
...>     rem(n, 2) == 0
...>   end)
true

Signifies that prop should be considered failing if it takes more than time_limit milliseconds to return.

The purpose of this wrapper is to test code that may hang if something goes wrong. timeout cannot contain any more wrappers.

iex> use PropCheck
iex> quickcheck(
...>   timeout(100, forall n <- nat() do
...>     :ok == :timer.sleep(n*100)
...>   end)
...> )
false

If the code inside prop spawns and links to a process that dies abnormally, PropEr will catch the exit signal and treat it as a test failure, instead of crashing.

trap_exit cannot contain any more wrappers.

iex> use PropCheck
iex> quickcheck(
...>   trap_exit(forall n <- nat() do
...>     # this must fail
...>     _pid = spawn_link(fn() -> n / 0 end)
...>     # wait for arrivial of the dieing linked process signal
...>     :timer.sleep(50)
...>     true #
...>   end)
...> )
false

Execute an action, if the property fails.

The action field should contain an expression or statement block that produces some side-effect (e.g. prints something to the screen). In case this test fails, action will be executed. Note that the output of such actions is not affected by the verbosity setting of the main application.

iex> use PropCheck
iex> quickcheck(
...>   when_fail(false, IO.puts "when_fail: Property failed")
...>)
false

Specs

with_title(title()) :: stats_printer()

A predefined function that accepts an atom or string and returns a stats printing function which is equivalent to the default one, but prints the given title title above the statistics.