Overview

Module eqc_gen

• Description
• Data Types
• Function Index
• Function Details

Copyright © Quviq AB, 2004-2023

Version: 1.46.3

Description

• A set of values that can be generated,
• A probability distribution on that set,
• A way of shrinking generated values to similar, smaller values---used after a test fails, to enable QuickCheck to search for a similar, but simpler failing case.

 {int(), bool()} 

Many of the functions in this module are usually used via macros, defined in eqc.hrl. These macros are listed here.

?LET(Pat, G1, G2)

The result is shrunk by first shrinking the value generated by G1 while the test still fails, then shrinking the value generated by G2. It is thus better to write ?LET({X, Y}, {G1, G2}, G3) than ?LET(X, G1, ?LET(Y, G2, G3)) (provided G2 does not depend on X), since in the first case shrinking can shrink G1 a bit, shrink G2, then shrink G1 some more, while in the second case G1 cannot be shrunk further once shrinking G2 has begun.

?SIZED(Size, G)

?SUCHTHAT(X, G, P)

?SUCHTHAT(Xs, list(int()), lists:sort(Xs)==Xs)

?SUCHTHATMAYBE(X, G, P)

?SHRINK(G, Gs)

?LETSHRINK(Pat, G1, G2)

 ?LETSHRINK([L, R], [tree(), tree()], {branch, L, R})

?LAZY(G)

Data Types

box()

abstract datatype: box(A)

gen()

abstract datatype: gen(A)

suspension()

abstract datatype: suspension(A)

Function Index

Function Details

binary/0

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.

binary/1

Generates a binary of a given size in bytes. When shrinking, the size is unchanged, but content shrinks like binary/0.

bitstring/0

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.

bitstring/1

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 bitstring/0.

bool/0

Generates a random boolean. Shrinks to false.

char/0

Generates a random character. Shrinks to a, b or c.

choose/2

Generates a number in the range M to N. The result shrinks towards smaller absolute values.

constrain_shrinking/2

Constrain the shrinking behaviour of a generator to only consider shrinking step satisfying the given relation. For instance, constrain_shrinking(fun erlang:'<'/2, G) constrains the shrinking of G to strictly decreasing values.

default/2

Adds a default value to a generator, to be chosen half the time. Any other value shrinks to the default.

elements/1

Generates an element of the list argument. Shrinking chooses an earlier element.

fault/2

Adds a fault - generation alternative to a generator. The probability of using the faulty alternative is controlled by fault_rate/3, more_faulty/2, and less_faulty/2. If no fault rate is specified, then the faulty alternative is never used. Shrinking attempts to replace a faulty value by a freshly generated non - faulty one.

fault_rate/3

Specifies that faulty data should be generated by any uses of fault/2 within G on M out of N occasions. M must be between zero and N.

frequency/1

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 numbers and sum to a positive value. A generator with a weight of zero will not be chosen.

function0/1

Generates a function of no arguments with result generated by G.

function1/1

Generates a function of one argument with result generated by G. The generated function is pure--will always return the same result for the same argument-- and the result depends randomly on the argument.

function2/1

Generates a function of two arguments with result generated by G. See function1/1.

function3/1

Generates a function of three arguments with result generated by G. See function1/1.

function4/1

Generates a function of four arguments with result generated by G. See function1/1.

growingelements/1

Generates an element of the list argument. In the early tests, when the size parameter is small, then only early elements of the list are chosen. For larger test sizes, all of the elements become candidates for generation. Thus, if several elements are chosen, then there is a high probability of choosing the same element twice during the early tests.

int/0

Generates a small integer (with absolute value bounded by the generation size).

largebinary/0

Equivalent to largebinary({limit, 255, 65535}).

largebinary/1

largebinary(X) is equivalent to largebinary({fixed, X}, []),
largebinary({fixed, X}) is equivalent to largebinary({fixed, X}, []), and
largebinary({limit, X, Y}) is equivalent to largebinary({limit, X, Y}).

largebinary/2

A generator for large binaries. As a rule of thumb, large means > 128 bytes. The problem with the standard generator (binary/0/binary/1) is twofold, the number of shrinking alternatives quickly grow unfeasably large, and the generation is memory consuming.

This generator sacrifices precision for performance. Generation is more efficient, and it shrinks faster although less precisely.

• a fixed size binary - {fixed, NrBytes},
• a binary within a size interval - {limit, Lower, Upper}

• {size, true/false} - shrink the size of the binary (default: false for fixed size binary, true otherwise)
• {value, true/false} - shrink (chunk of) bytes to zero (0) (default: true for fixed size binary, false otherwise)
• {chunks, NrChunks} - The number of chunks to split the binary into, each chunk is considered while shrinking (default: 32 - Note: Chunks should be a power of 2.)

largeint/0

Generates an integer from a large range.

less_faulty/2

Decreases the fault rate within G by a factor M.

list/1

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.

