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:

ActionChainArbitrary<S>, ActionSequenceArbitrary<M>, ArrayArbitrary<T,A>, BigDecimalArbitrary, BigIntegerArbitrary, ByteArbitrary, CalendarArbitrary, ChainArbitrary<T>, CharacterArbitrary, DateArbitrary, DoubleArbitrary, DurationArbitrary, EmailArbitrary, FloatArbitrary, FunctionArbitrary<F,R>, InstantArbitrary, IntegerArbitrary, IteratorArbitrary<T>, ListArbitrary<T>, LocalDateArbitrary, LocalDateTimeArbitrary, LocalTimeArbitrary, LongArbitrary, MapArbitrary<K,V>, MonthDayArbitrary, NumericalArbitrary<T,A>, OffsetDateTimeArbitrary, OffsetTimeArbitrary, PeriodArbitrary, SetArbitrary<T>, ShortArbitrary, SizableArbitrary<U>, StreamableArbitrary<T,U>, StreamArbitrary<T>, StringArbitrary, TraverseArbitrary<T>, TypeArbitrary<T>, YearArbitrary, YearMonthArbitrary, ZonedDateTimeArbitrary, ZoneOffsetArbitrary

All Known Implementing Classes:

ArbitraryDecorator

@API(status=STABLE,
     since="1.0")
 @CheckReturnValue
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> ArrayArbitrary<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()
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.
default EdgeCases<T>	edgeCases() Return an arbitrary's edge cases up to a limit of 1000.
default Arbitrary<T>	edgeCases(java.util.function.Consumer<EdgeCases.Config<T>> configurator) Experimental interface to change generated edge cases of a specific arbitrary.
EdgeCases<T>	edgeCases(int maxEdgeCases)
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(int maxMisses, 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>	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 RandomGenerator<T>	generator(int genSize, boolean withEdgeCases) Create the random generator for an arbitrary with or without edge cases.
default RandomGenerator<T>	generatorWithEmbeddedEdgeCases(int genSize) Create the random generator for an arbitrary where the embedded generators, if there are any, also generate edge cases.
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>	ignoreException(int maxThrows, 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>	ignoreExceptions(java.lang.Class<? extends java.lang.Throwable>... exceptionTypes) Create a new arbitrary of type T that will use the underlying arbitrary to create the tuple values but will ignore any raised exception in exceptionTypes during generation.
default Arbitrary<T>	ignoreExceptions(int maxThrows, java.lang.Class<? extends java.lang.Throwable>... exceptionTypes) Create a new arbitrary of type T that will use the underlying arbitrary to create the tuple values but will ignore any raised exception in exceptionTypes 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	isGeneratorMemoizable()
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 Arbitrary<java.util.Optional<T>>	optional(double presenceProbability) 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>	withoutEdgeCases() Create a new arbitrary of type T that will not explicitly generate any edge cases, neither directly or in embedded arbitraries.

Method Detail

generator

RandomGenerator<T> generator(int genSize)

Create the random generator for an arbitrary.

Starting with version 1.4.0 the returned generator should no longer include edge cases explicitly since those will be injected in generator(int, boolean)

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

generator

@API(status=INTERNAL,
     since="1.4.0")
default RandomGenerator<T> generator(int genSize,
                                                                               boolean withEdgeCases)

Create the random generator for an arbitrary with or without edge cases.

Never override this method. Override generator(int) instead.

Parameters:

genSize - See generator(int) about meaning of this parameter

withEdgeCases - True if edge cases should be injected into the stream of generated values

Returns:

a new random generator instance

generatorWithEmbeddedEdgeCases

@API(status=INTERNAL,
     since="1.4.0")
default RandomGenerator<T> generatorWithEmbeddedEdgeCases(int genSize)

Create the random generator for an arbitrary where the embedded generators, if there are any, also generate edge cases.

Override only if there are any embedded arbitraries / generators, e.g. a container using an element generator

Parameters:

genSize - See generator(int) about meaning of this parameter

Returns:

a new random generator instance

asGeneric

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

Returns:

The same instance but with type Arbitrary<Object>

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.

isGeneratorMemoizable

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

edgeCases

EdgeCases<T> edgeCases(int maxEdgeCases)

edgeCases

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

Return an arbitrary's edge cases up to a limit of 1000.

Never override. Override edgeCases(int) instead.

Returns:

an instance of type 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.

Parameters:

filterPredicate - The predicate used for filtering

Returns:

a new arbitrary instance

Throws:

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

filter

@API(status=EXPERIMENTAL,
     since="1.7.0")
default Arbitrary<T> filter(int maxMisses,
                                                                          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.

Parameters:

maxMisses - The max number of misses allowed for filtering

filterPredicate - The predicate used for filtering

Returns:

a new arbitrary instance

Throws:

TooManyFilterMissesException - if filtering will fail to come up with a value after maxMisses 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.

Type Parameters:

U - type of resulting object

Parameters:

mapper - the function used to map

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.

Type Parameters:

U - type of resulting object

Parameters:

mapper - the function used to map to arbitrary

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.

Parameters:

nullProbability - the probability. ≥ 0 and ≤ 1.

Returns:

a new arbitrary instance

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

Parameters:

genSize - The size used in arbitrary instead of the dynamic one

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.

Returns:

a new arbitrary instance

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

Type Parameters:

A - Type of resulting array class

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 generates Optional.empty() values with a probability of 0.05 (i.e. 1 in 20).

Returns:

a new arbitrary instance

optional

@API(status=MAINTAINED,
     since="1.5.4")
default Arbitrary<java.util.Optional<T>> optional(double presenceProbability)

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

The new arbitrary generates Optional.empty() values with a probability of 1 - presenceProbability.

Parameters:

presenceProbability - The probability with which a value is present, i.e. not empty

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.

Parameters:

until - predicate to check if final condition has been reached

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=MAINTAINED,
     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

Throws:

TooManyFilterMissesException - if more than 10000 exceptions are thrown in a row

ignoreException

@API(status=EXPERIMENTAL,
     since="1.7.3")
default Arbitrary<T> ignoreException(int maxThrows,
                                                                                   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:

maxThrows - The maximum number of subsequent exception throws before generation is stopped.

exceptionType - The exception type to ignore

Returns:

a new arbitrary instance

Throws:

TooManyFilterMissesException - if more than maxThrows exceptions are thrown in a row

ignoreExceptions

@API(status=MAINTAINED,
     since="1.7.2")
default Arbitrary<T> ignoreExceptions(java.lang.Class<? extends java.lang.Throwable>... exceptionTypes)

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

If exceptionTypes is empty, the original arbitrary is returned.

Parameters:

exceptionTypes - The exception types to ignore

Returns:

a new arbitrary instance

Throws:

TooManyFilterMissesException - if more than 10000 exceptions are thrown in a row

ignoreExceptions

@API(status=EXPERIMENTAL,
     since="1.7.3")
default Arbitrary<T> ignoreExceptions(int maxThrows,
                                                                                    java.lang.Class<? extends java.lang.Throwable>... exceptionTypes)

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

If exceptionTypes is empty, the original arbitrary is returned.

Parameters:

maxThrows - The maximum number of subsequent exception throws before generation is stopped.

exceptionTypes - The exception types to ignore

Returns:

a new arbitrary instance

Throws:

TooManyFilterMissesException - if more than maxThrows exceptions are thrown in a row

dontShrink

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

edgeCases

@API(status=MAINTAINED,
     since="1.8.0")
default Arbitrary<T> edgeCases(java.util.function.Consumer<EdgeCases.Config<T>> configurator)

Experimental interface to change generated edge cases of a specific arbitrary.

Parameters:

configurator - A consumer that configures deviating edge cases behaviour

Returns:

a new arbitrary instance

See Also:

EdgeCases.Config

withoutEdgeCases

@API(status=MAINTAINED,
     since="1.8.0")
default Arbitrary<T> withoutEdgeCases()

Create a new arbitrary of type T that will not explicitly generate any edge cases, neither directly or in embedded arbitraries. This is useful if you want to prune selected branches of edge case generation because they are to costly or generate too many cases.

Returns:

a new arbitrary instance