PropCheck - Property Testing v1.2.2 PropCheck.BasicTypes View Source

This modules contains all basic type generators from PropEr. It is automatically available by use PropCheck.

Acknowledgments

The functions defined here are delegated to the corresponding definition proper_types. Also most of the documentation is copied over from there.

Link to this section Summary

Types

Floats extend by infinity

Integers extend by infinity

Non negative integers extend by infinity

The internal representation of a basic type in PropEr

The internal representation of a type in PropEr

Functions

All Elixir terms (that PropEr can produce).

Arity is a byte value, i.e. integer(0, 255)

All atoms.

All binaries.

All binaries with a byte size of length.

All bitstrings.

All bitstrings with a bit size of length.

bool is equivalent to boolean

The atoms true and false. Instances shrink towards false.

Byte values, i.e. integer(0, 255)

Char values (16 bit for some reason), i.e. integer(0, 0xffff)

An Erlang string, i.e. list(char)

choose is equivalent to integer(low, high)

Adds a default value, default_value, to type.

elements is equivalent to union([..])

Singleton type consisting only of value.

All lists whose i-th element is an instance of the type at index i of list_of_types. Also written simply as a list of types.

All floats, i.e. float(:inf, :inf)

All floats between low and high, bounds included.

frequency is equivalent to weighted_union([..])

All pure functions that map instances of arg_types to instances of ret_type.

A function with 0 parameters, i.e. function(0, ret_type)

A function with 1 parameter, i.e. function(1, ret_type)

A function with 2 parameters, i.e. function(2, ret_type)

A function with 3 parameters, i.e. function(3, ret_type)

A function with 4 parameters, i.e. function(4, ret_type)

Small integers (bound by the current value of the size parameter).

All integers, i.e. integer(:inf, :inf)

All integers between low and high, bounds included.

Large_int is equivalent to integer

List of any types, i.e. list(any)

All lists containing elements of type elem_type.

Tuples whose elements are all of type elem_type.

A map whose keys are defined by the generator k and values by the generator v.

Small Small non-negative integers (bound by the current value of the size parameter).

Negative integers, i.e. integer(:inf, -1)

This is a predefined constraint that can be applied to random-length list and binary types to ensure that the produced values are never empty.

Non negative floats, i.e. float(0.0, inf)

Non negative integers, i.e. integer(0, :inf)

Creates a new type which is equivalent to type, but whose instances are never shrunk by the shrinking subsystem.

Numbers are integers or floats, i.e. union([integer(), float()])

oneof is equivalent to union([..])

All sorted lists containing elements of type elem_type.

Returns the value associated with parameter, or :undefined in case parameter is not associated with any value.

Returns the value associated with parameter, or default in case parameter is not associated with any value.

Strictly positive integers, i.e. integer(1, :inf)

A range is equivalent to integers

real is equivalent to float

Overrides the size parameter used when generating instances of type with new_size.

return is equivalent to exactly

A type that generates exactly the list list.

Term is a synonym for any

timeout values, i.e. union([non_neg_integer() | :infinity])

Tuples of any types, i.e. loose_tuple(any)

All tuples whose i-th element is an instance of the type at index i of list_of_types.

The union of all types in list_of_types.

utf8-encoded unbounded size binary

utf8-encoded bounded upper size binary.

Bounded upper size utf8 binary, codepoint length =< MaxCodePointSize.

All lists of length length containing elements of type elem_type.

A specialization of union/1, where each type in list_of_types is assigned a frequency.

Associates the atom key parameter with the value value while generating instances of type.

Similar to with_parameter/3, but accepts a list of {parameter, value} pairs.

weighted_union(FreqChoices)

Link to this section Types

Link to this type

ext_float()

View Source
ext_float() :: float() | :inf

Floats extend by infinity

Link to this type

ext_int()

View Source
ext_int() :: integer() | :inf

Integers extend by infinity

Link to this type

ext_non_neg_integer()

View Source
ext_non_neg_integer() :: non_neg_integer() | :inf

Non negative integers extend by infinity

Link to this type

frequency()

View Source
frequency() :: pos_integer()

The internal representation of a basic type in PropEr

The internal representation of a type in PropEr

Link to this section Functions

All Elixir terms (that PropEr can produce).

For reasons of efficiency, functions are never produced as instances of this type.

CAUTION: Instances of this type are expensive to produce, shrink and instance- check, both in terms of processing time and consumed memory. Only use this type if you are certain that you need it.

Arity is a byte value, i.e. integer(0, 255)

All atoms.

All atoms used internally by PropEr start with a :$ , so such atoms will never be produced as instances of this type. You should also refrain from using such atoms in your code, to avoid a potential clash. Instances shrink towards the empty atom, :"".

All binaries.

Instances shrink towards the empty binary, "".

All binaries with a byte size of length.

length must be an Elixir expression that evaluates to a non-negative integer. Instances shrink towards binaries of zeroes.

