EQC

This module contains macros to be used with Quviq QuickCheck. It defines Elixir versions of the Erlang macros found in eqc/include/eqc.hrl. For detailed documentation of the macros, please refer to the QuickCheck documentation.

Copyright (C) Quviq AB, 2014.

Summary

always(n, prop)

Repeat a property several times

collect(xs)

A property combinator to obtain test statistics

ensure(expr)

A property checking an operation and prints when relation is violated

feature(term, prop)
forall(bind, prop)

A property that should hold for all values generated by a generator

implies(pre, prop)

Add a precondition to a property

lazy(gen)

Make a generator lazy

let(bind, gen)

Bind a generated value for use by another generator

let_shrink(bind, gen)

Like let/2 but adds shrinking behaviour

once_only(prop)

A property that is only executed once for each test case

setup(setup, opts)

Setup for a test run

setup_teardown(setup, opts)

Setup and tear-down for a test run

shrink(g, gs)

Add shrinking behaviour to a generator

sized(n, prop)

Bind the current size parameter

sometimes(n, prop)

Repeat a property several times, failing only if the property fails every time

such_that(bind, pred)

Generate a value that satisfies a given predicate

such_that_maybe(bind, pred)

Generate a value that satisfies a given predicate, or false if no value is found

timeout(limit, prop)

Set a time limit on a property

trap_exit(prop)

Run a property in a separate process and trap exits

when_fail(action, prop)

Perform an action when a test fails

Functions

feature(term, prop)

Macros

always(n, prop)

Repeat a property several times.

Usage:

always n do
  prop
end

The property succeeds if all n tests of prop succeed.

In Erlang: ?ALWAYS(N, Prop).

collect(xs)

A property combinator to obtain test statistics

Usage: collect KeywordList, in: prop end

Example: forall {m, n} <- {int, int} do collect m: m, n: n, in: length(Enum.to_list(m .. n)) == abs(n - m) + 1 end

ensure(expr)

A property checking an operation and prints when relation is violated

Usage:

ensure t1 == t2
ensure t1 > t2

In Erlang ?WHENFAILS(eqc:format("not ensured: ~p ~p ~p ",[T1, Operator, T2]), T1 Operator T2).

forall(bind, prop)

A property that should hold for all values generated by a generator.

Usage:

forall pat <- gen do
  prop
end

The variables of pat are bound in prop.

In Erlang: ?FORALL(Pat, Gen, Prop).

implies(pre, prop)

Add a precondition to a property.

Usage:

implies pre do
  prop
end

Any test case not satisfying the precondition will be discarded.

In Erlang: ?IMPLIES(Pre, Prop).

lazy(gen)

Make a generator lazy.

Usage:

lazy do: gen

The generator is not evaluated until a value is generated from it. Crucial when building recursive generators.

In Erlang: ?LAZY(Gen).

let(bind, gen)

Bind a generated value for use by another generator.

Usage:

let pat <- gen1 do
  gen2
end

The variables of pat are bound in gen2.

In Erlang: ?LET(Pat, Gen1, Gen2).

let_shrink(bind, gen)

Like let/2 but adds shrinking behaviour.

Usage:

let_shrink pat <- gen1 do
  gen2
end

Here gen1 must generate a list of values, each of which is added as a possible shrinking of the result.

In Erlang: ?LETSHRINK(Pat, Gen1, Gen2).

once_only(prop)

A property that is only executed once for each test case.

Usage:

once_only do
  prop
end

Repeated tests are generated but not run, and shows up as xs in the test output. Useful if running tests is very expensive.

In Erlang: ?ONCEONLY(Prop).

setup(setup, opts)

Setup for a test run.

Usage:

setup function do
  prop
end

Performs setup before a test run (default 100 tests) without teardown function after the test run.

In Erlang: ?SETUP(fun() -> X = Setup, fun() -> ok end, Prop).

setup_teardown(setup, opts)

Setup and tear-down for a test run.

Usage:

setup_teardown(setup) do
  prop
after
  x -> teardown
end

Performs setup before a test run (default 100 tests) and teardown after the test run. The result of setup is bound to x in teardown, allowing passing resources allocated in setup to teardown. The after argument is optional.

In Erlang: ?SETUP(fun() -> X = Setup, fun() -> Teardown end, Prop).

shrink(g, gs)

Add shrinking behaviour to a generator.

Usage:

shrink g, gs

Generates a value from g that can shrink to a value generated by any of the generators in gs.

In Erlang: ?SHRINK(G, Gs).

sized(n, prop)

Bind the current size parameter.

Usage:

sized n, do: prop

In prop, n is bound to the current size.

In Erlang: ?SIZED(N, Prop)

sometimes(n, prop)

Repeat a property several times, failing only if the property fails every time.

Usage:

sometimes n do
  prop
end

The property succeeds if any of the n tests of prop succeed.

In Erlang: ?SOMETIMES(N, Prop).

such_that(bind, pred)

Generate a value that satisfies a given predicate.

Throws an exception if no value is found after 100 attempts. Usage:

such_that pat <- gen, do: pred

The variables of pat are bound in pred.

In Erlang: ?SUCHTHAT(Pat, Gen, Pred).

such_that_maybe(bind, pred)

Generate a value that satisfies a given predicate, or false if no value is found.

Usage:

such_that_maybe pat <- gen, do: pred

The variables of pat are bound in pred.

In Erlang: ?SUCHTHATMAYBE(Pat, Gen, Pred).

timeout(limit, prop)

Set a time limit on a property.

Usage:

timeout limit do
  prop
end

Causes the property to fail if it doesn't complete within the time limit.

In Erlang: ?TIMEOUT(Limit, Prop).

trap_exit(prop)

Run a property in a separate process and trap exits.

Usage:

trap_exit do
  prop
end

Prevents a property from crashing if a linked process exits.

In Erlang: ?TRAPEXIT(Prop).

when_fail(action, prop)

Perform an action when a test fails.

Usage:

when_fail(action) do
  prop
end

Typically the action will be printing some diagnostic information.

In Erlang: ?WHENFAIL(Action, Prop).