eqc_ex v1.4.2 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-2016.

Summary

Functions

Property combinator that is true if all components are true. The tags are used to report the counterexample

Macros

A property combinator to obtain test statistics for sequences

Repeat a property several times

A property combinator to obtain test statistics

A property checking an operation and prints when relation is violated. In postconditions, one uses satisfy instead

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

Add a precondition to a property

Make a generator lazy

Bind a generated value for use by another generator

Like let/2 but adds shrinking behaviour

A property combinator to obtain test statistics for numbers

A property that is only executed once for each test case

Wraps an expression that may raise an exception such that if the exception is of the expected error kind, this error is returned as a value, not raised as an exception

A condition modifier for operators to be used in postconditions. Instead of returning false, it returns a tuple representation of failing operator

Setup for a test run

Setup and tear-down for a test run

Add shrinking behaviour to a generator

Bind the current size parameter

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

Generate a value that satisfies a given predicate

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

Set a time limit on a property

Run a property in a separate process and trap exits

Perform an action when a test fails

Functions

conjunction(kvlist)

Property combinator that is true if all components are true. The tags are used to report the counterexample.

Example

property "Sort" do
  forall l <- list(int()) do
    sorted = sort(l)
    conjunction in_order: in_order?(sorted),
                same_element: same_elements(l, sorted),
                same_length: ensure length(l) == length(sorted)
  end
end
feature(term, prop)

Macros

aggregate(xs, prop)

A property combinator to obtain test statistics for sequences

Usage:

 aggregate KeywordList do 
   prop
 end
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, prop)

A property combinator to obtain test statistics

Usage:

 collect KeywordList do 
   prop
 end

Example:

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

A property checking an operation and prints when relation is violated. In postconditions, one uses satisfy instead.

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(bindings, list)

Bind a generated value for use by another generator.

Usage:

let pat <- gen1 do
  gen_a
end

let [pat1 <- gen1, pat2 <- gen2] do
  gen_b
end

In the first example, the variables of pat are bound in gen_a. In the second example, the variables of pat1 scope over both gen2 and gen_b.

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

measure(xs, prop)

A property combinator to obtain test statistics for numbers

Usage:

 measure KeywordList do 
   prop
 end

Example:

forall {m, n} <- {int, int} do
  measure m: m, n: n do
      length(Enum.to_list(m .. n)) == abs(n - m) + 1
  end
end
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).

resist(error, cmd)

Wraps an expression that may raise an exception such that if the exception is of the expected error kind, this error is returned as a value, not raised as an exception.

It only catches the expected error, or all errors if none is specified.

Usage:

 resist ArithmeticError, div(4, 0)
 > ArithmeticError

 resist ArgumentError, div(4,0)
 ** (ArithmeticError) bad argument in arithmetic expression

 resist div(4,0)
 > ArithmeticError
satisfy(expr)

A condition modifier for operators to be used in postconditions. Instead of returning false, it returns a tuple representation of failing operator.

Usage:

satisfy t1 == t2
satisfy t1 > t2

In Erlang eq(t1, t2).

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