net.jqwik.api

Interface Arbitrary<T>

Type Parameters:

T - The type of generated objects. Primitive objects (e.g. int, boolean etc.) are represented by their boxed type (e.g. Integer, Boolean).

All Known Subinterfaces:

ActionSequenceArbitrary<M>, BigDecimalArbitrary, BigIntegerArbitrary, ByteArbitrary, CharacterArbitrary, DoubleArbitrary, FloatArbitrary, FunctionArbitrary<F,R>, IntegerArbitrary, LongArbitrary, ShortArbitrary, SizableArbitrary<U>, StreamableArbitrary<T,U>, StringArbitrary, TypeArbitrary<T>

@API(status=STABLE,
     since="1.0")
public interface Arbitrary<T>

The main interface for representing objects that can be generated and shrunk.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Arbitrary.ArbitraryFacade

Method Summary

Modifier and Type	Method and Description
default java.util.Optional<java.util.stream.Stream<T>>	allValues() Create optional stream of all possible values this arbitrary could generate.
default <A> StreamableArbitrary<T,A>	array(java.lang.Class<A> arrayClass) Create a new arbitrary of type T[] using the existing arbitrary for generating the elements of the array.
default Arbitrary<java.util.List<T>>	collect(java.util.function.Predicate<java.util.List<T>> until) Create a new arbitrary of type List<T> by adding elements of type T until condition until is fulfilled.
default java.util.Optional<ExhaustiveGenerator<T>>	exhaustive() Create the exhaustive generator for an arbitrary using the maximum allowed number of generated samples.
default java.util.Optional<ExhaustiveGenerator<T>>	exhaustive(long maxNumberOfSamples) Create the exhaustive generator for an arbitrary.
default Arbitrary<T>	filter(java.util.function.Predicate<T> filterPredicate) Create a new arbitrary of the same type T that creates and shrinks the original arbitrary but only allows values that are accepted by the filterPredicate.
default Arbitrary<T>	fixGenSize(int genSize) Fix the genSize of an arbitrary so that it can no longer be influenced from outside
default <U> Arbitrary<U>	flatMap(java.util.function.Function<T,Arbitrary<U>> mapper) Create a new arbitrary of type U that uses the values of the existing arbitrary to create a new arbitrary using the mapper function.
default void	forEachValue(java.util.function.Consumer<? super T> action) Iterate through each value this arbitrary can generate if - and only if - exhaustive generation is possible.
RandomGenerator<T>	generator(int genSize) Create the random generator for an arbitrary
default Arbitrary<T>	injectNull(double nullProbability) Create a new arbitrary of the same type but inject null values with a probability of nullProbability.
default StreamableArbitrary<T,java.util.Iterator<T>>	iterator() Create a new arbitrary of type Iterable<T> using the existing arbitrary for generating the elements of the stream.
default StreamableArbitrary<T,java.util.List<T>>	list() Create a new arbitrary of type List<T> using the existing arbitrary for generating the elements of the list.
default <U> Arbitrary<U>	map(java.util.function.Function<T,U> mapper) Create a new arbitrary of type U that maps the values of the original arbitrary using the mapper function.
default Arbitrary<java.util.Optional<T>>	optional() Create a new arbitrary of type Optional<T> using the existing arbitrary for generating the elements of the stream.
default T	sample() Generate a single sample value using this arbitrary.
default java.util.stream.Stream<T>	sampleStream() Generate a stream of sample values using this arbitrary.
default StreamableArbitrary<T,java.util.Set<T>>	set() Create a new arbitrary of type Set<T> using the existing arbitrary for generating the elements of the set.
default StreamableArbitrary<T,java.util.stream.Stream<T>>	stream() Create a new arbitrary of type Stream<T> using the existing arbitrary for generating the elements of the stream.
default Arbitrary<T>	unique() Create a new arbitrary of the same type T that creates and shrinks the original arbitrary but will never generate the same value twice.
default Arbitrary<T>	withSamples(T... samples) Deprecated. Use something like Arbitraries.oneOf(myArbitrary, Arbitraries.of(samples)).

Method Detail

generator

RandomGenerator<T> generator(int genSize)

Create the random generator for an arbitrary

Parameters:

genSize - a very unspecific configuration parameter that can be used to influence the configuration and behaviour of a random generator if and only if the generator wants to be influenced. Many generators are independent of genSize. The default value of genSize is the number of tries configured for a property. Use fixGenSize(int) to fix the parameter for a given arbitrary.

Returns:

a new random generator instance

exhaustive

default java.util.Optional<ExhaustiveGenerator<T>> exhaustive()

Create the exhaustive generator for an arbitrary using the maximum allowed number of generated samples. Just trying to find out if such a generator exists might take a long time. This method should never be overridden.

Returns:

a new exhaustive generator or Optional.empty() if it cannot be created.

exhaustive