list/2

Generates a list of elements generated by its argument, of length at most MaxLen. Shrinking drops elements from the list.

map/2

Generates a map with keys generated by K and values generated by V.

more_faulty/2

Increases the fault rate within G by a factor M.

nat/0

Generates a small natural number (bounded by the generation size).

no_faults/1

Sets the fault rate to zero within its argument, disabling fault generation. Note that a nested call of fault_rate/3 within the argument of no_faults/1 can set the fault rate to be locally non - zero again, so that faults may still be generated. It is best to avoid calling fault_rate/3 within an argument to no_fault/1 or another call of fault_rate/3.

non_empty/1

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 non_empty(list(int())).

noshrink/1

Generates the same values as G, but these values are never shrunk. Can also be applied to properties.

oneof/1

Generates a value using a randomly chosen element of the list of generators.

open/1

Opens a box created by seal/1. Open can also be applied to any structure containing boxes, when it opens them all. Boxes inside boxes are not opened, however, and neither are boxes "inside generators". Thus

open(seal(Gen))

?LET(Box, seal(Gen), open(Box))

orderedlist/1

Generates an ordered list of elements generated by G.

parameter/1

Generates the value of generator parameter P, or fails if P is unbound.

parameter/2

Generates the value of generator parameter P, or Default if P is unbound.

peek/1

Returns the value contained in a sealed box, before any shrinking. Can also be applied to a structure containing sealed boxes.

prop_shrinks_without_duplicates/1

This property holds if the generator G never produces duplicate values during shrinking (except perhaps in the last failing test). Such generators lead to faster shrinking when tests fail, because no duplicate tests are run. This property can be used to test user - defined shrinking strategies.

real/0

Generates a real number.

resize/2

Binds the generation size parameter to Size within G. Size should never be negative.

return/1

Constructs a generator that always generates the value X. Most values can also be used as generators for themselves, making return unnecessary, but return(X) may be more efficient than using X as a generator, since when return(X) is used then QuickCheck does not traverse X searching for values to be intepreted specially.

sample/1

Prints 11 values randomly generated by G, for sizes ranging from 10 to 20.

sampleshrink/1

Prints a value generated by G, followed by one way of shrinking it. Each following line displays a list of values that the first value on the previous line can be shrunk to in one step. Thus the output traces the leftmost path through the shrinking tree.

seal/1

"Seals" G, by generating a sealed box that, every time it is opened, generates the same value, chosen from those generated by G. The box contains not only the value, but all the possible ways of shrinking it. Each time the box is opened, its value can be shrunk independently--thus there is no reason to expect that, after shrinking, all openings of a box will result in the same value.

The purpose of seal is to control the search order during shrinking, since the alternative values are explored at the point the box is opened, not at the point it is created.

shrink_genlist/1

Given a list of generators Gs, builds a generator that shrinks to a sublist of elements generated from Gs. The shrinking will alternate between dropping elements from the list and shrinking the elements.

shrink_int/3

Generates the value X, and shrinks it within the range M to N. The shrinking strategy used is the same one used by built - in QuickCheck generators.

shrink_list/1

Generates L, and shrinks to any sublist of L.

shrink_without_duplicates/1

Removes duplicate values from the shrinking search. The result is a generator equivalent to G, in that it generates the same values, and explores the same possibilities during shrinking, leading to the same final result. However, shrink_without_duplicates(G) generates each value at most once during the shrinking search, except possibly for the last failing value, which is repeated if necessary to ensure that shrinking stops at the same value. To do so, it shrinks in the same way as G, but collects a set of all values encountered, testing each new value for membership. This is quite expensive, so shrink_without_duplicates should only be used when it is difficult to avoid duplicates by other means. See prop_shrinks_without_duplicates/1.

shuffle/1

Shuffles a list and shrinks to the unshuffled list.

sublist/1

Generate a random sublist of the given list. Generates short sublists when the size parameter is small, and ramps up to an even distribution of sublist lengths as the size parameter increases. Shrinks to shorter sublists containing elements from earlier in the list.

suspend/1

Creates a suspended generator. A suspension works just like a box created by seal/1, except you cannot peek/1 at the value. The advantage is that the generator is not evaluated until the suspension is opened.

timeout/2

timeout(T, G) generates using G, but with a timeout of T (in milliseconds). Values generated in this way do not shrink on a test failure.

utf8/0

Generates a random utf8 binary.

utf8/1

Generates a random utf8 binary with N unicode characters.

vector/2

Generates a list of the given length, with elements generated by G.

weighted_default/2

Adds a default value to a generator, where both the default and the generator carry weights. Any other value shrinks to the default.

with_parameter/3

Binds the parameter P to the value V within generator G.

with_parameters/2

Binds all the parameters to the values given within the generator G. For example, with_parameters([{id, 247}], G) is equivalent to with_parameter(id, 247, G).

Overview

Generated by EDoc