<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Module proper</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
</head>
<body bgcolor="white">
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<hr>
<h1>Module proper</h1>
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>This is the main PropEr module.
<p>Copyright © 2010-2018 Manolis Papadakis, Eirini Arvaniti, Kostis Sagonas and Andreas Löscher</p>
<p><b>Version:</b> Sep 22 2018 19:52:28</p>
<p><b>Authors:</b> Manolis Papadakis.</p>
<h2><a name="description">Description</a></h2><p>This is the main PropEr module.</p>
<h3><a name="How_to_write_properties">How to write properties</a></h3><p>
The simplest properties that PropEr can test consist of a single boolean
expression (or a statement block that returns a boolean), which is expected
to evaluate to <code>true</code>. Thus, the test <code>true</code> always succeeds, while the test
<code>false</code> always fails (the failure of a property may also be signified by
throwing an exception, error or exit. More complex (and useful) properties
can be written by wrapping such a boolean expression with one or more of the
following wrappers:</p>
<dl>
<dt><code>?FORALL(<Xs>, <Xs_type>, <Prop>)</code></dt>
<dd>The <code><Xs></code> field can either be a single variable, a tuple of variables
or a list of variables. The <code><Xs_type></code> field must then be a single type,
a tuple of types of the same length as the tuple of variables or a list
of types of the same length as the list of variables, respectively.
Tuples and lists can be combined in any way, as long as <code><Xs></code> and
<code><Xs_type></code> are compatible. Both PropEr-provided types, as listed in the
<a href="proper_types.html"><code>proper_types</code></a> module, and types declared in Erlang's built-in
typesystem (we will refer to such types in as <em>native types</em>) may
be used in the <code><Xs_type></code> field. The use of native types in <code>?FORALL</code>s is
subject to some limitations, as described in the documentation for the
<a href="proper_typeserver.html"><code>proper_typeserver</code></a> module. All the variables inside <code><Xs></code> can
(and should) be present as free variables inside the wrapped property
<code><Prop></code>. When a <code>?FORALL</code> wrapper is encountered, a random instance of
<code><Xs_type></code> is produced and each variable in <code><Xs></code> is replaced inside
<code><Prop></code> by its corresponding instance.</dd>
<dt><code>?FORALL_TARGETED(<Xs>, <Xs_type>, <Prop>)</code></dt>
<dd>This is the targeted version of the <code>?FORALL</code> macro that uses the
targeted PBT component of PropEr.</dd>
<dt><code>?IMPLIES(<Precondition>, <Prop>)</code></dt>
<dd>This wrapper only makes sense when in the scope of at least one
<code>?FORALL</code>. The <code><Precondition></code> field must be a boolean expression or a
statement block that returns a boolean. If the precondition evaluates to
<code>false</code> for the variable instances produced in the enclosing <code>?FORALL</code>
wrappers, the test case is rejected (it doesn't count as a failing test
case), and PropEr starts over with a new random test case. Also, in
verbose mode, an <code>x</code> is printed on screen.</dd>
<dt><code>?WHENFAIL(<Action>, <Prop>)</code></dt>
<dd>The <code><Action></code> 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, <code><Action></code> will be executed. Note that the output
of such actions is not affected by the verbosity setting of the main
application.</dd>
<dt><code>?EXISTS(<Xs>, <Xs_type>, <Prop>)</code></dt>
<dd> The <code>?EXISTS</code> macro uses the targeted PBT component of PropEr to try
to find one instance of <code><Xs></code> that makes the <code><Prop></code> true. If such a <code><Xs></code>
is found the property passes. Note that there is no counterexample if no
such <code><Xs></code> could be found.</dd>
<dt><code>?NOT_EXISTS(<Xs>, <Xs_type>, <Prop>)</code></dt>
<dd> The <code>?NOT_EXISTS</code> macro is similar to the <code>?EXISTS</code> macro with the
difference that if an <code><Xs></code> is found that makes <code><Prop></code> true, the
property fails and this <code><Xs></code> is a counterexample to the property.</dd>
<dt><code>?TRAPEXIT(<Prop>)</code></dt>
<dd>If the code inside <code><Prop></code> 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. <code>?TRAPEXIT</code> cannot contain any more
wrappers.</dd>
<dt><code>?TIMEOUT(<Time_limit>, <Prop>)</code></dt>
<dd>Signifies that <code><Prop></code> should be considered failing if it takes more
than <code><Time_limit></code> milliseconds to return. The purpose of this wrapper is
to test code that may hang if something goes wrong. <code>?TIMEOUT</code> cannot
contain any more wrappers.</dd>
<dt><code>?SETUP(<Fun>, <Prop>)</code></dt>
<dd>Adds a setup <code><Fun></code>ction 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 <code>ok</code>, that will be called after the last test.
It is possible to use multiple <code>?SETUP</code> macros on the same property.</dd>
<dt><code>conjunction(<SubProps>)</code></dt>
<dd>See the documentation for <a href="#conjunction-1"><code>conjunction/1</code></a>.</dd>
<dt><code>equals(<A>, <B>)</code></dt>
<dd>See the documentation for <a href="#equals-2"><code>equals/2</code></a>.</dd>
</dl>
<p>There are also multiple wrappers that can be used to collect statistics on
the distribution of test data:</p>
<ul>
<li><a href="#collect-2"><code>collect/2</code></a></li>
<li><a href="#collect-3"><code>collect/3</code></a></li>
<li><a href="#aggregate-2"><code>aggregate/2</code></a></li>
<li><a href="#aggregate-3"><code>aggregate/3</code></a></li>
<li><a href="#classify-3"><code>classify/3</code></a></li>
<li><a href="#measure-3"><code>measure/3</code></a></li>
</ul>
<p><span id="external-wrappers"></span>
A property may also be wrapped with one or more of the following outer-level
wrappers, which control the behaviour of the testing subsystem. If an
outer-level wrapper appears more than once in a property, the innermost
instance takes precedence.</p>
<ul>
<li><a href="#numtests-2"><code>numtests/2</code></a></li>
<li><a href="#fails-2"><code>fails/2</code></a></li>
<li><a href="#on_output-2"><code>on_output/2</code></a></li>
</ul>
<p>For some actual usage examples, see the code in the examples directory, or
check out PropEr's site. The testing modules in the tests directory may also
be of interest.</p>
<h3><a name="Program_behaviour">Program behaviour</a></h3><p>
When running in verbose mode (this is the default), each sucessful test
prints a '.' on screen. If a test fails, a '!' is printed, along with the
failing test case (the instances of the types in every <code>?FORALL</code>) and the
cause of the failure, if it was not simply the falsification of the
property.
Then, unless the test was expected to fail, PropEr attempts to produce a
minimal test case that fails the property in the same way. This process is
called <em>shrinking</em>. During shrinking, a '.' is printed for each
successful simplification of the failing test case. When PropEr reaches its
shrinking limit or realizes that the instance cannot be shrunk further while
still failing the test, it prints the minimal failing test case and failure
reason and exits.</p>
<p>The return value of PropEr can be one of the following:</p>
<ul>
<li><code>true</code>: The property held for all valid produced inputs.</li>
<li><code>false</code>: The property failed for some input.</li>
<li><code>{error, <Type_of_error>}</code>: An error occured; see the <a href="#Errors">Errors</a>
section for more information.</li>
</ul>
<p>To test all properties exported from a module (a property is a 0-arity
function whose name begins with <code>prop_</code>), you can use <a href="#module-1"><code>module/1</code></a> or
<a href="#module-2"><code>module/2</code></a>. This returns a list of all failing properties, represented
by MFAs. Testing progress is also printed on screen (unless quiet mode is
active). The provided options are passed on to each property, except for
<code>long_result</code>, which controls the return value format of the <code>module</code>
function itself.</p>
<h3><a name="Counterexamples">Counterexamples</a></h3><p>
A counterexample for a property is represented as a list of terms; each such
term corresponds to the type in a <code>?FORALL</code>. The instances are provided in
the same order as the <code>?FORALL</code> wrappers in the property, i.e. the instance
at the head of the list corresponds to the outermost <code>?FORALL</code> etc.
Instances generated inside a failing sub-property of a conjunction are
marked with the sub-property's tag.</p>
<p>The last (simplest) counterexample produced by PropEr during a (failing) run
can be retrieved after testing has finished, by running
<a href="#counterexample-0"><code>counterexample/0</code></a>. When testing a whole module, run
<a href="#counterexamples-0"><code>counterexamples/0</code></a> to get a counterexample for each failing property,
as a list of <code>{mfa(),</code><code><a href="#type-counterexample">counterexample()</a></code><code>}</code> tuples. To enable this
functionality, some information has to remain in the process dictionary
even after PropEr has returned. If, for some reason, you want to completely
clean up the process dictionary of PropEr-produced entries, run
<a href="#clean_garbage-0"><code>clean_garbage/0</code></a>.</p>
<p>Counterexamples can also be retrieved by running PropEr in long-result mode,
where counterexamples are returned as part of the return value.
Specifically, when testing a single property under long-result mode
(activated by supplying the option <code>long_result</code>, or by calling
<a href="#counterexample-1"><code>counterexample/1</code></a> or <a href="#counterexample-2"><code>counterexample/2</code></a> instead of
<a href="#quickcheck-1"><code>quickcheck/1</code></a> and <a href="#quickcheck-2"><code>quickcheck/2</code></a> respectively), PropEr will
return a counterexample in case of failure (instead of simply returning
<code>false</code>). When testing a whole module under long-result mode (activated by
supplying the option <code>long_result</code> to <a href="#module-2"><code>module/2</code></a>), PropEr will return
a list of <code>{mfa(),</code><code><a href="#type-counterexample">counterexample()</a></code><code>}</code> tuples, one for each failing
property.</p>
<p>You can re-check a specific counterexample against the property that it
previously falsified by running <a href="#check-2"><code>check/2</code></a> or <a href="#check-3"><code>check/3</code></a>. This
will return one of the following (both in short- and long-result mode):</p>
<ul>
<li><code>true</code>: The property now holds for this test case.</li>
<li><code>false</code>: The test case still fails (although not necessarily for the
same reason as before).</li>
<li><code>{error, <Type_of_error>}</code>: An error occured - see the <a href="#Errors">Errors</a>
section for more information.</li>
</ul>
<p>Proper will not attempt to shrink the input in case it still fails the
property. Unless silent mode is active, PropEr will also print a message on
screen, describing the result of the re-checking. Note that PropEr can do
very little to verify that the counterexample actually corresponds to the
property that it is tested against.</p>
<h3><a name="Options">Options</a></h3><p>
Options can be provided as an extra argument to most testing functions (such
as <a href="#quickcheck-1"><code>quickcheck/1</code></a>). A single option can be written stand-alone, or
multiple options can be provided in a list. When two settings conflict, the
one that comes first in the list takes precedence. Settings given inside
external wrappers to a property (see the <a href="#How_to_write_properties">How to write properties</a>
section) override any conflicting settings provided as options.</p>
<p>The available options are:</p>
<dl>
<dt><code>quiet</code></dt>
<dd>Enables quiet mode - no output is printed on screen while PropEr is
running.</dd>
<dt><code>verbose</code></dt>
<dd>Enables verbose mode - this is the default mode of operation.</dd>
<dt><code>{to_file, <IO_device>}</code></dt>
<dd>Redirects all of PropEr's output to <code><IO_device></code>, which should be an
IO device associated with a file opened for writing.</dd>
<dt><code>{on_output, <Output_function>}</code></dt>
<dd>PropEr will use the supplied function for all output printing. This
function should accept two arguments in the style of <code>io:format/2</code>.<br>
CAUTION: The above output control options are incompatible with each
other.</dd>
<dt><code>long_result</code></dt>
<dd>Enables long-result mode (see the <a href="#Counterexamples">Counterexamples</a> section
for details).</dd>
<dt><code>{numtests, <Positive_number>}</code> or simply <code><Positive_number></code></dt>
<dd>This is equivalent to the <a href="#numtests-1"><code>numtests/1</code></a> property wrapper. Any
<a href="#numtests-1"><code>numtests/1</code></a> wrappers in the actual property will overwrite this
setting.</dd>
<dt><code>{start_size, <Size>}</code></dt>
<dd>Specifies the initial value of the <code>size</code> parameter (default is 1), see
the documentation of the <a href="proper_types.html"><code>proper_types</code></a> module for details.</dd>
<dt><code>{max_size, <Size>}</code></dt>
<dd>Specifies the maximum value of the <code>size</code> parameter (default is 42), see
the documentation of the <a href="proper_types.html"><code>proper_types</code></a> module for details.</dd>
<dt><code>{max_shrinks, <Non_negative_number>}</code></dt>
<dd>Specifies the maximum number of times a failing test case should be
shrunk before returning. Note that the shrinking may stop before so many
shrinks are achieved if the shrinking subsystem deduces that it cannot
shrink the failing test case further. Default is 500.</dd>
<dt><code>noshrink</code></dt>
<dd>Instructs PropEr to not attempt to shrink any failing test cases.</dd>
<dt><code>{constraint_tries, <Positive_number>}</code></dt>
<dd>Specifies the maximum number of tries before the generator subsystem
gives up on producing an instance that satisfies a <code>?SUCHTHAT</code>
constraint. Default is 50.</dd>
<dt><code>fails</code></dt>
<dd>This is equivalent to the <a href="#fails-1"><code>fails/1</code></a> property wrapper.</dd>
<dt><code>{spec_timeout, infinity | <Non_negative_number>}</code></dt>
<dd>When testing a spec, PropEr will consider an input to be failing if the
function under test takes more than the specified amount of milliseconds
to return for that input.</dd>
<dt><code>any_to_integer</code></dt>
<dd>All generated instances of the type <a href="proper_types.html#any-0"><code>proper_types:any/0</code></a> will be
integers. This is provided as a means to speed up the testing of specs,
where <code>any()</code> is a commonly used type (see the <a href="#Spec_testing">Spec testing</a>
section for details).</dd>
<dt><code>{skip_mfas, [<MFA>]}</code></dt>
<dd> When checking a module's specs, PropEr will not test the
specified MFAs. Default is [].</dd>
<dt><code>{false_positive_mfas, fun((mfa(),[Arg::term()],{fail, Result::term()} | {error | exit | throw, Reason::term()}) -> boolean()) | undefined}</code></dt>
<dd> When checking a module's spec(s), PropEr will treat a
counterexample as a false positive if the user supplied function
returns true. Otherwise, PropEr will treat the counterexample as
it normally does. The inputs to the user supplied function are
the MFA, the arguments passed to the MFA, and the result returned
from the MFA or an exception with it's reason. If needed, the
user supplied function can call erlang:get_stacktrace/0. Default
is undefined.</dd>
<dt><code>nocolors</code></dt>
<dd>Don't use term colors in output.</dd>
</dl>
<h3><a name="Spec_testing">Spec testing</a></h3><p>
You can test the accuracy of an exported function's spec by running
<a href="#check_spec-1"><code>check_spec/1</code></a> or <a href="#check_spec-2"><code>check_spec/2</code></a>.
Under this mode of operation, PropEr will call the provided function with
increasingly complex valid inputs (according to its spec) and test that no
unexpected value is returned. If an input is found that violates the spec,
it will be saved as a counterexample and PropEr will attempt to shrink it.</p>
<p>You can test all exported functions of a module against their spec by
running <a href="#check_specs-1"><code>check_specs/1</code></a> or <a href="#check_specs-2"><code>check_specs/2</code></a>.</p>
<p>The use of <code>check_spec</code> is subject to the following usage rules:</p>
<ul>
<li>Currently, PropEr can't test functions whose range contains a type
that exhibits a certain kind of self-reference: it is (directly or
indirectly) self-recursive and at least one recursion path contains only
unions and type references. E.g. these types are acceptable:
<pre> -type a(T) :: T | {'bar',a(T)}.
-type b() :: 42 | [c()].
-type c() :: {'baz',b()}.</pre>
while these are not:
<pre> -type a() :: 'foo' | b().
-type b() :: c() | [integer()].
-type c() :: 'bar' | a().
-type d(T) :: T | d({'baz',T}).</pre> </li>
<li>Throwing any exception or raising an <code>error:badarg</code> is considered
normal behaviour. Currently, users cannot fine-tune this setting.</li>
<li>Only the first clause of the function's spec is considered.</li>
<li>The only spec constraints we accept are is_subtype' constraints whose
first argument is a simple, non-'_' variable. It is not checked whether or
not these variables actually appear in the spec. The second argument of an
<code>is_subtype</code> constraint cannot contain any non-'_' variables. Multiple
constraints for the same variable are not supported.</li>
</ul>
<h3><a name="Errors">Errors</a></h3><p>
The following errors may be encountered during testing. The term provided
for each error is the error type returned by proper:quickcheck in case such
an error occurs. Normaly, a message is also printed on screen describing
the error.</p>
<dl>
<dt><code>arity_limit</code></dt>
<dd>The random instance generation subsystem has failed to produce
a function of the desired arity. Please recompile PropEr with a suitable
value for <code>?MAX_ARITY</code> (defined in <code>proper_internal.hrl</code>). This error
should only be encountered during normal operation.</dd>
<dt><code>cant_generate</code></dt>
<dd>The random instance generation subsystem has failed to
produce an instance that satisfies some <code>?SUCHTHAT</code> constraint. You
should either increase the <code>constraint_tries</code> limit, loosen the failing
constraint, or make it non-strict. This error should only be encountered
during normal operation.</dd>
<dt><code>cant_satisfy</code></dt>
<dd>All the tests were rejected because no produced test case
would pass all <code>?IMPLIES</code> checks. You should loosen the failing <code>?IMPLIES</code>
constraint(s). This error should only be encountered during normal
operation.</dd>
<dt><code>non_boolean_result</code></dt>
<dd>The property code returned a non-boolean result. Please
fix your property.</dd>
<dt><code>rejected</code></dt>
<dd>Only encountered during re-checking, the counterexample does not
match the property, since the counterexample doesn't pass an <code>?IMPLIES</code>
check.</dd>
<dt><code>too_many_instances</code></dt>
<dd>Only encountered during re-checking, the counterexample
does not match the property, since the counterexample contains more
instances than there are <code>?FORALL</code>s in the property.</dd>
<dt><code>type_mismatch</code></dt>
<dd>The variables' and types' structures inside a <code>?FORALL</code> don't
match. Please check your properties.</dd>
<dt><code>{typeserver, <SubError>}</code></dt>
<dd>The typeserver encountered an error. The <code><SubError></code> field contains
specific information regarding the error.</dd>
<dt><code>{unexpected, <Result>}</code></dt>
<dd>A test returned an unexpected result during normal operation. If you
ever get this error, it means that you have found a bug in PropEr
- please send an error report to the maintainers and remember to include
both the failing test case and the output of the program, if possible.
</dd>
<dt><code>{unrecognized_option, <Option>}</code></dt>
<dd><code><Option></code> is not an option that PropEr understands.</dd>
</dl>
<h2><a name="types">Data Types</a></h2>
<h3 class="typedecl"><a name="type-clean_input">clean_input()</a></h3>
<p><pre>clean_input() = <a href="proper_gen.html#type-instance">proper_gen:instance()</a> | <a href="#type-sub_counterexamples">sub_counterexamples()</a></pre></p>
<h3 class="typedecl"><a name="type-counterexample">counterexample()</a></h3>
<p><pre>counterexample() = [<a href="#type-clean_input">clean_input()</a>]</pre></p>
<h3 class="typedecl"><a name="type-error">error()</a></h3>
<p><pre>error() = {error, <a href="#type-error_reason">error_reason()</a>}</pre></p>
<h3 class="typedecl"><a name="type-error_reason">error_reason()</a></h3>
<p><pre>error_reason() =
arity_limit |
cant_generate |
cant_satisfy |
non_boolean_result |
rejected |
too_many_instances |
type_mismatch |
wrong_type |
{typeserver, term()} |
{unexpected, any()} |
{unrecognized_option, term()}</pre></p>
<h3 class="typedecl"><a name="type-false_positive_mfas">false_positive_mfas()</a></h3>
<p><pre>false_positive_mfas() =
fun((mfa(),
Args :: [term()],
{fail, Result :: term()} |
{error | exit | throw, Reason :: term()}) ->
boolean()) |
undefined</pre></p>
<p> </p>
<h3 class="typedecl"><a name="type-long_module_result">long_module_result()</a></h3>
<p><pre>long_module_result() = [{mfa(), <a href="#type-counterexample">counterexample()</a>}] | <a href="#type-error">error()</a></pre></p>
<h3 class="typedecl"><a name="type-long_result">long_result()</a></h3>
<p><pre>long_result() = true | <a href="#type-counterexample">counterexample()</a> | <a href="#type-error">error()</a></pre></p>
<h3 class="typedecl"><a name="type-mod_name">mod_name()</a></h3>
<p><pre>mod_name() = atom()</pre></p>
<h3 class="typedecl"><a name="type-module_result">module_result()</a></h3>
<p><pre>module_result() = <a href="#type-long_module_result">long_module_result()</a> | <a href="#type-short_module_result">short_module_result()</a></pre></p>
<h3 class="typedecl"><a name="type-outer_test">outer_test()</a></h3>
<p><b>abstract datatype</b>: <tt>outer_test()</tt></p>
<p>A testable property that has optionally been wrapped with
one or more <a href="#external-wrappers">external wrappers</a>.</p>
<h3 class="typedecl"><a name="type-output_fun">output_fun()</a></h3>
<p><pre>output_fun() = fun((string(), [term()]) -> ok)</pre></p>
<p> A fun to be used by PropEr for output printing. Such a fun should follow the
conventions of <code>io:format/2</code>.</p>
<h3 class="typedecl"><a name="type-result">result()</a></h3>
<p><pre>result() = <a href="#type-long_result">long_result()</a> | <a href="#type-short_result">short_result()</a></pre></p>
<h3 class="typedecl"><a name="type-sample">sample()</a></h3>
<p><pre>sample() = [term()]</pre></p>
<h3 class="typedecl"><a name="type-setup_opts">setup_opts()</a></h3>
<p><pre>setup_opts() = term()</pre></p>
<p> </p>
<h3 class="typedecl"><a name="type-short_module_result">short_module_result()</a></h3>
<p><pre>short_module_result() = [mfa()] | <a href="#type-error">error()</a></pre></p>
<h3 class="typedecl"><a name="type-short_result">short_result()</a></h3>
<p><pre>short_result() = boolean() | <a href="#type-error">error()</a></pre></p>
<h3 class="typedecl"><a name="type-size">size()</a></h3>
<p><pre>size() = non_neg_integer()</pre></p>
<h3 class="typedecl"><a name="type-stats_printer">stats_printer()</a></h3>
<p><pre>stats_printer() =
fun((<a href="#type-sample">sample()</a>) -> ok) | fun((<a href="#type-sample">sample()</a>, <a href="#type-output_fun">output_fun()</a>) -> ok)</pre></p>
<p> A stats-printing function that can be passed to some of the statistics
collection functions, to be used instead of the predefined stats-printer.
Such a function will be called at the end of testing (in case no test fails)
with a sorted list of collected terms. A commonly used stats-printer is
<code>with_title/1</code>.</p>
<h3 class="typedecl"><a name="type-sub_counterexamples">sub_counterexamples()</a></h3>
<p><pre>sub_counterexamples() = [{<a href="#type-tag">tag()</a>, <a href="#type-counterexample">counterexample()</a>}]</pre></p>
<h3 class="typedecl"><a name="type-tag">tag()</a></h3>
<p><pre>tag() = atom()</pre></p>
<h3 class="typedecl"><a name="type-test">test()</a></h3>
<p><b>abstract datatype</b>: <tt>test()</tt></p>
<p>A testable property that has not been wrapped with an
<a href="#external-wrappers">external wrapper</a>.</p>
<h3 class="typedecl"><a name="type-title">title()</a></h3>
<p><pre>title() = atom() | string()</pre></p>
<h3 class="typedecl"><a name="type-user_opt">user_opt()</a></h3>
<p><pre>user_opt() =
quiet |
verbose |
{to_file, <a href="io.html#type-device">io:device()</a>} |
{on_output, <a href="#type-output_fun">output_fun()</a>} |
long_result |
{numtests, pos_integer()} |
{search_steps, pos_integer()} |
{search_strategy, atom()} |
pos_integer() |
{start_size, <a href="#type-size">size()</a>} |
{max_size, <a href="#type-size">size()</a>} |
{max_shrinks, non_neg_integer()} |
noshrink |
{constraint_tries, pos_integer()} |
fails |
any_to_integer |
{spec_timeout, timeout()} |
{skip_mfas, [mfa()]} |
{false_positive_mfas, <a href="#type-false_positive_mfas">false_positive_mfas()</a>} |
nocolors</pre></p>
<h3 class="typedecl"><a name="type-user_opts">user_opts()</a></h3>
<p><pre>user_opts() = [<a href="#type-user_opt">user_opt()</a>] | <a href="#type-user_opt">user_opt()</a></pre></p>
<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#aggregate-2">aggregate/2</a></td><td>Same as <a href="#collect-2"><code>collect/2</code></a>, but accepts a list of categories under which
to classify the produced test case.</td></tr>
<tr><td valign="top"><a href="#aggregate-3">aggregate/3</a></td><td>Same as <a href="#collect-3"><code>collect/3</code></a>, but accepts a list of categories under which
to classify the produced test case.</td></tr>
<tr><td valign="top"><a href="#check-2">check/2</a></td><td>Re-checks a specific counterexample <code>CExm</code> against the property
<code>OuterTest</code> that it previously falsified.</td></tr>
<tr><td valign="top"><a href="#check-3">check/3</a></td><td>Same as <a href="#check-2"><code>check/2</code></a>, but also accepts a list of options.</td></tr>
<tr><td valign="top"><a href="#check_spec-1">check_spec/1</a></td><td>Tests the accuracy of an exported function's spec.</td></tr>
<tr><td valign="top"><a href="#check_spec-2">check_spec/2</a></td><td>Same as <a href="#check_spec-1"><code>check_spec/1</code></a>, but also accepts a list of options.</td></tr>
<tr><td valign="top"><a href="#check_specs-1">check_specs/1</a></td><td>Tests all exported, <code>-spec</code>ed functions of a module <code>Mod</code> against their
spec.</td></tr>
<tr><td valign="top"><a href="#check_specs-2">check_specs/2</a></td><td>Same as <a href="#check_specs-1"><code>check_specs/1</code></a>, but also accepts a list of options.</td></tr>
<tr><td valign="top"><a href="#classify-3">classify/3</a></td><td>Same as <a href="#collect-2"><code>collect/2</code></a>, but can accept both a single category and a
list of categories.</td></tr>
<tr><td valign="top"><a href="#clean_garbage-0">clean_garbage/0</a></td><td>Cleans up the process dictionary of all PropEr-produced entries.</td></tr>
<tr><td valign="top"><a href="#collect-2">collect/2</a></td><td>Specifies that test cases produced by this property should be
categorized under the term <code>Category</code>.</td></tr>
<tr><td valign="top"><a href="#collect-3">collect/3</a></td><td>Same as <a href="#collect-2"><code>collect/2</code></a>, but also accepts a fun <code>Printer</code> to be used
as the stats printer.</td></tr>
<tr><td valign="top"><a href="#conjunction-1">conjunction/1</a></td><td>Returns a property that is true only if all of the sub-properties
<code>SubProps</code> are true.</td></tr>
<tr><td valign="top"><a href="#counterexample-0">counterexample/0</a></td><td>Retrieves the last (simplest) counterexample produced by PropEr during
the most recent testing run.</td></tr>
<tr><td valign="top"><a href="#counterexample-1">counterexample/1</a></td><td>Equivalent to <a href="#quickcheck-2"><tt>quickcheck(OuterTest, [long_result])</tt></a>.
</td></tr>
<tr><td valign="top"><a href="#counterexample-2">counterexample/2</a></td><td>Same as <a href="#counterexample-1"><code>counterexample/1</code></a>, but also accepts a list of options.</td></tr>
<tr><td valign="top"><a href="#counterexamples-0">counterexamples/0</a></td><td>Returns a counterexample for each failing property of the most recent
module testing run.</td></tr>
<tr><td valign="top"><a href="#equals-2">equals/2</a></td><td>A custom property that evaluates to <code>true</code> only if <code>A =:= B</code>, else
evaluates to <code>false</code> and prints "<code>A =/= B</code>" on the screen.</td></tr>
<tr><td valign="top"><a href="#fails-1">fails/1</a></td><td>Specifies that we expect the property <code>Test</code> to fail for some input.</td></tr>
<tr><td valign="top"><a href="#measure-3">measure/3</a></td><td>A function that collects numeric statistics on the produced instances.</td></tr>
<tr><td valign="top"><a href="#module-1">module/1</a></td><td>Tests all properties (i.e., all 0-arity functions whose name begins with
<code>prop_</code>) exported from module <code>Mod</code>.</td></tr>
<tr><td valign="top"><a href="#module-2">module/2</a></td><td>Same as <a href="#module-1"><code>module/1</code></a>, but also accepts a list of options.</td></tr>
<tr><td valign="top"><a href="#numtests-2">numtests/2</a></td><td>Specifies the number <code>N</code> of tests to run when testing the property
<code>Test</code>.</td></tr>
<tr><td valign="top"><a href="#on_output-2">on_output/2</a></td><td>Specifies an output function <code>Print</code> to be used by PropEr for all output
printing during the testing of property <code>Test</code>.</td></tr>
<tr><td valign="top"><a href="#quickcheck-1">quickcheck/1</a></td><td>Runs PropEr on the property <code>OuterTest</code>.</td></tr>
<tr><td valign="top"><a href="#quickcheck-2">quickcheck/2</a></td><td>Same as <a href="#quickcheck-1"><code>quickcheck/1</code></a>, but also accepts a list of options.</td></tr>
<tr><td valign="top"><a href="#with_title-1">with_title/1</a></td><td>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 <code>Title</code> above the statistics.</td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
<h3 class="function"><a name="aggregate-2">aggregate/2</a></h3>
<div class="spec">
<p><pre>aggregate(Sample :: <a href="#type-sample">sample()</a>, Test :: <a href="#type-test">test()</a>) -> <a href="#type-test">test()</a></pre></p>
</div><p>Same as <a href="#collect-2"><code>collect/2</code></a>, but accepts a list of categories under which
to classify the produced test case.</p>
<h3 class="function"><a name="aggregate-3">aggregate/3</a></h3>
<div class="spec">
<p><pre>aggregate(Printer :: <a href="#type-stats_printer">stats_printer()</a>,
Sample :: <a href="#type-sample">sample()</a>,
Test :: <a href="#type-test">test()</a>) ->
<a href="#type-test">test()</a></pre></p>
</div><p>Same as <a href="#collect-3"><code>collect/3</code></a>, but accepts a list of categories under which
to classify the produced test case.</p>
<h3 class="function"><a name="check-2">check/2</a></h3>
<div class="spec">
<p><pre>check(OuterTest :: <a href="#type-outer_test">outer_test()</a>, CExm :: <a href="#type-counterexample">counterexample()</a>) ->
<a href="#type-short_result">short_result()</a></pre></p>
</div><p>Re-checks a specific counterexample <code>CExm</code> against the property
<code>OuterTest</code> that it previously falsified.</p>
<h3 class="function"><a name="check-3">check/3</a></h3>
<div class="spec">
<p><pre>check(OuterTest :: <a href="#type-outer_test">outer_test()</a>,
CExm :: <a href="#type-counterexample">counterexample()</a>,
UserOpts :: <a href="#type-user_opts">user_opts()</a>) ->
<a href="#type-short_result">short_result()</a></pre></p>
</div><p>Same as <a href="#check-2"><code>check/2</code></a>, but also accepts a list of options.</p>
<h3 class="function"><a name="check_spec-1">check_spec/1</a></h3>
<div class="spec">
<p><pre>check_spec(MFA :: mfa()) -> <a href="#type-result">result()</a></pre></p>
</div><p>Tests the accuracy of an exported function's spec.</p>
<h3 class="function"><a name="check_spec-2">check_spec/2</a></h3>
<div class="spec">
<p><pre>check_spec(MFA :: mfa(), UserOpts :: <a href="#type-user_opts">user_opts()</a>) -> <a href="#type-result">result()</a></pre></p>
</div><p>Same as <a href="#check_spec-1"><code>check_spec/1</code></a>, but also accepts a list of options.</p>
<h3 class="function"><a name="check_specs-1">check_specs/1</a></h3>
<div class="spec">
<p><pre>check_specs(Mod :: <a href="#type-mod_name">mod_name()</a>) -> <a href="#type-module_result">module_result()</a></pre></p>
</div><p>Tests all exported, <code>-spec</code>ed functions of a module <code>Mod</code> against their
spec.</p>
<h3 class="function"><a name="check_specs-2">check_specs/2</a></h3>
<div class="spec">
<p><pre>check_specs(Mod :: <a href="#type-mod_name">mod_name()</a>, UserOpts :: <a href="#type-user_opts">user_opts()</a>) ->
<a href="#type-module_result">module_result()</a></pre></p>
</div><p>Same as <a href="#check_specs-1"><code>check_specs/1</code></a>, but also accepts a list of options.</p>
<h3 class="function"><a name="classify-3">classify/3</a></h3>
<div class="spec">
<p><pre>classify(Count :: boolean(),
TermOrSample :: term() | <a href="#type-sample">sample()</a>,
Test :: <a href="#type-test">test()</a>) ->
<a href="#type-test">test()</a></pre></p>
</div><p>Same as <a href="#collect-2"><code>collect/2</code></a>, but can accept both a single category and a
list of categories. <code>Count</code> is a boolean flag: when <code>false</code>, the particular
test case will not be counted.</p>
<h3 class="function"><a name="clean_garbage-0">clean_garbage/0</a></h3>
<div class="spec">
<p><pre>clean_garbage() -> ok</pre></p>
</div><p>Cleans up the process dictionary of all PropEr-produced entries.</p>
<h3 class="function"><a name="collect-2">collect/2</a></h3>
<div class="spec">
<p><pre>collect(Category :: term(), Test :: <a href="#type-test">test()</a>) -> <a href="#type-test">test()</a></pre></p>
</div><p>Specifies that test cases produced by this property should be
categorized under the term <code>Category</code>. 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 <code>collect</code>
wrappers are allowed in a single property, in which case the percentages for
each <code>collect</code> wrapper are printed separately.</p>
<h3 class="function"><a name="collect-3">collect/3</a></h3>
<div class="spec">
<p><pre>collect(Printer :: <a href="#type-stats_printer">stats_printer()</a>,
Category :: term(),
Test :: <a href="#type-test">test()</a>) ->
<a href="#type-test">test()</a></pre></p>
</div><p>Same as <a href="#collect-2"><code>collect/2</code></a>, but also accepts a fun <code>Printer</code> to be used
as the stats printer.</p>
<h3 class="function"><a name="conjunction-1">conjunction/1</a></h3>
<div class="spec">
<p><pre>conjunction(SubProps :: [{<a href="#type-tag">tag()</a>, <a href="#type-test">test()</a>}]) -> <a href="#type-test">test()</a></pre></p>
</div><p>Returns a property that is true only if all of the sub-properties
<code>SubProps</code> 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.</p>
<h3 class="function"><a name="counterexample-0">counterexample/0</a></h3>
<div class="spec">
<p><pre>counterexample() -> <a href="#type-counterexample">counterexample()</a> | undefined</pre></p>
</div><p>Retrieves the last (simplest) counterexample produced by PropEr during
the most recent testing run.</p>
<h3 class="function"><a name="counterexample-1">counterexample/1</a></h3>
<div class="spec">
<p><pre>counterexample(OuterTest :: <a href="#type-outer_test">outer_test()</a>) -> <a href="#type-long_result">long_result()</a></pre></p>
</div><p>Equivalent to <a href="#quickcheck-2"><tt>quickcheck(OuterTest, [long_result])</tt></a>.</p>
<h3 class="function"><a name="counterexample-2">counterexample/2</a></h3>
<div class="spec">
<p><pre>counterexample(OuterTest :: <a href="#type-outer_test">outer_test()</a>, UserOpts :: <a href="#type-user_opts">user_opts()</a>) ->
<a href="#type-long_result">long_result()</a></pre></p>
</div><p>Same as <a href="#counterexample-1"><code>counterexample/1</code></a>, but also accepts a list of options.</p>
<h3 class="function"><a name="counterexamples-0">counterexamples/0</a></h3>
<div class="spec">
<p><pre>counterexamples() -> [{mfa(), <a href="#type-counterexample">counterexample()</a>}] | undefined</pre></p>
</div><p>Returns a counterexample for each failing property of the most recent
module testing run.</p>
<h3 class="function"><a name="equals-2">equals/2</a></h3>
<div class="spec">
<p><pre>equals(A :: term(), B :: term()) -> <a href="#type-test">test()</a></pre></p>
</div><p>A custom property that evaluates to <code>true</code> only if <code>A =:= B</code>, else
evaluates to <code>false</code> and prints "<code>A =/= B</code>" on the screen.</p>
<h3 class="function"><a name="fails-1">fails/1</a></h3>
<div class="spec">
<p><pre>fails(Test :: <a href="#type-outer_test">outer_test()</a>) -> <a href="#type-outer_test">outer_test()</a></pre></p>
</div><p>Specifies that we expect the property <code>Test</code> to fail for some input. The
property will be considered failing if it passes all the tests.</p>
<h3 class="function"><a name="measure-3">measure/3</a></h3>
<div class="spec">
<p><pre>measure(Title :: <a href="#type-title">title()</a>,
Sample :: number() | [number()],
Test :: <a href="#type-test">test()</a>) ->
<a href="#type-test">test()</a></pre></p>
</div><p>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 <code>Title</code>, which should be an atom or string.</p>
<h3 class="function"><a name="module-1">module/1</a></h3>
<div class="spec">
<p><pre>module(Mod :: <a href="#type-mod_name">mod_name()</a>) -> <a href="#type-module_result">module_result()</a></pre></p>
</div><p>Tests all properties (i.e., all 0-arity functions whose name begins with
<code>prop_</code>) exported from module <code>Mod</code>.</p>
<h3 class="function"><a name="module-2">module/2</a></h3>
<div class="spec">
<p><pre>module(Mod :: <a href="#type-mod_name">mod_name()</a>, UserOpts :: <a href="#type-user_opts">user_opts()</a>) ->
<a href="#type-module_result">module_result()</a></pre></p>
</div><p>Same as <a href="#module-1"><code>module/1</code></a>, but also accepts a list of options.</p>
<h3 class="function"><a name="numtests-2">numtests/2</a></h3>
<div class="spec">
<p><pre>numtests(N :: pos_integer(), Test :: <a href="#type-outer_test">outer_test()</a>) -> <a href="#type-outer_test">outer_test()</a></pre></p>
</div><p>Specifies the number <code>N</code> of tests to run when testing the property
<code>Test</code>. Default is 100.</p>
<h3 class="function"><a name="on_output-2">on_output/2</a></h3>
<div class="spec">
<p><pre>on_output(Print :: <a href="#type-output_fun">output_fun()</a>, Test :: <a href="#type-outer_test">outer_test()</a>) ->
<a href="#type-outer_test">outer_test()</a></pre></p>
</div><p>Specifies an output function <code>Print</code> to be used by PropEr for all output
printing during the testing of property <code>Test</code>. This wrapper is equivalent to
the <code>on_output</code> option.</p>
<h3 class="function"><a name="quickcheck-1">quickcheck/1</a></h3>
<div class="spec">
<p><pre>quickcheck(OuterTest :: <a href="#type-outer_test">outer_test()</a>) -> <a href="#type-result">result()</a></pre></p>
</div><p>Runs PropEr on the property <code>OuterTest</code>.</p>
<h3 class="function"><a name="quickcheck-2">quickcheck/2</a></h3>
<div class="spec">
<p><pre>quickcheck(OuterTest :: <a href="#type-outer_test">outer_test()</a>, UserOpts :: <a href="#type-user_opts">user_opts()</a>) ->
<a href="#type-result">result()</a></pre></p>
</div><p>Same as <a href="#quickcheck-1"><code>quickcheck/1</code></a>, but also accepts a list of options.</p>
<h3 class="function"><a name="with_title-1">with_title/1</a></h3>
<div class="spec">
<p><pre>with_title(Title :: <a href="#type-title">title()</a>) -> <a href="#type-stats_printer">stats_printer()</a></pre></p>
</div><p>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 <code>Title</code> above the statistics.</p>
<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc</i></p>
</body>
</html>
