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, IteratorArbitrary<T>, ListArbitrary<T>, LongArbitrary, MapArbitrary<K,V>, NumericalArbitrary<T,A>, SetArbitrary<T>, ShortArbitrary, SizableArbitrary<U>, StreamableArbitrary<T,U>, StreamArbitrary<T>, 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.lang.Object>	asGeneric() Sometimes simplifies test writing
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 Arbitrary<T>	dontShrink() Create a new arbitrary of type T that will use the underlying arbitrary to create the tuple values but will return unshrinkable values.
EdgeCases<T>	edgeCases()
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>	ignoreException(java.lang.Class<? extends java.lang.Throwable> exceptionType) Create a new arbitrary of type T that will use the underlying arbitrary to create the tuple values but will ignore any raised exception of type exceptionType during generation.
default Arbitrary<T>	injectDuplicates(double duplicateProbability) Create a new arbitrary of type Iterable<T> that will inject duplicates of previously generated values with a probability of duplicateProbability.
default Arbitrary<T>	injectNull(double nullProbability) Create a new arbitrary of the same type but inject null values with a probability of nullProbability.
default boolean	isUnique() All arbitraries whose base generator is supposed to produce no duplicates should return true.
default IteratorArbitrary<T>	iterator() Create a new arbitrary of type Iterable<T> using the existing arbitrary for generating the elements of the stream.
default ListArbitrary<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 SetArbitrary<T>	set() Create a new arbitrary of type Set<T> using the existing arbitrary for generating the elements of the set.
default StreamArbitrary<T>	stream() Create a new arbitrary of type Stream<T> using the existing arbitrary for generating the elements of the stream.
default Arbitrary<Tuple.Tuple1<T>>	tuple1() Create a new arbitrary of type Tuple.Tuple1<T> that will use the underlying arbitrary to create the tuple value;
default Arbitrary<Tuple.Tuple2<T,T>>	tuple2() Create a new arbitrary of type Tuple.Tuple2<T, T> that will use the underlying arbitrary to create the tuple values;
default Arbitrary<Tuple.Tuple3<T,T,T>>	tuple3() Create a new arbitrary of type Tuple.Tuple3<T, T, T> that will use the underlying arbitrary to create the tuple values;
default Arbitrary<Tuple.Tuple4<T,T,T,T>>	tuple4() Create a new arbitrary of type Tuple.Tuple4<T, T, T, T> that will use the underlying arbitrary to create the tuple values;
default Arbitrary<Tuple.Tuple5<T,T,T,T,T>>	tuple5() Create a new arbitrary of type Tuple.Tuple5<T, T, T, T, T> that will use the underlying arbitrary to create the tuple values;
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.

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

asGeneric

@API(status=INTERNAL)
default Arbitrary<java.lang.Object> asGeneric()

Sometimes simplifies test writing

Returns:

The same instance but with type Arbitrary<Object>

isUnique

@API(status=INTERNAL)
default boolean isUnique()

All arbitraries whose base generator is supposed to produce no duplicates should return true.

Returns:

true if base genator is supposed to produce no duplicates

exhaustive

@API(status=INTERNAL)
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=INTERNAL)
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.

edgeCases

@API(status=EXPERIMENTAL,
     since="1.3.0")
EdgeCases<T> edgeCases()

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.

Returns:

a new arbitrary instance

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.

Returns:

a new arbitrary instance

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.

Returns:

a new arbitrary instance

injectNull

default Arbitrary<T> injectNull(double nullProbability)

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

Returns:

a new arbitrary instance

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.

Uniqueness is only held up for a single use of this arbitrary. If the same arbitrary instance is used in several places, e.g. for creating several lists, the different lists may share values between them.

Returns:

a new arbitrary instance

Throws:

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

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

Returns:

a new arbitrary instance

list

default ListArbitrary<T> list()

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

set

default SetArbitrary<T> set()

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

Returns:

a new arbitrary instance

stream

default StreamArbitrary<T> stream()

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

Returns:

a new arbitrary instance

iterator

default IteratorArbitrary<T> iterator()

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

Returns:

a new arbitrary instance

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.

