342 lines
20 KiB
HTML
342 lines
20 KiB
HTML
<!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>
|