Link to this function

bitstring()

View Source
bitstring() :: type()

All bitstrings.

Instances shrink towards the empty bitstring, "".

Link to this function

bitstring(length)

View Source
bitstring(non_neg_integer()) :: type()

All bitstrings with a bit size of length.

length must be an Elixir expression that evaluates to a non-negative integer. Instances shrink towards bitstrings of zeroes.

bool is equivalent to boolean

The atoms true and false. Instances shrink towards false.

Byte values, i.e. integer(0, 255)

Char values (16 bit for some reason), i.e. integer(0, 0xffff)

Link to this function

char_list()

View Source
char_list() :: type()

An Erlang string, i.e. list(char)

Link to this function

choose(low, high)

View Source
choose(ext_int(), ext_int()) :: type()

choose is equivalent to integer(low, high)

Link to this function

default(default_value, type)

View Source
default(raw_type(), raw_type()) :: type()

Adds a default value, default_value, to type.

The default serves as a primary shrinking target for instances, while it is also chosen by the random instance generation subsystem half the time.

Link to this function

elements(choices)

View Source
elements([raw_type(), ...]) :: type()

elements is equivalent to union([..])

Link to this function

exactly(value)

View Source
exactly(any()) :: type()

Singleton type consisting only of value.

value must be an evaluated term. Also written simply as value.

Link to this function

fixed_list(list_of_types)

View Source
fixed_list([raw_type()]) :: type()

All lists whose i-th element is an instance of the type at index i of list_of_types. Also written simply as a list of types.

All floats, i.e. float(:inf, :inf)

All floats between low and high, bounds included.

low and high must be Elixir expressions that evaluate to floats, with Low =< high. Additionally, low and high may have the value :inf, in which case they represent minus infinity and plus infinity respectively. Instances shrink towards 0.0 if low =< 0.0 =< high, or towards the bound with the smallest absolute value otherwise.

Link to this function

frequency(freq_choices)

View Source
frequency([{frequency(), raw_type()}, ...]) :: type()

frequency is equivalent to weighted_union([..])

Link to this function

function(arg_types, return_type)

View Source
function([raw_type()] | arity(), raw_type()) :: type()

All pure functions that map instances of arg_types to instances of ret_type.

The syntax function(arity, ret_type) is also acceptable.

Link to this function

function0(ret_type)

View Source
function0(type()) :: type()

A function with 0 parameters, i.e. function(0, ret_type)

Link to this function

function1(ret_type)

View Source
function1(type()) :: type()

A function with 1 parameter, i.e. function(1, ret_type)

Link to this function

function2(ret_type)

View Source
function2(type()) :: type()

A function with 2 parameters, i.e. function(2, ret_type)

Link to this function

function3(ret_type)

View Source
function3(type()) :: type()

A function with 3 parameters, i.e. function(3, ret_type)

Link to this function

function4(ret_type)

View Source
function4(type()) :: type()

A function with 4 parameters, i.e. function(4, ret_type)

Small integers (bound by the current value of the size parameter).

Instances shrink towards 0.

All integers, i.e. integer(:inf, :inf)

Link to this function

integer(low, high)

View Source
integer(ext_int(), ext_int()) :: type()

All integers between low and high, bounds included.

low and high must be Elixir expressions that evaluate to integers, with low =< high. Additionally, low and high may have the value :inf, in which case they represent minus infinity and plus infinity respectively. Instances shrink towards 0 if low =< 0 =< high, or towards the bound with the smallest absolute value otherwise.

Link to this function

large_int()

View Source
large_int() :: type()

Large_int is equivalent to integer

List of any types, i.e. list(any)

All lists containing elements of type elem_type.

Instances shrink towards the empty list, [].

Link to this function

loose_tuple(elem_type)

View Source
loose_tuple(raw_type()) :: type()

Tuples whose elements are all of type elem_type.

Instances shrink towards the 0-size tuple, {}.

A map whose keys are defined by the generator k and values by the generator v.

Small Small non-negative integers (bound by the current value of the size parameter).

Instances shrink towards 0.

Link to this function

neg_integer()

View Source
neg_integer() :: type()

Negative integers, i.e. integer(:inf, -1)

Link to this function

non_empty(list_type)

View Source
non_empty(raw_type()) :: type()

This is a predefined constraint that can be applied to random-length list and binary types to ensure that the produced values are never empty.

Use for e.g. list/0, char_list/0, binary/0

Link to this function

non_neg_float()

View Source
non_neg_float() :: type()

Non negative floats, i.e. float(0.0, inf)

Link to this function

non_neg_integer()

View Source
non_neg_integer() :: type()

Non negative integers, i.e. integer(0, :inf)

Link to this function

noshrink(type)

View Source
noshrink(raw_type()) :: type()

Creates a new type which is equivalent to type, but whose instances are never shrunk by the shrinking subsystem.