Returns:

a new arbitrary instance

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).

Returns:

a new arbitrary instance

collect

@API(status=MAINTAINED,
     since="1.3.0")
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.

Returns:

a new arbitrary instance

sampleStream

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

Generate a stream of sample values using this arbitrary. This can be useful for

• Testing arbitraries
• Playing around with arbitraries in jshell
• Using arbitraries independently from jqwik, e.g. to feed test data builders

The underlying generator is created with size 1000. Outside a property a new instance of Random will be created to feed the generator.

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.

Returns:

a stream of newly generated values

sample

@API(status=MAINTAINED,
     since="1.3.0")
default T sample()

Generate a single sample value using this arbitrary. This can be useful for

• Testing arbitraries
• Playing around with arbitraries in jshell
• Using arbitraries independently from jqwik, e.g. to feed test data builders

Some additional things to be aware of:

• If you feel the need to use this method for real generation, e.g. in a provider method you are most probably doing it wrong. You might want to use flatMap(Function).
• The underlying generator is created with size 1000. Outside a property a new instance of Random will be created to feed the generator.
• 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.

Returns:

a newly generated value

injectDuplicates

@API(status=MAINTAINED,
     since="1.3.0")
default Arbitrary<T> injectDuplicates(double duplicateProbability)

Create a new arbitrary of type Iterable<T> that will inject duplicates of previously generated values with a probability of duplicateProbability.

Shrinking behavior for duplicate values -- if duplication is required for falsification -- is poor, i.e. those duplicate values cannot be shrunk to "smaller" duplicate values.

Parameters:

duplicateProbability - The probability with which a previous value will be generated

Returns:

a new arbitrary instance

tuple1

@API(status=MAINTAINED,
     since="1.3.0")
default Arbitrary<Tuple.Tuple1<T>> tuple1()

Create a new arbitrary of type Tuple.Tuple1<T> that will use the underlying arbitrary to create the tuple value;

Returns:

a new arbitrary instance

tuple2

@API(status=MAINTAINED,
     since="1.3.0")
default Arbitrary<Tuple.Tuple2<T,T>> tuple2()

Create a new arbitrary of type Tuple.Tuple2<T, T> that will use the underlying arbitrary to create the tuple values;

Returns:

a new arbitrary instance

tuple3

@API(status=MAINTAINED,
     since="1.3.0")
default Arbitrary<Tuple.Tuple3<T,T,T>> tuple3()

Create a new arbitrary of type Tuple.Tuple3<T, T, T> that will use the underlying arbitrary to create the tuple values;

Returns:

a new arbitrary instance

tuple4

@API(status=MAINTAINED,
     since="1.3.0")
default Arbitrary<Tuple.Tuple4<T,T,T,T>> tuple4()

Create a new arbitrary of type Tuple.Tuple4<T, T, T, T> that will use the underlying arbitrary to create the tuple values;

Returns:

a new arbitrary instance

tuple5

@API(status=MAINTAINED,
     since="1.3.3")
default Arbitrary<Tuple.Tuple5<T,T,T,T,T>> tuple5()

Create a new arbitrary of type Tuple.Tuple5<T, T, T, T, T> that will use the underlying arbitrary to create the tuple values;

Returns:

a new arbitrary instance

ignoreException

@API(status=EXPERIMENTAL,
     since="1.3.1")
default Arbitrary<T> ignoreException(java.lang.Class<? extends java.lang.Throwable> exceptionType)

Create a new arbitrary of type T that will use the underlying arbitrary to create the tuple values but will ignore any raised exception of type exceptionType during generation.

Parameters:

exceptionType - The exception type to ignore

Returns:

a new arbitrary instance

dontShrink

@API(status=EXPERIMENTAL,
     since="1.3.2")
default Arbitrary<T> dontShrink()

Create a new arbitrary of type T that will use the underlying arbitrary to create the tuple values but will return unshrinkable values. This might be necessary if values are being mutated during a property run and the mutated state would make a shrunk value invalid.

This is a hack to get around a weakness in jqwik's shrinking mechanism

Returns:

a new arbitrary instance