@API(status=MAINTAINED,
     since="1.2.1")
default java.util.Optional<ExhaustiveGenerator<T>> exhaustive(long maxNumberOfSamples)

Create the exhaustive generator for an arbitrary. Depending on maxNumberOfSamples this can take a long time. This method must be overridden in all arbitraries that support exhaustive generation.

Parameters:

maxNumberOfSamples - The maximum number of samples considered. If during generation it becomes clear that this number will be exceeded generation stops.

Returns:

a new exhaustive generator or Optional.empty() if it cannot be created.

allValues

default java.util.Optional<java.util.stream.Stream<T>> allValues()

Create optional stream of all possible values this arbitrary could generate. This is only possible if the arbitrary is available for exhaustive generation.

Returns:

optional stream of all possible values

forEachValue

@API(status=MAINTAINED,
     since="1.1.2")
default void forEachValue(java.util.function.Consumer<? super T> action)

Iterate through each value this arbitrary can generate if - and only if - exhaustive generation is possible. This method can be used for example to make assertions about a set of values described by an arbitrary.

Parameters:

action - the consumer function to be invoked for each value

Throws:

java.lang.AssertionError - if exhaustive generation is not possible

filter

default Arbitrary<T> filter(java.util.function.Predicate<T> filterPredicate)

Create a new arbitrary of the same type T that creates and shrinks the original arbitrary but only allows values that are accepted by the filterPredicate.

Throws:

JqwikException - if filtering will fail to come up with a value after 10000 tries

map

default <U> Arbitrary<U> map(java.util.function.Function<T,U> mapper)

Create a new arbitrary of type U that maps the values of the original arbitrary using the mapper function.

flatMap

default <U> Arbitrary<U> flatMap(java.util.function.Function<T,Arbitrary<U>> mapper)

Create a new arbitrary of type U that uses the values of the existing arbitrary to create a new arbitrary using the mapper function.

injectNull

default Arbitrary<T> injectNull(double nullProbability)

Create a new arbitrary of the same type but inject null values with a probability of nullProbability.

unique

default Arbitrary<T> unique()

Create a new arbitrary of the same type T that creates and shrinks the original arbitrary but will never generate the same value twice.

Throws:

JqwikException - if filtering will fail to come up with a value after 10000 tries

withSamples

@Deprecated
 @API(status=DEPRECATED,
     since="1.2.2")
default Arbitrary<T> withSamples(T... samples)

Deprecated. Use something like Arbitraries.oneOf(myArbitrary, Arbitraries.of(samples)).

Create a new arbitrary of the same type but inject values in samples first before continuing with standard value generation.

fixGenSize

@API(status=MAINTAINED,
     since="1.2.0")
default Arbitrary<T> fixGenSize(int genSize)

Fix the genSize of an arbitrary so that it can no longer be influenced from outside

list

default StreamableArbitrary<T,java.util.List<T>> list()

Create a new arbitrary of type List<T> using the existing arbitrary for generating the elements of the list.

set

default StreamableArbitrary<T,java.util.Set<T>> set()

Create a new arbitrary of type Set<T> using the existing arbitrary for generating the elements of the set.

stream

default StreamableArbitrary<T,java.util.stream.Stream<T>> stream()

Create a new arbitrary of type Stream<T> using the existing arbitrary for generating the elements of the stream.

iterator

default StreamableArbitrary<T,java.util.Iterator<T>> iterator()

Create a new arbitrary of type Iterable<T> using the existing arbitrary for generating the elements of the stream.

array

default <A> StreamableArbitrary<T,A> array(java.lang.Class<A> arrayClass)

Create a new arbitrary of type T[] using the existing arbitrary for generating the elements of the array.

Parameters:

arrayClass - The arrays class to create, e.g. String[].class. This is required due to limitations in Java's reflection capabilities.

optional

default Arbitrary<java.util.Optional<T>> optional()

Create a new arbitrary of type Optional<T> using the existing arbitrary for generating the elements of the stream. The new arbitrary also generates Optional.empty() values with a probability of 0.05 (i.e. 1 in 20).

collect

@API(status=EXPERIMENTAL,
     since="1.1.4")
default Arbitrary<java.util.List<T>> collect(java.util.function.Predicate<java.util.List<T>> until)

Create a new arbitrary of type List<T> by adding elements of type T until condition until is fulfilled.

sampleStream

@API(status=EXPERIMENTAL,
     since="1.2.2")
default java.util.stream.Stream<T> sampleStream()

Generate a stream of sample values using this arbitrary.

Using this method within a property does not break reproducibility of results, i.e. rerunning it with same seed will also generate the same values.

sample

@API(status=EXPERIMENTAL,
     since="1.2.2")
default T sample()

Generate a single sample value using this arbitrary.

Using this method within a property does not break reproducibility of results, i.e. rerunning it with same seed will also generate the same value.