Numbers are integers or floats, i.e. union([integer(), float()])

Link to this function

oneof(choices)

View Source
oneof([raw_type(), ...]) :: type()

oneof is equivalent to union([..])

Link to this function

ordered_list(elem_type)

View Source
ordered_list(raw_type()) :: type()

All sorted lists containing elements of type elem_type.

Instances shrink towards the empty list, [].

Link to this function

parameter(parameter)

View Source
parameter(atom()) :: value()

Returns the value associated with parameter, or :undefined in case parameter is not associated with any value.

Association occurs with calling with_parameter/3 or with_parameters/2 before.

Link to this function

parameter(parameter, default)

View Source
parameter(atom(), value()) :: value()

Returns the value associated with parameter, or default in case parameter is not associated with any value.

Association occurs with calling with_parameter/3 or with_parameters/2 before.

Link to this function

pos_integer()

View Source
pos_integer() :: type()

Strictly positive integers, i.e. integer(1, :inf)

Link to this function

range(low, high)

View Source
range(ext_int(), ext_int()) :: type()

A range is equivalent to integers

real is equivalent to float

Link to this function

resize(new_size, raw_type)

View Source
resize(size(), raw_type()) :: type()

Overrides the size parameter used when generating instances of type with new_size.

Has no effect on size-less types, such as unions. Also, this will not affect the generation of any internal types contained in type, such as the elements of a list - those will still be generated using the test-wide value of size. One use of this function is to modify types to produce instances that grow faster or slower, like so:

iex> quickcheck(forall l <- list(integer()) do
...>   length(l) <= 42
...> end)
true

iex> long_list = sized(size, resize(size * 2, list(integer())))
iex> really_long = such_that_maybe l <- long_list, when:
...>      length(l) > 42
iex> quickcheck(forall l <- really_long do
...>   (length(l) <= 84)
...>   |> measure("List length", length l)
...>   |> collect(length l)
...> end)
true

The above specifies a list type that grows twice as fast as normal lists.

return is equivalent to exactly

Link to this function

shrink_list(list)

View Source
shrink_list([any()]) :: type()

A type that generates exactly the list list.

Instances shrink towards shorter sublists of the original list.

Term is a synonym for any

timeout values, i.e. union([non_neg_integer() | :infinity])

Tuples of any types, i.e. loose_tuple(any)

Link to this function

tuple(list_of_types)

View Source
tuple([raw_type()]) :: type()

All tuples whose i-th element is an instance of the type at index i of list_of_types.

Also written simply as a tuple of types.

Link to this function

union(list_of_types)

View Source
union([raw_type(), ...]) :: type()

The union of all types in list_of_types.

list_of_types can't be empty. The random instance generator is equally likely to choose any one of the types in list_of_types. The shrinking subsystem will always try to shrink an instance of a type union to an instance of the first type in list_of_types, thus you should write the simplest case first.

utf8-encoded unbounded size binary

utf8-encoded bounded upper size binary.

Link to this function

utf8(n, max_codepoint_size)

View Source
utf8(ext_non_neg_integer(), 1..4) :: type()

Bounded upper size utf8 binary, codepoint length =< MaxCodePointSize.

Limiting codepoint size can be useful when applications do not accept full unicode range. For example, MySQL in utf8 encoding accepts only 3-byte unicode codepoints in VARCHAR fields.

If unbounded length is needed, use :inf as first argument.

Link to this function

vector(length, elem_type)

View Source
vector(non_neg_integer(), raw_type()) :: type()

All lists of length length containing elements of type elem_type.

length must be an Elixir expression that evaluates to a non-negative integer.

Link to this function

weighted_default(default, type)

View Source
weighted_default({frequency(), raw_type()}, {frequency(), raw_type()}) :: type()

A specialization of default/2.

Parameters default and type are assigned weights to be considered by the random instance generator. The shrinking subsystem will ignore the weights and try to shrink using the default value.

Link to this function

weighted_union(list_of_types)

View Source
weighted_union([{frequency(), raw_type()}, ...]) :: type()

A specialization of union/1, where each type in list_of_types is assigned a frequency.

Frequencies must be Elixir expressions that evaluate to positive integers. Types with larger frequencies are more likely to be chosen by the random instance generator. The shrinking subsystem will ignore the frequencies and try to shrink towards the first type in the list.

Link to this function

with_parameter(parameter, value, type)

View Source
with_parameter(atom(), value(), raw_type()) :: type()

Associates the atom key parameter with the value value while generating instances of type.

Link to this function

with_parameters(pv_list, type)

View Source
with_parameters([{atom(), value()}], raw_type()) :: type()

Similar to with_parameter/3, but accepts a list of {parameter, value} pairs.

Link to this function

wunion(freq_choices)

View Source
wunion([{frequency(), raw_type()}, ...]) :: type()

weighted_union(FreqChoices)