Added eqcmini quickcheck library to lib/
This commit is contained in:
Kallfaktorn
parent
8a574db360
commit
73194d7d28
21 changed files with 2075 additions and 0 deletions
2
lib/eqc/doc/edoc-info
Normal file
2
lib/eqc/doc/edoc-info
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
{packages,[]}.
|
||||
{modules,[eqc,eqc_gen,eqc_symbolic]}.
|
||||
385
lib/eqc/doc/eqc.html
Normal file
385
lib/eqc/doc/eqc.html
Normal file
|
|
@ -0,0 +1,385 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Module eqc</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 eqc</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 module defines functions for writing and testing QuickCheck properties.
|
||||
|
||||
<p><b>Version:</b> 1.0.1</p>
|
||||
|
||||
<h2><a name="description">Description</a></h2>This module defines functions for writing and testing QuickCheck properties.
|
||||
Much of the interface is provided via macros (defined in <tt>eqc.hrl</tt>).
|
||||
These are documented below:
|
||||
<h2><tt>?FORALL(X,Gen,Prop)</tt></h2>
|
||||
Property that holds if <tt>Prop</tt> holds for all values <tt>X</tt> that
|
||||
can be generated by <tt>Gen</tt>. For example,
|
||||
<pre>
|
||||
prop_reverse() ->
|
||||
?FORALL(Xs,list(int()),
|
||||
lists:reverse(lists:reverse(Xs)) == Xs).
|
||||
</pre>
|
||||
Generators are defined using the module <a href="eqc_gen.html"><code>eqc_gen</code></a>.
|
||||
<h2><tt>?IMPLIES(Pre,Prop)</tt></h2>
|
||||
Property that holds if <tt>Prop</tt> holds whenever the precondition
|
||||
<tt>Pre</tt> is true. The precondition must be a boolean, but <tt>Prop</tt>
|
||||
can be any QuickCheck property. An implication is tested by discarding test
|
||||
cases which do not satisfy the precondition. This can make testing slow,
|
||||
since many more test cases may need to be generated to find 100 which
|
||||
satisfy the precondition. In the worst case, QuickCheck may not be able
|
||||
to find enough test cases that do satisfy the precondition, in which case
|
||||
the number actually found is reported. Some preconditions may also skew
|
||||
the test data badly--for example, a precondition that a list is sorted
|
||||
skews the test data towards short lists, since random longer lists are
|
||||
extremely unlikely to be sorted just by chance. <tt>?IMPLIES</tt> works
|
||||
well for preconditions which are true with a high probability, but if the
|
||||
precondition is unlikely to hold, then it is better to write a custom
|
||||
generator which generates test cases where the precondition is true.
|
||||
<h2><tt>?WHENFAIL(Action,Prop)</tt></h2><p>
|
||||
Property that is equivalent to <tt>Prop</tt>, but performs <tt>Action</tt>
|
||||
(for its side effects) when <tt>Prop</tt> fails. This can be used to
|
||||
print additional information when a test case fails.</p>
|
||||
|
||||
|
||||
|
||||
|
||||
<h2><a name="types">Data Types</a></h2>
|
||||
|
||||
<h3 class="typedecl"><a name="type-counterexample">counterexample()</a></h3>
|
||||
<p><b>abstract datatype</b>: <tt>counterexample()</tt></p>
|
||||
<p>A counter-example to a QuickCheck property, which can be obtained
|
||||
using <a href="#counterexample-0"><code>counterexample/0</code></a> or <a href="#counterexample-1"><code>counterexample/1</code></a>, and used to repeat a test,
|
||||
or test a different property in the same case. Counterexamples are represented by the values
|
||||
bound by ?FORALL--for the counterexample to make sense independently, it's important that
|
||||
these were generated without side-effects.</p>
|
||||
|
||||
<h3 class="typedecl"><a name="type-print_method">print_method()</a></h3>
|
||||
<p><tt>print_method() = (list(term())) -> any()</tt></p>
|
||||
<p>A function for
|
||||
printing statistics, which is passed a list of samples and is
|
||||
expected to print statistical information about them. Print methods
|
||||
are used by <a href="#collect-3"><code>collect/3</code></a> and <a href="#aggregate-3"><code>aggregate/3</code></a>.</p>
|
||||
|
||||
<h3 class="typedecl"><a name="type-property">property()</a></h3>
|
||||
<p><b>abstract datatype</b>: <tt>property()</tt></p>
|
||||
<p>QuickCheck properties, which can either be boolean
|
||||
expressions, or constructed using the functions in this module.
|
||||
QuickCheck properties are tested using <a href="#quickcheck-1"><code>quickcheck/1</code></a>.</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>A property logically equivalent to <tt>Prop</tt>, but which collects a list of values in
|
||||
each test, and displays the distribution of these values once
|
||||
testing is complete.</td></tr>
|
||||
<tr><td valign="top"><a href="#aggregate-3">aggregate/3</a></td><td>Like <a href="#aggregate-2"><code>aggregate/2</code></a>, but allows the user to specify how
|
||||
the collected values should be printed.</td></tr>
|
||||
<tr><td valign="top"><a href="#backtrace-0">backtrace/0</a></td><td>Displays a stack backtrace from the last exception QuickCheck caught.</td></tr>
|
||||
<tr><td valign="top"><a href="#check-2">check/2</a></td><td>Tests the property in the case given.</td></tr>
|
||||
<tr><td valign="top"><a href="#classify-3">classify/3</a></td><td>Property which is logically equivalent to <tt>Prop</tt>, but also
|
||||
classifies test cases and displays the distribution of test case classes
|
||||
when testing is complete.</td></tr>
|
||||
<tr><td valign="top"><a href="#collect-2">collect/2</a></td><td>Equivalent to <a href="#aggregate-2"><tt>aggregate([S], Prop)</tt></a>.
|
||||
</td></tr>
|
||||
<tr><td valign="top"><a href="#collect-3">collect/3</a></td><td>Equivalent to <a href="#aggregate-3"><tt>aggregate(PrintMethod, [S], Prop)</tt></a>.
|
||||
</td></tr>
|
||||
<tr><td valign="top"><a href="#counterexample-0">counterexample/0</a></td><td>Returns the last counter-example found.</td></tr>
|
||||
<tr><td valign="top"><a href="#counterexample-1">counterexample/1</a></td><td>Tests the property in the same way as <a href="#quickcheck-1"><code>quickcheck/1</code></a>, but if
|
||||
a test fails, then the failing test case is returned as a counterexample.</td></tr>
|
||||
<tr><td valign="top"><a href="#counterexamples-0">counterexamples/0</a></td><td>Returns a list of the counterexamples found by the last call
|
||||
of <code>eqc:module</code>, paired with the name of the property that failed.</td></tr>
|
||||
<tr><td valign="top"><a href="#current_counterexample-0">current_counterexample/0</a></td><td>Returns the most recent
|
||||
counterexample found by QuickCheck.</td></tr>
|
||||
<tr><td valign="top"><a href="#equals-2">equals/2</a></td><td>A property which holds if X and Y are equal...</td></tr>
|
||||
<tr><td valign="top"><a href="#fails-1">fails/1</a></td><td>A property which succeeds when its argument fails.</td></tr>
|
||||
<tr><td valign="top"><a href="#measure-3">measure/3</a></td><td>Collects the values of X while testing Prop, and if all tests
|
||||
pass, displays statistics such as the minimum, average, and maximum
|
||||
values, identified by the name Name.</td></tr>
|
||||
<tr><td valign="top"><a href="#module-1">module/1</a></td><td>Tests all the properties exported from a module, given the module name.</td></tr>
|
||||
<tr><td valign="top"><a href="#numtests-2">numtests/2</a></td><td>Property which is logically equivalent to <tt>Prop</tt>, but is
|
||||
tested <tt>N</tt> times rather than 100.</td></tr>
|
||||
<tr><td valign="top"><a href="#on_output-2">on_output/2</a></td><td>Supplies an output function to be used instead of io:format
|
||||
when QuickCheck generates output.</td></tr>
|
||||
<tr><td valign="top"><a href="#on_test-2">on_test/2</a></td><td>Attaches a function to a property which is called every time a
|
||||
test passes or fails.</td></tr>
|
||||
<tr><td valign="top"><a href="#quickcheck-1">quickcheck/1</a></td><td>Tests the property in 100 random cases, printing a counter-example
|
||||
if one is found.</td></tr>
|
||||
<tr><td valign="top"><a href="#recheck-1">recheck/1</a></td><td>Tests the property with the <i>same</i> random number seed as
|
||||
the last failing call of <a href="#quickcheck-1"><code>quickcheck/1</code></a>.</td></tr>
|
||||
<tr><td valign="top"><a href="#start-0">start/0</a></td><td>Equivalent to <a href="#start-1"><tt>start(true)</tt></a>.
|
||||
</td></tr>
|
||||
<tr><td valign="top"><a href="#start-1">start/1</a></td><td>Starts the QuickCheck server.</td></tr>
|
||||
<tr><td valign="top"><a href="#stop-0">stop/0</a></td><td>Stops the QuickCheck server.</td></tr>
|
||||
<tr><td valign="top"><a href="#version-0">version/0</a></td><td></td></tr>
|
||||
<tr><td valign="top"><a href="#with_title-1">with_title/1</a></td><td>A printing method for collected data, which displays a title
|
||||
before
|
||||
the percentages of each value in the data.</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><tt>aggregate(L::list(term()), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>A property logically equivalent to <tt>Prop</tt>, but which collects a list of values in
|
||||
each test, and displays the distribution of these values once
|
||||
testing is complete. A typical use would be to aggregate the list of command names generated
|
||||
by <a href="eqc_statem.html#commands-1"><code>eqc_statem:commands/1</code></a>, in order to see how often each individual
|
||||
command appeared in generated tests:
|
||||
<pre>aggregate(command_names(Cmds), ...) </pre>
|
||||
<p>
|
||||
See also <a href="#aggregate-3"><code>aggregate/3</code></a>.
|
||||
</p></p>
|
||||
|
||||
<h3 class="function"><a name="aggregate-3">aggregate/3</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>aggregate(PrintMethod::(list(term())) -> any(), L::list(term()), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Like <a href="#aggregate-2"><code>aggregate/2</code></a>, but allows the user to specify how
|
||||
the collected values should be printed. The <tt>PrintMethod</tt> parameter
|
||||
is called with a sorted list of the collected data as an argument,
|
||||
and is expected to print some statistics. A predefined printing
|
||||
methods is provided to add a title to the statistics:
|
||||
<pre>aggregate(with_title(T),L,Prop)</pre>. This is useful when a property contains
|
||||
several calls to aggregate or collect.</p>
|
||||
|
||||
<h3 class="function"><a name="backtrace-0">backtrace/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>backtrace() -> ok</tt></p>
|
||||
</div><p>Displays a stack backtrace from the last exception QuickCheck caught. Note that
|
||||
this is only possible if the exception is raised in the process in which the test
|
||||
case starts. If a test case fails because of an exception in another, linked,
|
||||
process, then no backtrace is available. Calls to functions in the implementation
|
||||
of QuickCheck itself are not included in the backtrace.
|
||||
<p>If you really need to see a backtrace from a linked process, then you can do so by
|
||||
catching
|
||||
the exception yourself in that process, using erlang:get_stacktrace() to obtain the
|
||||
backtrace, and printing it yourself.</p></p>
|
||||
|
||||
<h3 class="function"><a name="check-2">check/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>check(P::<a href="#type-property">property()</a>, Values::<a href="#type-counterexample">counterexample()</a>) -> bool()</tt></p>
|
||||
</div><p>Tests the property in the case given. Counterexamples are generated by testing a
|
||||
property using <a href="#counterexample-1"><code>counterexample/1</code></a> or <a href="#counterexample-0"><code>counterexample/0</code></a>, and contain a list
|
||||
of the values bound by ?FORALL. A property tested by check should begin with the <i>same</i>
|
||||
sequence of ?FORALL s as the property from which the counterexample was generated, otherwise
|
||||
the results will be unpredictable. In particular, there is no check that the values
|
||||
in the counterexample could actually have been generated by the ?FORALL s in the property under
|
||||
test.
|
||||
<p><a href="#check-2"><code>check/2</code></a> can be used without a QuickCheck licence, allowing anyone to run
|
||||
tests that a licenced user has generated.</p></p>
|
||||
|
||||
<h3 class="function"><a name="classify-3">classify/3</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>classify(B::bool(), S::term(), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Property which is logically equivalent to <tt>Prop</tt>, but also
|
||||
classifies test cases and displays the distribution of test case classes
|
||||
when testing is complete. If the boolean is true then the current test case is
|
||||
labelled with the term <tt>S</tt>,
|
||||
and, after testing is complete, QuickCheck prints out the percentage of
|
||||
test cases carrying each label. This can be used to check that the space
|
||||
of possible test cases has been covered reasonably well. For example,
|
||||
classifying test cases according to the length of a list enables one to
|
||||
see whether unreasonably many lists were short. Classifying
|
||||
test cases is a way to discover skewed distributions, such as can arise
|
||||
from using <tt>?IMPLIES</tt>. It is good practice to check the distribution
|
||||
of test data using <tt>classify</tt> or <a href="#collect-2"><code>collect/2</code></a>, at least while
|
||||
properties are being developed.
|
||||
<p>
|
||||
Each test case can be labelled with any number of labels: QuickCheck then
|
||||
displays the percentage of each label in the generated
|
||||
test data.
|
||||
</p>
|
||||
<p>
|
||||
Calls of classify or collect can be nested, in which case each call
|
||||
generates its own table of distributions.
|
||||
</p></p>
|
||||
|
||||
<h3 class="function"><a name="collect-2">collect/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>collect(S::term(), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Equivalent to <a href="#aggregate-2"><tt>aggregate([S], Prop)</tt></a>.</p>
|
||||
|
||||
|
||||
<h3 class="function"><a name="collect-3">collect/3</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>collect(PrintMethod::(list(term())) -> any(), S::term(), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Equivalent to <a href="#aggregate-3"><tt>aggregate(PrintMethod, [S], Prop)</tt></a>.</p>
|
||||
|
||||
|
||||
<h3 class="function"><a name="counterexample-0">counterexample/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>counterexample() -> undefined | <a href="#type-counterexample">counterexample()</a></tt></p>
|
||||
</div><p>Returns the last counter-example found. See <a href="#counterexample-1"><code>counterexample/1</code></a>.</p>
|
||||
|
||||
<h3 class="function"><a name="counterexample-1">counterexample/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>counterexample(P::<a href="#type-property">property()</a>) -> true | <a href="#type-counterexample">counterexample()</a></tt></p>
|
||||
</div><p>Tests the property in the same way as <a href="#quickcheck-1"><code>quickcheck/1</code></a>, but if
|
||||
a test fails, then the failing test case is returned as a counterexample.</p>
|
||||
|
||||
<h3 class="function"><a name="counterexamples-0">counterexamples/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>counterexamples() -> list({atom(), <a href="#type-counterexample">counterexample()</a>})</tt></p>
|
||||
</div><p>Returns a list of the counterexamples found by the last call
|
||||
of <code>eqc:module</code>, paired with the name of the property that failed.</p>
|
||||
|
||||
<h3 class="function"><a name="current_counterexample-0">current_counterexample/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>current_counterexample() -> <a href="#type-counterexample">counterexample()</a></tt></p>
|
||||
</div><p>Returns the most recent
|
||||
counterexample found by QuickCheck. This can be used while
|
||||
QuickCheck is shrinking a failed test case to follow progress, or if
|
||||
shrinking must be interrupted, to recover the last failed test case
|
||||
that QuickCheck had found. The counterexample is fetched from a file
|
||||
in the current directory.</p>
|
||||
|
||||
<h3 class="function"><a name="equals-2">equals/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>equals(X::any(), Y::any()) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>A property which holds if X and Y are equal... and displays
|
||||
their values when a test fails.</p>
|
||||
|
||||
<h3 class="function"><a name="fails-1">fails/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>fails(P::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>A property which succeeds when its argument fails.
|
||||
Sometimes it is useful to write down properties which do <i>not</i> hold
|
||||
(even though one might expect them to). This can help prevent misconceptions.
|
||||
<tt>fails(P)</tt> is tested in the same way as <tt>P</tt>, but
|
||||
fails only if <tt>P</tt> <i>succeeds</i> 100 times. Thus
|
||||
<tt>fails(P)</tt> declares that QuickCheck should be able to find
|
||||
a counter-example to property <tt>P</tt>.</p>
|
||||
|
||||
<h3 class="function"><a name="measure-3">measure/3</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>measure(Name::atom() | string(), X::number() | list(number()), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Collects the values of X while testing Prop, and if all tests
|
||||
pass, displays statistics such as the minimum, average, and maximum
|
||||
values, identified by the name Name. X can also be a list of values,
|
||||
in which case all of them are included in the measurements.</p>
|
||||
|
||||
<h3 class="function"><a name="module-1">module/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>module(Mod::atom()) -> list(atom())</tt></p>
|
||||
</div><p>Tests all the properties exported from a module, given the module name.
|
||||
Any function with arity zero whose name begins with "prop_" is treated as a
|
||||
property. The result is a list of the names of the properties that
|
||||
failed. See also <a href="#module-2"><code>module/2</code></a>.</p>
|
||||
|
||||
<h3 class="function"><a name="numtests-2">numtests/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>numtests(N::<a href="#type-int">int()</a>, Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Property which is logically equivalent to <tt>Prop</tt>, but is
|
||||
tested <tt>N</tt> times rather than 100. If numtests appears more than once
|
||||
in a property, then the outermost use takes precedence.</p>
|
||||
|
||||
<h3 class="function"><a name="on_output-2">on_output/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>on_output(Fun::(string(), list(term())) -> any(), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Supplies an output function to be used instead of io:format
|
||||
when QuickCheck generates output. All output generated by
|
||||
QuickCheck is passed to <tt>Fun</tt>, in the form of a format
|
||||
string and a list of terms--the same arguments expected by
|
||||
<tt>io:format</tt>. By supplying a function which does nothing,
|
||||
QuickCheck can be run silently. By supplying a function which
|
||||
writes to a file, all QuickCheck output can be saved.
|
||||
<p>Note that output generated by user code is <i>not</i> passed to
|
||||
this output function. For example, calls to io:format in the
|
||||
property, or in the code under test, will generate output in the
|
||||
shell as usual. This applies even to calls inside a
|
||||
<tt>?WHENFAIL</tt>. If you want to redirect such output also, then
|
||||
you need to modify your own code appropriately.</p>
|
||||
<p>The reason that <tt>Fun</tt> is passed a format string and
|
||||
arguments, rather than an already formatted string, is to make it
|
||||
easier to extract information from the output without parsing
|
||||
it. However, there is no guarantee that different versions of
|
||||
QuickCheck will use the same format strings and term lists--you use
|
||||
this information at your own risk, in other words.</p></p>
|
||||
|
||||
<h3 class="function"><a name="on_test-2">on_test/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>on_test(Fun::(<a href="#type-counterexample">counterexample()</a>, bool()) -> any(), Prop::<a href="#type-property">property()</a>) -> <a href="#type-property">property()</a></tt></p>
|
||||
</div><p>Attaches a function to a property which is called every time a
|
||||
test passes or fails. The arguments are the test case (a list of
|
||||
values), and a boolean indicating whether or not the test
|
||||
passed. Tests which are skipped (because of an
|
||||
<tt>?IMPLIES(false,...)</tt>) are not included.</p>
|
||||
|
||||
<h3 class="function"><a name="quickcheck-1">quickcheck/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>quickcheck(P::<a href="#type-property">property()</a>) -> bool()</tt></p>
|
||||
</div><p>Tests the property in 100 random cases, printing a counter-example
|
||||
if one is found. Initially small test cases are generated, then the
|
||||
size increases as testing progresses (see <a href="eqc_gen.html"><code>eqc_gen</code></a>, <tt>?SIZED</tt>,
|
||||
<a href="eqc_gen.html#resize-2"><code>eqc_gen:resize/2</code></a> for the way size affects test data generation).
|
||||
The result is <tt>true</tt> if all tests succeeded (or if one failed,
|
||||
and failure was expected). On success, <tt>quickcheck</tt> analyses
|
||||
the distribution of test case labels. On failure, <tt>quickcheck</tt>
|
||||
tries to simplify the counter-example found as far as possible (see <i>
|
||||
shrinking</i>, described in <a href="eqc_gen.html"><code>eqc_gen</code></a>).</p>
|
||||
|
||||
<h3 class="function"><a name="recheck-1">recheck/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>recheck(Prop::<a href="#type-property">property()</a>) -> bool()</tt></p>
|
||||
</div><p>Tests the property with the <i>same</i> random number seed as
|
||||
the last failing call of <a href="#quickcheck-1"><code>quickcheck/1</code></a>. If the property is
|
||||
the same as in that last call, then the same test case will be
|
||||
generated. Note that recheck repeats the test <i>and its
|
||||
shrinking</i>. This can be used to adjust the shrinking strategy in
|
||||
the property, then reshrink the same counterexample, perhaps to a
|
||||
better result. If you just
|
||||
want to repeat the <i>shrunk</i> test, then use
|
||||
<pre>eqc:check(Prop,eqc:counterexample())</pre> instead.
|
||||
<p><b>Note:</b> the type and behaviour of recheck changed in version 1.19.</p></p>
|
||||
|
||||
<h3 class="function"><a name="start-0">start/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>start() -> any()</tt></p>
|
||||
</div><p>Equivalent to <a href="#start-1"><tt>start(true)</tt></a>.</p>
|
||||
|
||||
|
||||
<h3 class="function"><a name="start-1">start/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>start(Force::bool()) -> pid()</tt></p>
|
||||
</div><p><p>Starts the QuickCheck server. If it is already running on this
|
||||
node, nothing is done.</p>
|
||||
|
||||
Each user can run only one instance of the QuickCheck server at a
|
||||
time. If the server is already running on another Erlang node, it
|
||||
will be terminated automatically if <tt>Force</tt> is
|
||||
<tt>true</tt>. If another instance is running, and <tt>Force</tt> is
|
||||
<tt>false</tt>, then the new instance will not start.</p>
|
||||
|
||||
<h3 class="function"><a name="stop-0">stop/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>stop() -> any()</tt></p>
|
||||
</div><p>Stops the QuickCheck server.
|
||||
QuickCheck properties are tested in the QuickCheck server process, which is
|
||||
spawned automatically when quickcheck is first called. Usually there is no
|
||||
need to stop the QuickCheck server explicitly, but if a need does arise
|
||||
then this function can be used. For example, if the shell process crashes
|
||||
and is restarted, then the QuickCheck server should be stopped and restarted
|
||||
too, since otherwise the server will crash when it attempts to write to the
|
||||
console.</p>
|
||||
|
||||
<h3 class="function"><a name="version-0">version/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>version() -> any()</tt></p>
|
||||
</div>
|
||||
|
||||
<h3 class="function"><a name="with_title-1">with_title/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>with_title(Title::atom() | string()) -> <a href="#type-print_method">print_method()</a></tt></p>
|
||||
</div><p>A printing method for collected data, which displays a title
|
||||
before
|
||||
the percentages of each value in the data. It is intended to be
|
||||
passed to <a href="#collect-3"><code>collect/3</code></a> or <a href="#aggregate-3"><code>aggregate/3</code></a>.</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, Jun 13 2010, 13:15:30.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
342
lib/eqc/doc/eqc_gen.html
Normal file
342
lib/eqc/doc/eqc_gen.html
Normal file
|
|
@ -0,0 +1,342 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Module eqc_gen</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 eqc_gen</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 module implements QuickCheck generators.
|
||||
|
||||
<p><b>Version:</b> 1.0.1</p>
|
||||
|
||||
<h2><a name="description">Description</a></h2>
|
||||
This module implements QuickCheck generators.
|
||||
QuickCheck generators are used to generate random test data for
|
||||
QuickCheck properties. A generator specifies three things at the same
|
||||
time:
|
||||
<ul> <li> A <i>set</i> of values that can be generated,</li>
|
||||
<li> A <i>probability distribution</i> on that set,</li>
|
||||
<li> A way of <i>shrinking</i> generated values to similar,
|
||||
smaller values---used after a test fails, to enable
|
||||
QuickCheck to search for a similar, but simpler failing case.</li>
|
||||
</ul>
|
||||
QuickCheck permits constants to be used as generators for their own value,
|
||||
and also permits tuples, records, and lists containing generators to be
|
||||
used as generators for values of the same form. For example,
|
||||
<pre> {int(),bool()} </pre>
|
||||
is a generator that generates random pairs of integers and booleans.
|
||||
<p>
|
||||
Many of the functions in this module are usually used via macros, defined
|
||||
in <tt>eqc.hrl</tt>. These macros are listed here.
|
||||
<h2><tt>?LET(Pat,G1,G2)</tt></h2>
|
||||
Generates a value from <tt>G1</tt>,
|
||||
binds it to <tt>Pat</tt>, then generates a value from <tt>G2</tt>
|
||||
(which may refer to the variables bound in <tt>Pat</tt>).
|
||||
<p>The
|
||||
result is shrunk by <i>first</i> shrinking the value generated by
|
||||
<tt>G1</tt> while the test still fails, then shrinking the value
|
||||
generated by <tt>G2</tt>. It is thus better to write
|
||||
<tt>?LET({X,Y},{G1,G2},G3)</tt> than
|
||||
<tt>?LET(X,G1,?LET(Y,G2,G3))</tt> (provided <tt>G2</tt> does
|
||||
not depend on <tt>X</tt>), since in the first case shrinking can
|
||||
shrink <tt>G1</tt> a bit, shrink <tt>G2</tt>, then shrink
|
||||
<tt>G1</tt> some more, while in the second case <tt>G1</tt>
|
||||
cannot be shrunk further once shrinking <tt>G2</tt> has begun.</p>
|
||||
<h2><tt>?SIZED(Size,G)</tt></h2>
|
||||
Binds the variable <tt>Size</tt> to the current size parameter for
|
||||
generation. <tt>G</tt> may use <tt>Size</tt> in any way to control the
|
||||
size of generated data. However, as <tt>Size</tt> increases,
|
||||
the set of possible values that <tt>G</tt> can generate should also
|
||||
increase. <tt>Size</tt> is always a natural number, and increases during
|
||||
QuickCheck testing from a small value up to about 40. See also
|
||||
<a href="#resize-2"><code>resize/2</code></a> and <a href="#pick-2"><code>pick/2</code></a>.
|
||||
<h2><tt>?SUCHTHAT(X,G,P)</tt></h2>
|
||||
Generates values <tt>X</tt> from <tt>G</tt> such that the condition <tt>P</tt> is true.
|
||||
Should only be used if the probability that <tt>P</tt> holds is reasonably high for values
|
||||
generated by <tt>G</tt>--otherwise generation may be slow, and the
|
||||
distribution of generated values may be skewed. For example,
|
||||
<pre>?SUCHTHAT(Xs,list(int()),lists:sort(Xs)==Xs)</pre>
|
||||
generates predominantly very short lists, since the probability that a random longer list
|
||||
will just happen to be sorted is very low. If no value is found within 100 attempts,
|
||||
then ?SUCHTHAT exits.
|
||||
|
||||
|
||||
<h2><tt>?LETSHRINK(Pat,G1,G2)</tt></h2>
|
||||
This behaves in the same way as <tt>?LET(Pat,G1,G2)</tt>, <i>except</i>
|
||||
that <tt>G1</tt> must generate a <i>list</i> of values, and each one of these
|
||||
values is added as a possible shrinking of the result. This is intended for
|
||||
use in generating tree-like structures. For example,
|
||||
<pre>
|
||||
?LETSHRINK([L,R],[tree(),tree()],{branch,L,R})</pre>
|
||||
generates a tree node <tt>{branch,L,R}</tt>, which can shrink to either
|
||||
<tt>L</tt> or <tt>R</tt>.
|
||||
<h2><tt>?LAZY(G)</tt></h2>
|
||||
A generator equivalent to its argument, but which is always cheap to construct. To be used,
|
||||
for example, in recursive generators to avoid building a huge generator, only a small part
|
||||
of which will be used.
|
||||
</p>
|
||||
<h2><a name="types">Data Types</a></h2>
|
||||
|
||||
<h3 class="typedecl"><a name="type-box">box()</a></h3>
|
||||
<p><b>abstract datatype</b>: <tt>box(A)</tt></p>
|
||||
<p>Boxes are not supported in this version of QuickCheck.</p>
|
||||
|
||||
<h3 class="typedecl"><a name="type-gen">gen()</a></h3>
|
||||
<p><b>abstract datatype</b>: <tt>gen(A)</tt></p>
|
||||
<p>A QuickCheck generator for values of type A.
|
||||
QuickCheck generators are first-class
|
||||
values, and can be used repeatedly to generate many different values.</p>
|
||||
|
||||
<h3 class="typedecl"><a name="type-proplist">proplist()</a></h3>
|
||||
<p><tt>proplist() = list({atom(), term()})</tt></p>
|
||||
<p>A property list associating values with names.
|
||||
See the standard module <tt>proplists</tt>.</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="#binary-0">binary/0</a></td><td>Generates a binary of random size.</td></tr>
|
||||
<tr><td valign="top"><a href="#binary-1">binary/1</a></td><td>Generates a binary of a given size in bytes.</td></tr>
|
||||
<tr><td valign="top"><a href="#bitstring-0">bitstring/0</a></td><td>Generates a list of bits in a bitstring.</td></tr>
|
||||
<tr><td valign="top"><a href="#bitstring-1">bitstring/1</a></td><td>Generates a bitstring of a given size in bits.</td></tr>
|
||||
<tr><td valign="top"><a href="#bool-0">bool/0</a></td><td>Generates a random boolean.</td></tr>
|
||||
<tr><td valign="top"><a href="#char-0">char/0</a></td><td>Generates a random character.</td></tr>
|
||||
<tr><td valign="top"><a href="#choose-2">choose/2</a></td><td>Generates a number in the range M to N.</td></tr>
|
||||
<tr><td valign="top"><a href="#default-2">default/2</a></td><td>Adds a default value to a generator, to be chosen half the time.</td></tr>
|
||||
<tr><td valign="top"><a href="#elements-1">elements/1</a></td><td>Generates an element of the list argument.</td></tr>
|
||||
<tr><td valign="top"><a href="#eval-1">eval/1</a></td><td>Evaluates terms of the form <tt>{call,Module,Function,Args}</tt> anywhere in its
|
||||
argument, replacing them by the result of the corresponding function call.</td></tr>
|
||||
<tr><td valign="top"><a href="#eval-2">eval/2</a></td><td>Like <a href="#eval-1"><code>eval/1</code></a>, but also replaces symbolic variables, that is,
|
||||
terms of the form <tt>{var,V}</tt>, by their corresponding values in the
|
||||
property list.</td></tr>
|
||||
<tr><td valign="top"><a href="#frequency-1">frequency/1</a></td><td>Makes a weighted choice between the generators in its argument, such that the
|
||||
probability of choosing each generator is proportional to the weight paired with it.</td></tr>
|
||||
<tr><td valign="top"><a href="#function0-1">function0/1</a></td><td>Generates a function of no arguments with result generated by <tt>G</tt>.</td></tr>
|
||||
<tr><td valign="top"><a href="#function1-1">function1/1</a></td><td>Generates a function of one argument with result generated by <tt>G</tt>.</td></tr>
|
||||
<tr><td valign="top"><a href="#int-0">int/0</a></td><td>Generates a small integer (with absolute value bounded by the generation size).</td></tr>
|
||||
<tr><td valign="top"><a href="#is_generator-1">is_generator/1</a></td><td>Returns true if the argument is a QuickCheck generator.</td></tr>
|
||||
<tr><td valign="top"><a href="#largeint-0">largeint/0</a></td><td>Generates an integer from a large range.</td></tr>
|
||||
<tr><td valign="top"><a href="#list-1">list/1</a></td><td>Generates a list of elements generated by its argument.</td></tr>
|
||||
<tr><td valign="top"><a href="#nat-0">nat/0</a></td><td>Generates a small natural number (bounded by the generation size).</td></tr>
|
||||
<tr><td valign="top"><a href="#non_empty-1">non_empty/1</a></td><td>Make sure that the generated value is not empty.</td></tr>
|
||||
<tr><td valign="top"><a href="#noshrink-1">noshrink/1</a></td><td>Generates the same values as <tt>G</tt>, but these values are never
|
||||
shrunk.</td></tr>
|
||||
<tr><td valign="top"><a href="#oneof-1">oneof/1</a></td><td>Generates a value using a randomly chosen element of the list of generators.</td></tr>
|
||||
<tr><td valign="top"><a href="#orderedlist-1">orderedlist/1</a></td><td>Generates an ordered list of elements generated by <tt>G</tt>.</td></tr>
|
||||
<tr><td valign="top"><a href="#real-0">real/0</a></td><td>Generates a real number.</td></tr>
|
||||
<tr><td valign="top"><a href="#resize-2">resize/2</a></td><td>Binds the generation size parameter to <tt>Size</tt> within <tt>G</tt>.</td></tr>
|
||||
<tr><td valign="top"><a href="#return-1">return/1</a></td><td>Constructs a generator that always generates the value
|
||||
<tt>X</tt>.</td></tr>
|
||||
<tr><td valign="top"><a href="#sample-1">sample/1</a></td><td>Prints 11 values randomly generated by <tt>G</tt>, for sizes ranging
|
||||
from 10 to 20.</td></tr>
|
||||
<tr><td valign="top"><a href="#sampleshrink-1">sampleshrink/1</a></td><td>Prints a value generated by <tt>G</tt>, followed by one way of shrinking it.</td></tr>
|
||||
<tr><td valign="top"><a href="#shuffle-1">shuffle/1</a></td><td>Shuffles a list and shrinks to the unshuffled list.</td></tr>
|
||||
<tr><td valign="top"><a href="#vector-2">vector/2</a></td><td>Generates a list of the given length, with elements generated by <tt>G</tt>.</td></tr>
|
||||
</table>
|
||||
|
||||
<h2><a name="functions">Function Details</a></h2>
|
||||
|
||||
<h3 class="function"><a name="binary-0">binary/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>binary() -> <a href="#type-gen">gen(binary())</a></tt></p>
|
||||
</div><p>Generates a binary of random size. The binary shrinks both in
|
||||
size as well as in content. If you consider the
|
||||
binary as a representation of a number, then each shrinking step
|
||||
will result in a smaller-or-equal number.</p>
|
||||
|
||||
<h3 class="function"><a name="binary-1">binary/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>binary(NrBytes::<a href="#type-int">int()</a>) -> <a href="#type-gen">gen(binary())</a></tt></p>
|
||||
</div><p>Generates a binary of a given size in bytes. When shrinking,
|
||||
the size is unchanged, but content shrinks like <a href="#binary-0"><code>binary/0</code></a>.</p>
|
||||
|
||||
<h3 class="function"><a name="bitstring-0">bitstring/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>bitstring() -> <a href="#type-gen">gen(<a href="#type-bitstring">bitstring()</a>)</a></tt></p>
|
||||
</div><p>Generates a list of bits in a bitstring. For Erlang release R12B and
|
||||
later.
|
||||
The bitstring shrinks both in
|
||||
size as well as in content. If you consider the
|
||||
bitstring as a representation of a number, then each shrinking step
|
||||
will result in a smaller-or-equal number.</p>
|
||||
|
||||
<h3 class="function"><a name="bitstring-1">bitstring/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>bitstring(NrBits::<a href="#type-int">int()</a>) -> <a href="#type-gen">gen(<a href="#type-bitstring">bitstring()</a>)</a></tt></p>
|
||||
</div><p>Generates a bitstring of a given size in bits. For Erlang
|
||||
release R12B and later. When shrinking,
|
||||
the size is unchanged, but content shrinks like <a href="#bitstring-0"><code>bitstring/0</code></a>.</p>
|
||||
|
||||
<h3 class="function"><a name="bool-0">bool/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>bool() -> <a href="#type-gen">gen(bool())</a></tt></p>
|
||||
</div><p>Generates a random boolean. Shrinks to false.</p>
|
||||
|
||||
<h3 class="function"><a name="char-0">char/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>char() -> <a href="#type-gen">gen(char())</a></tt></p>
|
||||
</div><p>Generates a random character. Shrinks to a, b or c.</p>
|
||||
|
||||
<h3 class="function"><a name="choose-2">choose/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>choose(M, N::integer()) -> <a href="#type-gen">gen(integer())</a></tt></p>
|
||||
</div><p>Generates a number in the range M to N.
|
||||
The result shrinks towards smaller absolute values.</p>
|
||||
|
||||
<h3 class="function"><a name="default-2">default/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>default(Default::A, G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Adds a default value to a generator, to be chosen half the time. Any
|
||||
other value shrinks to the default.</p>
|
||||
|
||||
<h3 class="function"><a name="elements-1">elements/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>elements(Xs::list(A)) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Generates an element of the list argument. Shrinking chooses an earlier element.</p>
|
||||
|
||||
<h3 class="function"><a name="eval-1">eval/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>eval(Term::term()) -> term()</tt></p>
|
||||
</div><p>Evaluates terms of the form <tt>{call,Module,Function,Args}</tt> anywhere in its
|
||||
argument, replacing them by the result of the corresponding function call.
|
||||
This is useful when, for example, test data is of an abstract datatype, and
|
||||
we want to know how it was generated, rather than its representation--it is
|
||||
much clearer to see that a test failed for <tt>sets:new()</tt> (that is
|
||||
<tt>{call,sets,new,[]}</tt>), for example,
|
||||
than for its representation.
|
||||
We write <tt>?FORALL(X,TGen,...eval(X)...)</tt>, where <tt>TGen</tt>
|
||||
generates terms containing calls, so that test cases are displayed in this
|
||||
form, but the actual test data is the result of evaluating the calls.</p>
|
||||
|
||||
<h3 class="function"><a name="eval-2">eval/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>eval(Env::<a href="#type-proplist">proplist()</a>, T::term()) -> term()</tt></p>
|
||||
</div><p>Like <a href="#eval-1"><code>eval/1</code></a>, but also replaces symbolic variables, that is,
|
||||
terms of the form <tt>{var,V}</tt>, by their corresponding values in the
|
||||
property list. This should be a list of pairs of atoms and values. For example,
|
||||
<tt>eval([{x,3}],{var,x})</tt> evaluates to 3.</p>
|
||||
|
||||
<h3 class="function"><a name="frequency-1">frequency/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>frequency(FGs::list({integer(), <a href="#type-gen">gen(A)</a>})) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Makes a weighted choice between the generators in its argument, such that the
|
||||
probability of choosing each generator is proportional to the weight paired with it.
|
||||
The
|
||||
weights should be non-negative integers and sum to a positive value. A generator
|
||||
with a weight of zero will not be chosen.</p>
|
||||
|
||||
<h3 class="function"><a name="function0-1">function0/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>function0(G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(() -> A)</a></tt></p>
|
||||
</div><p>Generates a function of no arguments with result generated by <tt>G</tt>.</p>
|
||||
|
||||
<h3 class="function"><a name="function1-1">function1/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>function1(G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen((term()) -> A)</a></tt></p>
|
||||
</div><p>Generates a function of one argument with result generated by <tt>G</tt>.
|
||||
The generated function is pure--will always return the same result for the same argument--
|
||||
and the result depends randomly on the argument.</p>
|
||||
|
||||
<h3 class="function"><a name="int-0">int/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>int() -> <a href="#type-gen">gen(integer())</a></tt></p>
|
||||
</div><p>Generates a small integer (with absolute value bounded by the generation size).</p>
|
||||
|
||||
<h3 class="function"><a name="is_generator-1">is_generator/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>is_generator(X::any()) -> bool()</tt></p>
|
||||
</div><p>Returns true if the argument is a QuickCheck generator.</p>
|
||||
|
||||
<h3 class="function"><a name="largeint-0">largeint/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>largeint() -> any()</tt></p>
|
||||
</div><p>Generates an integer from a large range.</p>
|
||||
|
||||
<h3 class="function"><a name="list-1">list/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>list(G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(list(A))</a></tt></p>
|
||||
</div><p>Generates a list of elements generated by its argument. Shrinking drops elements
|
||||
from the list. The length of the list varies up to one third of the generation size parameter.</p>
|
||||
|
||||
<h3 class="function"><a name="nat-0">nat/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>nat() -> <a href="#type-gen">gen(integer())</a></tt></p>
|
||||
</div><p>Generates a small natural number (bounded by the generation size).</p>
|
||||
|
||||
<h3 class="function"><a name="non_empty-1">non_empty/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>non_empty(G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Make sure that the generated value is not empty.
|
||||
For example when creating a list of integers, but the list should always
|
||||
contain at least one element <tt>non_empty(list(int()))</tt>.</p>
|
||||
|
||||
<h3 class="function"><a name="noshrink-1">noshrink/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>noshrink(G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Generates the same values as <tt>G</tt>, but these values are never
|
||||
shrunk.</p>
|
||||
|
||||
<h3 class="function"><a name="oneof-1">oneof/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>oneof(Gs::list(<a href="#type-gen">gen(A)</a>)) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Generates a value using a randomly chosen element of the list of generators.</p>
|
||||
|
||||
<h3 class="function"><a name="orderedlist-1">orderedlist/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>orderedlist(G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(list(A))</a></tt></p>
|
||||
</div><p>Generates an ordered list of elements generated by <tt>G</tt>.</p>
|
||||
|
||||
<h3 class="function"><a name="real-0">real/0</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>real() -> <a href="#type-gen">gen(float())</a></tt></p>
|
||||
</div><p>Generates a real number.</p>
|
||||
|
||||
<h3 class="function"><a name="resize-2">resize/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>resize(Size::integer(), G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Binds the generation size parameter to <tt>Size</tt> within <tt>G</tt>.
|
||||
Size should never be negative.</p>
|
||||
|
||||
<h3 class="function"><a name="return-1">return/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>return(X::A) -> <a href="#type-gen">gen(A)</a></tt></p>
|
||||
</div><p>Constructs a generator that always generates the value
|
||||
<tt>X</tt>. Most values can also be used as generators for
|
||||
themselves, making <tt>return</tt> unnecessary, but
|
||||
<tt>return(X)</tt> may be more efficient than using <tt>X</tt> as a
|
||||
generator, since when <tt>return(X)</tt> is used then QuickCheck
|
||||
does not traverse <tt>X</tt> searching for values to be intepreted
|
||||
specially.</p>
|
||||
|
||||
<h3 class="function"><a name="sample-1">sample/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>sample(G::<a href="#type-gen">gen(A)</a>) -> ok</tt></p>
|
||||
</div><p>Prints 11 values randomly generated by <tt>G</tt>, for sizes ranging
|
||||
from 10 to 20.</p>
|
||||
|
||||
<h3 class="function"><a name="sampleshrink-1">sampleshrink/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>sampleshrink(G::<a href="#type-gen">gen(A)</a>) -> ok</tt></p>
|
||||
</div><p>Prints a value generated by <tt>G</tt>, followed by one way of shrinking it.
|
||||
Each following line displays a list of values that the <i>first</i> value on the
|
||||
previous line can be shrunk to in one step. Thus the output traces the leftmost path
|
||||
through the shrinking tree.</p>
|
||||
|
||||
<h3 class="function"><a name="shuffle-1">shuffle/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>shuffle(List::list(A)) -> <a href="#type-gen">gen(list(A))</a></tt></p>
|
||||
</div><p>Shuffles a list and shrinks to the unshuffled list.</p>
|
||||
|
||||
<h3 class="function"><a name="vector-2">vector/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>vector(K::integer(), G::<a href="#type-gen">gen(A)</a>) -> <a href="#type-gen">gen(list(A))</a></tt></p>
|
||||
</div><p>Generates a list of the given length, with elements generated by <tt>G</tt>.</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, Jun 13 2010, 13:15:30.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
156
lib/eqc/doc/eqc_symbolic.html
Normal file
156
lib/eqc/doc/eqc_symbolic.html
Normal file
|
|
@ -0,0 +1,156 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Module eqc_symbolic</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 eqc_symbolic</h1>
|
||||
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>
|
||||
This module implements QuickCheck generators and utility functions for
|
||||
symbolic calls.
|
||||
|
||||
<p><b>Version:</b> 1.0.1</p>
|
||||
|
||||
<h2><a name="description">Description</a></h2><p>
|
||||
This module implements QuickCheck generators and utility functions for
|
||||
symbolic calls.</p>
|
||||
|
||||
<p>In test case generation it is often an advantage to postpone calling
|
||||
functions in the subject under test. In a test one is interested in
|
||||
the actual function that is called as well as its evaluated result.
|
||||
If one would evaluate the result already at generation time, then the actual
|
||||
call is not visible in the QuickCheck counter example shown in a
|
||||
failing test.</p>
|
||||
|
||||
<p>For example, when testing a data structure like the OTP library sets.erl,
|
||||
one may need more information than just the value to detect what goes
|
||||
wrong with the following property:</p>
|
||||
|
||||
<pre>
|
||||
prop_sets() ->
|
||||
?FORALL({S1,S2},{set(),set()},
|
||||
begin
|
||||
L1 = sets:to_list(S1),
|
||||
L2 = sets:to_list(S2),
|
||||
sets:intersection(S1,S2) ==
|
||||
sets:from_list(L1--(L1--L2))
|
||||
end).
|
||||
</pre>
|
||||
|
||||
which will fail with for example the following counter example:
|
||||
<pre>
|
||||
Failed! After 132 tests.
|
||||
Shrinking.......(7 times)
|
||||
{{set,2,16,16,8,80,48,
|
||||
{[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[]},
|
||||
{{[],[],[],[],[],[],[],[],[],[],[],[-15,33],[],[],[],[]}}},
|
||||
{set,3,16,16,8,80,48,
|
||||
{[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],[]},
|
||||
{{[0],[],[],[],[],[],[],[],[],[],[],[33,-15],[],[],[],[]}}}}
|
||||
false
|
||||
</pre>
|
||||
|
||||
We would really need to understand the internal representation of sets in order to understand which
|
||||
sets we have generated and even if we know that, we have no clue which operations were used to
|
||||
create those sets.
|
||||
This is were symbolic representations help a lot. We would create a recursive generator that
|
||||
creates symbolic sets and use the following property instead:
|
||||
<pre>
|
||||
prop_sets() ->
|
||||
?FORALL({SymbS1,SymbS2},{set(),set()},
|
||||
begin
|
||||
S1 = eval(SymbS1),
|
||||
S2 = eval(SymbS2),
|
||||
L1 = sets:to_list(S1),
|
||||
L2 = sets:to_list(S2),
|
||||
sets:intersection(S1,S2) ==
|
||||
sets:from_list(L1--(L1--L2))
|
||||
end).
|
||||
|
||||
This would then result in a more readable error message:
|
||||
Shrinking..........(10 times)
|
||||
{{call,sets,from_list,[[6,-10]]},{call,sets,from_list,[[0,-10,6]]}}
|
||||
false
|
||||
</pre>
|
||||
|
||||
Symbolic representation of function calls provides us with
|
||||
<ul>
|
||||
<li>Better readable counter examples</li>
|
||||
<li>No need to break abstraction by using clean interface to code
|
||||
under test</li>
|
||||
<li>Better possibilities for shrinking when defining generators</li>
|
||||
</ul>
|
||||
<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="#defined-1">defined/1</a></td><td>Checks whether a term can be evaluated without raising an exception.</td></tr>
|
||||
<tr><td valign="top"><a href="#eval-1">eval/1</a></td><td>Evaluates terms of the form <tt>{call,Module,Function,Args}</tt> anywhere in its
|
||||
argument, replacing them by the result of the corresponding function call.</td></tr>
|
||||
<tr><td valign="top"><a href="#eval-2">eval/2</a></td><td>Like <a href="#eval-1"><code>eval/1</code></a>, but also replaces symbolic variables, that is,
|
||||
terms of the form <tt>{var,V}</tt>, by their corresponding values in the
|
||||
property list.</td></tr>
|
||||
<tr><td valign="top"><a href="#pretty_print-1">pretty_print/1</a></td><td>Pretty printing of symbolic terms.</td></tr>
|
||||
<tr><td valign="top"><a href="#pretty_print-2">pretty_print/2</a></td><td>Pretty printing of symbolic terms within given environment.</td></tr>
|
||||
<tr><td valign="top"><a href="#well_defined-1">well_defined/1</a></td><td>Generates a well defined symbolic value.</td></tr>
|
||||
</table>
|
||||
|
||||
<h2><a name="functions">Function Details</a></h2>
|
||||
|
||||
<h3 class="function"><a name="defined-1">defined/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>defined(E::term()) -> bool()</tt></p>
|
||||
</div><p>Checks whether a term can be evaluated without raising an exception.
|
||||
Some symbolic terms may raise an exception when evaluating, e.g., division by zero would
|
||||
raise an exception, thus <tt>eval({call,erlang,'div',[1,0]})</tt> raises an exception as well.</p>
|
||||
|
||||
<h3 class="function"><a name="eval-1">eval/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>eval(Term::term()) -> term()</tt></p>
|
||||
</div><p>Evaluates terms of the form <tt>{call,Module,Function,Args}</tt> anywhere in its
|
||||
argument, replacing them by the result of the corresponding function call.
|
||||
This is useful when, for example, test data is of an abstract datatype, and
|
||||
we want to know how it was generated, rather than its representation--it is
|
||||
much clearer to see that a test failed for <tt>sets:new()</tt> (that is
|
||||
<tt>{call,sets,new,[]}</tt>), for example,
|
||||
than for its representation.
|
||||
We write <tt>?FORALL(X,TGen,...eval(X)...)</tt>, where <tt>TGen</tt>
|
||||
generates terms containing calls, so that test cases are displayed in this
|
||||
form, but the actual test data is the result of evaluating the calls.</p>
|
||||
|
||||
<h3 class="function"><a name="eval-2">eval/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>eval(Env::<a href="#type-proplist">proplist()</a>, T::term()) -> term()</tt></p>
|
||||
</div><p>Like <a href="#eval-1"><code>eval/1</code></a>, but also replaces symbolic variables, that is,
|
||||
terms of the form <tt>{var,V}</tt>, by their corresponding values in the
|
||||
property list. This should be a list of pairs of atoms and values. For example,
|
||||
<tt>eval([{x,3}],{var,x})</tt> evaluates to 3.</p>
|
||||
|
||||
<h3 class="function"><a name="pretty_print-1">pretty_print/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>pretty_print(Symb::term()) -> string()</tt></p>
|
||||
</div><p>Pretty printing of symbolic terms.
|
||||
A symbolic value like <tt>{call,sets,union,[{call,sets,new,[]},{call,sets,from_list,[[1,2]]}]}</tt>
|
||||
is transformed to the string \"sets:union(sets:new(),from_list([1,2]))\".</p>
|
||||
|
||||
<h3 class="function"><a name="pretty_print-2">pretty_print/2</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>pretty_print(Env::<a href="#type-proplist">proplist()</a>, Symb::term()) -> string()</tt></p>
|
||||
</div><p>Pretty printing of symbolic terms within given environment.
|
||||
Like <a href="#pretty_print-1"><code>pretty_print/1</code></a>, but also replaces symbolic variables, that is,
|
||||
terms of the form <tt>{var,V}</tt>, by their corresponding values in the
|
||||
property list. This should be a list of pairs of atoms and values. For example,
|
||||
<tt>eval([{x,3}],{var,x})</tt> is pretty printed to \"3\".</p>
|
||||
|
||||
<h3 class="function"><a name="well_defined-1">well_defined/1</a></h3>
|
||||
<div class="spec">
|
||||
<p><tt>well_defined(G::<a href="#type-gen">gen(A)</a>) -> A</tt></p>
|
||||
</div><p>Generates a well defined symbolic value.
|
||||
A value is well defined if evaluating it does not raise an exception.</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, Jun 13 2010, 13:15:30.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
BIN
lib/eqc/doc/erlang.png
Normal file
BIN
lib/eqc/doc/erlang.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.1 KiB |
17
lib/eqc/doc/index.html
Normal file
17
lib/eqc/doc/index.html
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Overview</title>
|
||||
</head>
|
||||
<frameset cols="20%,80%">
|
||||
<frame src="modules-frame.html" name="modulesFrame" title="">
|
||||
|
||||
<frame src="overview-summary.html" name="overviewFrame" title="">
|
||||
<noframes>
|
||||
<h2>This page uses frames</h2>
|
||||
<p>Your browser does not accept frames.
|
||||
<br>You should go to the <a href="overview-summary.html">non-frame version</a> instead.
|
||||
</p>
|
||||
</noframes>
|
||||
</frameset>
|
||||
</html>
|
||||
14
lib/eqc/doc/modules-frame.html
Normal file
14
lib/eqc/doc/modules-frame.html
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Overview</title>
|
||||
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
|
||||
</head>
|
||||
<body bgcolor="white">
|
||||
<h2 class="indextitle">Modules</h2>
|
||||
<table width="100%" border="0" summary="list of modules">
|
||||
<tr><td><a href="eqc.html" target="overviewFrame" class="module">eqc</a></td></tr>
|
||||
<tr><td><a href="eqc_gen.html" target="overviewFrame" class="module">eqc_gen</a></td></tr>
|
||||
<tr><td><a href="eqc_symbolic.html" target="overviewFrame" class="module">eqc_symbolic</a></td></tr></table>
|
||||
</body>
|
||||
</html>
|
||||
53
lib/eqc/doc/overview-summary.html
Normal file
53
lib/eqc/doc/overview-summary.html
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>QuickCheck Mini
</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>
|
||||
<h1>QuickCheck Mini
</h1>
|
||||
<p>Copyright © Quviq AB, 2006-2010.
</p>
|
||||
<p><b>Version:</b> 1.0.1
</p>
|
||||
<p>
|
||||
QuickCheck is a specification-based testing tool for Erlang. QuickCheck Mini is
|
||||
a powerful, but restricted version of QuickCheck. It is released free of charge for
|
||||
anyone interested in learning more about QuickCheck as well as for open source
|
||||
developers that want to ship their code with simple QuickCheck properties.</p>
|
||||
|
||||
<p>In order to learn more about QuickCheck, please visit http://www.quviq.com/.
|
||||
There is also a mailing list discussing QuickCheck issues, which you can subscribe to by sending an email to quickcheck-questions@quviq.com with subject "Subscribe".</p>
|
||||
|
||||
|
||||
<h2>QuickCheck</h2>
|
||||
|
||||
Programs
|
||||
are tested by writing <i>properties</i> in the source code, such as
|
||||
<pre>
|
||||
prop_reverse() ->
|
||||
?FORALL(Xs,list(int()),
|
||||
lists:reverse(lists:reverse(Xs)) == Xs).
|
||||
</pre>
|
||||
Properties are tested by calling
|
||||
<pre>
|
||||
eqc:quickcheck(prop_reverse())
|
||||
</pre><p>
|
||||
which generates 100 random test cases and checks that the property
|
||||
returns <tt>true</tt> in every case.</p>
|
||||
|
||||
<p>
|
||||
Functions for writing properties are found in module <a href="eqc.html"><code>eqc</code></a>,
|
||||
while functions for writing test data generators (such as
|
||||
<tt>list(int())</tt> above) are found in module <a href="eqc_gen.html"><code>eqc_gen</code></a>. Parts
|
||||
of the interface are provided via macros, which are defined in
|
||||
<tt>eqc.hrl</tt>--this file should be included in every module which
|
||||
uses QuickCheck. This header file also imports much of the QuickCheck
|
||||
API, so it can be used without explicit module names.
|
||||
</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, Jun 13 2010, 13:15:30.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
39
lib/eqc/doc/overview.edoc
Normal file
39
lib/eqc/doc/overview.edoc
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
@title QuickCheck Mini
|
||||
@version {@version}
|
||||
@copyright Quviq AB, 2006-2010.
|
||||
@doc
|
||||
QuickCheck is a specification-based testing tool for Erlang. QuickCheck Mini is
|
||||
a powerful, but restricted version of QuickCheck. It is released free of charge for
|
||||
anyone interested in learning more about QuickCheck as well as for open source
|
||||
developers that want to ship their code with simple QuickCheck properties.
|
||||
|
||||
In order to learn more about QuickCheck, please visit http://www.quviq.com/.
|
||||
There is also a mailing list discussing QuickCheck issues, which you can subscribe to by sending an email to quickcheck-questions@quviq.com with subject "Subscribe".
|
||||
|
||||
|
||||
<h2>QuickCheck</h2>
|
||||
|
||||
Programs
|
||||
are tested by writing <i>properties</i> in the source code, such as
|
||||
<pre>
|
||||
prop_reverse() ->
|
||||
?FORALL(Xs,list(int()),
|
||||
lists:reverse(lists:reverse(Xs)) == Xs).
|
||||
</pre>
|
||||
Properties are tested by calling
|
||||
<pre>
|
||||
eqc:quickcheck(prop_reverse())
|
||||
</pre>
|
||||
which generates 100 random test cases and checks that the property
|
||||
returns <tt>true</tt> in every case.
|
||||
|
||||
<p>
|
||||
Functions for writing properties are found in module {@link eqc},
|
||||
while functions for writing test data generators (such as
|
||||
<tt>list(int())</tt> above) are found in module {@link eqc_gen}. Parts
|
||||
of the interface are provided via macros, which are defined in
|
||||
<tt>eqc.hrl</tt>--this file should be included in every module which
|
||||
uses QuickCheck. This header file also imports much of the QuickCheck
|
||||
API, so it can be used without explicit module names.
|
||||
</p>
|
||||
|
||||
11
lib/eqc/doc/packages-frame.html
Normal file
11
lib/eqc/doc/packages-frame.html
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Overview</title>
|
||||
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
|
||||
</head>
|
||||
<body bgcolor="white">
|
||||
<h2 class="indextitle">Packages</h2>
|
||||
<table width="100%" border="0" summary="list of packages"></table>
|
||||
</body>
|
||||
</html>
|
||||
55
lib/eqc/doc/stylesheet.css
Normal file
55
lib/eqc/doc/stylesheet.css
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
/* standard EDoc style sheet */
|
||||
body {
|
||||
font-family: Verdana, Arial, Helvetica, sans-serif;
|
||||
margin-left: .25in;
|
||||
margin-right: .2in;
|
||||
margin-top: 0.2in;
|
||||
margin-bottom: 0.2in;
|
||||
color: #000000;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
h1,h2 {
|
||||
margin-left: -0.2in;
|
||||
}
|
||||
div.navbar {
|
||||
background-color: #add8e6;
|
||||
padding: 0.2em;
|
||||
}
|
||||
h2.indextitle {
|
||||
padding: 0.4em;
|
||||
background-color: #add8e6;
|
||||
}
|
||||
h3.function,h3.typedecl {
|
||||
background-color: #add8e6;
|
||||
padding-left: 1em;
|
||||
}
|
||||
div.spec {
|
||||
margin-left: 2em;
|
||||
background-color: #eeeeee;
|
||||
}
|
||||
a.module,a.package {
|
||||
text-decoration:none
|
||||
}
|
||||
a.module:hover,a.package:hover {
|
||||
background-color: #eeeeee;
|
||||
}
|
||||
ul.definitions {
|
||||
list-style-type: none;
|
||||
}
|
||||
ul.index {
|
||||
list-style-type: none;
|
||||
background-color: #eeeeee;
|
||||
}
|
||||
|
||||
/*
|
||||
* Minor style tweaks
|
||||
*/
|
||||
ul {
|
||||
list-style-type: square;
|
||||
}
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
}
|
||||
td {
|
||||
padding: 3
|
||||
}
|
||||
Reference in a new issue