Class Arbitraries
-
Nested Class Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic BigDecimalArbitrary
Create an arbitrary that generates values of type BigDecimal.static BigIntegerArbitrary
Create an arbitrary that generates values of type BigInteger.static ByteArbitrary
bytes()
Create an arbitrary that generates values of type Byte.static CharacterArbitrary
chars()
Create an arbitrary that generates values of type Character.static <T> Arbitrary<T>
Create an arbitrary that will use a supplier to generate a value.static <T> Arbitrary<T>
defaultFor
(Class<T> type, Class<?>... typeParameters) Find a registered arbitrary that will be used to generate values of type T.static <T> Arbitrary<T>
defaultFor
(TypeUsage typeUsage) Find a registered arbitrary that will be used to generate values of type T.static <T> Arbitrary<T>
Find a registered arbitrary that will be used to generate values of type T.static DoubleArbitrary
doubles()
Create an arbitrary that generates values of type Double.Create an arbitrary to create instances of Map.Entry.static FloatArbitrary
floats()
Create an arbitrary that generates values of type Float.static <T> TypeArbitrary<T>
Create an arbitrary for typeT
that will by default use the type's public constructors and public factory methods.static <T> Arbitrary<T>
frequency
(List<Tuple.Tuple2<Integer, T>> frequencies) Create an arbitrary that will randomly choose between all given values of the same type T.static <T> Arbitrary<T>
frequency
(Tuple.Tuple2<Integer, T>... frequencies) Create an arbitrary that will randomly choose between all given values of the same type T.static <T> Arbitrary<T>
frequencyOf
(List<Tuple.Tuple2<Integer, Arbitrary<T>>> frequencies) Create an arbitrary that will randomly choose between all given arbitraries of the same type T.static <T> Arbitrary<T>
frequencyOf
(Tuple.Tuple2<Integer, Arbitrary<? extends T>>... frequencies) Create an arbitrary that will randomly choose between all given arbitraries of the same type T.static <T> Arbitrary<T>
fromGenerator
(RandomGenerator<T> generator) Create an arbitrary of type T from a corresponding generator of type T.static IntegerArbitrary
integers()
Create an arbitrary that generates values of type Integer.static <T> Arbitrary<T>
just
(T value) Create an arbitrary that will always generate the same value.static <T> Arbitrary<T>
Create an arbitrary that will evaluate arbitrarySupplier as soon as it is used for generating values.static <T> Arbitrary<T>
Create an arbitrary by lazy supplying one of several arbitraries.static LongArbitrary
longs()
Create an arbitrary that generates values of type Long.static <K,
V> MapArbitrary<K, V> Create an arbitrary to create instances of Map.nothing()
Create an arbitrary that never creates anything.of
(char[] values) Create an arbitrary of character values.Create an arbitrary for enum values of type T.static <T> Arbitrary<T>
of
(Collection<T> values) Create an arbitrary that will randomly choose from a given collection of values.static <T> Arbitrary<T>
of
(T... values) Create an arbitrary that will randomly choose from a given array of values.static <T> Arbitrary<T>
ofSuppliers
(Collection<Supplier<T>> valueSuppliers) Create an arbitrary that will randomly choose from a given collection of value suppliers and then get the value from the supplier.static <T> Arbitrary<T>
ofSuppliers
(Supplier<T>... valueSuppliers) Create an arbitrary that will randomly choose from a given array of value suppliers and then get the value from the supplier.static <T> Arbitrary<T>
oneOf
(Collection<Arbitrary<? extends T>> choices) Create an arbitrary that will randomly choose between all given arbitraries of the same type T.static <T> Arbitrary<T>
Create an arbitrary that will randomly choose between all given arbitraries of the same type T.randoms()
Create an arbitrary for Random objects.static <T> Arbitrary<T>
randomValue
(Function<Random, T> generator) Create an arbitrary that will generate values of type T using a generator function.static <T> Arbitrary<T>
Create an arbitrary by deterministic recursion.static <T> Arbitrary<T>
recursive
(Supplier<Arbitrary<T>> base, Function<Arbitrary<T>, Arbitrary<T>> recur, int minDepth, int maxDepth) Create an arbitrary by deterministic recursion.static <M> ActionSequenceArbitrary<M>
Create an arbitrary to create a sequence of actions.static ShortArbitrary
shorts()
Create an arbitrary that generates values of type Short.Create an arbitrary that will always generate a list which is a permutation of the values handed to it.shuffle
(T... values) Create an arbitrary that will always generate a list which is a permutation of the values handed to it.static StringArbitrary
strings()
Create an arbitrary that generates values of type String.static <T> SetArbitrary<T>
subsetOf
(Collection<T> values) Create a new arbitrary of element typeSet<T>
using the handed in values as elements of the set.static <T> SetArbitrary<T>
subsetOf
(T... values) Create a new arbitrary of element typeSet<T>
using the handed in values as elements of the set.static <T> TraverseArbitrary<T>
traverse
(Class<T> targetType, TraverseArbitrary.Traverser traverser) Create an arbitrary for typeT
that will try to traverse a type - and all types it is based on - given a TraverseArbitrary.Traverser strategy.
-
Method Details
-
fromGenerator
Create an arbitrary of type T from a corresponding generator of type T.- Type Parameters:
T
- The type of values to generate- Parameters:
generator
- The generator to be used for generating the values- Returns:
- a new arbitrary instance
-
randomValue
Create an arbitrary that will generate values of type T using a generator function. The generated values are unshrinkable.- Type Parameters:
T
- The type of values to generate- Parameters:
generator
- The generator function to be used for generating the values- Returns:
- a new arbitrary instance
-
randoms
Create an arbitrary for Random objects.- Returns:
- a new arbitrary instance
-
of
Create an arbitrary that will randomly choose from a given array of values. A generated value will be shrunk towards the start of the array.Use this method only for immutable arrays of immutable values. Changing a value will change subsequently generated values as well. For mutable values use ofSuppliers(Supplier[]) instead. Modifying the array may cause erratic behavior, things may halt and catch fire.
- Type Parameters:
T
- The type of values to generate- Parameters:
values
- The array of values to choose from- Returns:
- a new arbitrary instance
-
of
Create an arbitrary that will randomly choose from a given collection of values. A generated value will be shrunk towards the start of the collection.Use this method only for immutable collections of immutable values. Changing a value will change subsequently generated values as well. For mutable values use ofSuppliers(Collection) instead. Modifying the collection may cause erratic behavior, kittens may die.
- Type Parameters:
T
- The type of values to generate- Parameters:
values
- The collection of values to choose from- Returns:
- a new arbitrary instance
-
ofSuppliers
@API(status=MAINTAINED, since="1.3.0") @SafeVarargs public static <T> Arbitrary<T> ofSuppliers(Supplier<T>... valueSuppliers) Create an arbitrary that will randomly choose from a given array of value suppliers and then get the value from the supplier. A generated value will be shrunk towards the start of the array.Use this method instead of of(Object[]) for mutable objects to make sure that changing a generated object will not influence other generated objects.
- Type Parameters:
T
- The type of values to generate- Parameters:
valueSuppliers
- The array of values to choose from- Returns:
- a new arbitrary instance
-
ofSuppliers
@API(status=MAINTAINED, since="1.3.1") public static <T> Arbitrary<T> ofSuppliers(Collection<Supplier<T>> valueSuppliers) Create an arbitrary that will randomly choose from a given collection of value suppliers and then get the value from the supplier. A generated value will be shrunk towards the start of the collection.Use this method instead of of(Collection) for mutable objects to make sure that changing a generated object will not influence other generated objects.
- Type Parameters:
T
- The type of values to generate- Parameters:
valueSuppliers
- The collection of values to choose from- Returns:
- a new arbitrary instance
-
of
Create an arbitrary of character values.- Parameters:
values
- The array of characters to choose from.- Returns:
- a new arbitrary instance
-
of
Create an arbitrary for enum values of type T.- Type Parameters:
T
- The type of values to generate- Parameters:
enumClass
- The enum class.- Returns:
- a new arbitrary instance
-
oneOf
@SafeVarargs public static <T> Arbitrary<T> oneOf(Arbitrary<? extends T> first, Arbitrary<? extends T>... rest) Create an arbitrary that will randomly choose between all given arbitraries of the same type T.- Type Parameters:
T
- The type of values to generate- Parameters:
first
- The first arbitrary to choose formrest
- An array of arbitraries to choose from- Returns:
- a new arbitrary instance
-
oneOf
Create an arbitrary that will randomly choose between all given arbitraries of the same type T.- Type Parameters:
T
- The type of values to generate- Parameters:
choices
- A collection of arbitraries to choose from- Returns:
- a new arbitrary instance
-
frequency
Create an arbitrary that will randomly choose between all given values of the same type T. The probability distribution is weighted with the first parameter of the tuple.- Type Parameters:
T
- The type of values to generate- Parameters:
frequencies
- An array of tuples of which the first parameter gives the weight and the second the value.- Returns:
- a new arbitrary instance
-
frequency
Create an arbitrary that will randomly choose between all given values of the same type T. The probability distribution is weighted with the first parameter of the tuple.- Type Parameters:
T
- The type of values to generate- Parameters:
frequencies
- A list of tuples of which the first parameter gives the weight and the second the value.- Returns:
- a new arbitrary instance
-
frequencyOf
@SafeVarargs public static <T> Arbitrary<T> frequencyOf(Tuple.Tuple2<Integer, Arbitrary<? extends T>>... frequencies) Create an arbitrary that will randomly choose between all given arbitraries of the same type T. The probability distribution is weighted with the first parameter of the tuple.- Type Parameters:
T
- The type of values to generate- Parameters:
frequencies
- An array of tuples of which the first parameter gives the weight and the second the arbitrary.- Returns:
- a new arbitrary instance
-
frequencyOf
Create an arbitrary that will randomly choose between all given arbitraries of the same type T. The probability distribution is weighted with the first parameter of the tuple.- Type Parameters:
T
- The type of values to generate- Parameters:
frequencies
- A list of tuples of which the first parameter gives the weight and the second the arbitrary.- Returns:
- a new arbitrary instance
-
integers
Create an arbitrary that generates values of type Integer.- Returns:
- a new arbitrary instance
-
longs
Create an arbitrary that generates values of type Long.- Returns:
- a new arbitrary instance
-
bigIntegers
Create an arbitrary that generates values of type BigInteger.- Returns:
- a new arbitrary instance
-
floats
Create an arbitrary that generates values of type Float.- Returns:
- a new arbitrary instance
-
bigDecimals
Create an arbitrary that generates values of type BigDecimal.- Returns:
- a new arbitrary instance
-
doubles
Create an arbitrary that generates values of type Double.- Returns:
- a new arbitrary instance
-
bytes
Create an arbitrary that generates values of type Byte.- Returns:
- a new arbitrary instance
-
shorts
Create an arbitrary that generates values of type Short.- Returns:
- a new arbitrary instance
-
strings
Create an arbitrary that generates values of type String.- Returns:
- a new arbitrary instance
-
chars
Create an arbitrary that generates values of type Character.- Returns:
- a new arbitrary instance
-
just
Create an arbitrary that will always generate the same value.- Type Parameters:
T
- The type of the value- Parameters:
value
- The value to "generate".- Returns:
- a new arbitrary instance
-
create
Create an arbitrary that will use a supplier to generate a value. The difference to just(Object) is that the value is freshly generated for each try of a property.Mind that within a
supplier
you should never use other arbitraries or do anything non-deterministic.For exhaustive shrinking all generated values are supposed to have identical behaviour, i.e. that means that only one value is generated per combination.
- Type Parameters:
T
- The type of values to generate- Parameters:
supplier
- The supplier use to generate a value- Returns:
- a new arbitrary instance
-
shuffle
Create an arbitrary that will always generate a list which is a permutation of the values handed to it. Permutations will not be shrunk.- Type Parameters:
T
- The type of values to generate- Parameters:
values
- The values to permute- Returns:
- a new arbitrary instance
-
shuffle
Create an arbitrary that will always generate a list which is a permutation of the values handed to it. Permutations will not be shrunk.- Type Parameters:
T
- The type of values to generate- Parameters:
values
- The values to permute- Returns:
- a new arbitrary instance
-
defaultFor
Find a registered arbitrary that will be used to generate values of type T. All default arbitrary providers and all registered arbitrary providers are considered. This is more or less the same mechanism that jqwik uses to find arbitraries for property method parameters.- Type Parameters:
T
- The type of values to generate- Parameters:
type
- The type of the value to find an arbitrary fortypeParameters
- The type parameters if type is a generic type- Returns:
- a new arbitrary instance
- Throws:
CannotFindArbitraryException
- if there is no registered arbitrary provider to serve this type
-
defaultFor
Find a registered arbitrary that will be used to generate values of type T. All default arbitrary providers and all registered arbitrary providers are considered. This is more or less the same mechanism that jqwik uses to find arbitraries for property method parameters.The returned arbitrary is lazy, i.e. it be evaluated at generation time to allow domain contexts to be used.
- Type Parameters:
T
- The type of values to generate- Parameters:
typeUsage
- The type of the value to find an arbitrary for- Returns:
- a new arbitrary instance
-
defaultFor
@API(status=EXPERIMENTAL, since="1.6.1") public static <T> Arbitrary<T> defaultFor(TypeUsage typeUsage, Function<TypeUsage, Arbitrary<Object>> noDefaultResolver) Find a registered arbitrary that will be used to generate values of type T. All default arbitrary providers and all registered arbitrary providers are considered. This is more or less the same mechanism that jqwik uses to find arbitraries for property method parameters.The returned arbitrary is lazy, i.e. it be evaluated at generation time to allow domain contexts to be used. Those
- Type Parameters:
T
- The type of values to generate- Parameters:
typeUsage
- The type of the value to find an arbitrary fornoDefaultResolver
- Alternative resolution when no default arbitrary can be found at generation time- Returns:
- a new arbitrary instance
-
forType
@API(status=MAINTAINED, since="1.2.0") public static <T> TypeArbitrary<T> forType(Class<T> targetType) Create an arbitrary for typeT
that will by default use the type's public constructors and public factory methods.- Type Parameters:
T
- The type of values to generate- Parameters:
targetType
- The class of the type to create an arbitrary for- Returns:
- a new arbitrary instance
- See Also:
-
traverse
@API(status=EXPERIMENTAL, since="1.6.1") public static <T> TraverseArbitrary<T> traverse(Class<T> targetType, TraverseArbitrary.Traverser traverser) Create an arbitrary for typeT
that will try to traverse a type - and all types it is based on - given a TraverseArbitrary.Traverser strategy.By default recursion is disable, i.e. that parameters of creator functions can be resolved by the traverser, have a default arbitrary or generation fails at runtime. Use TraverseArbitrary.enableRecursion() to switch on recursive traversal.
One usage of this traversing mechanism is forType(Class) which uses traverse(Class, Traverser) under the hood.
- Type Parameters:
T
- The type of values to generate- Parameters:
targetType
- The class of the type to create an arbitrary fortraverser
- The traversing strategy specification- Returns:
- a new arbitrary instance
- See Also:
-
lazy
Create an arbitrary that will evaluate arbitrarySupplier as soon as it is used for generating values.This is useful (and necessary) when arbitrary providing functions use other arbitrary providing functions in a recursive way. Without the use of lazy() this would result in a stack overflow. Most of the time, however, using lazyOf(Supplier, Supplier[]) is the better choice because it has significantly better shrinking behaviour.
- Type Parameters:
T
- The type of values to generate- Parameters:
arbitrarySupplier
- The supplier function being used to generate an arbitrary- Returns:
- a new arbitrary instance
- See Also:
-
recursive
public static <T> Arbitrary<T> recursive(Supplier<Arbitrary<T>> base, Function<Arbitrary<T>, Arbitrary<T>> recur, int depth) Create an arbitrary by deterministic recursion.Mind that the arbitrary will be created by invoking recursion at arbitrary creation time. Using lazyOf(Supplier, Supplier[]) or lazy(Supplier) instead will recur at value generation time.
- Type Parameters:
T
- The type of values to generate- Parameters:
base
- The supplier returning the recursion's base caserecur
- The function to extend the base casedepth
- The number of times to invoke recursion- Returns:
- a new arbitrary instance
- See Also:
-
recursive
@API(status=MAINTAINED, since="1.6.4") public static <T> Arbitrary<T> recursive(Supplier<Arbitrary<T>> base, Function<Arbitrary<T>, Arbitrary<T>> recur, int minDepth, int maxDepth) Create an arbitrary by deterministic recursion.Mind that the arbitrary will be created by invoking recursion at arbitrary creation time. Using lazyOf(Supplier, Supplier[]) or lazy(Supplier) instead will recur at value generation time.
- Type Parameters:
T
- The type of values to generate- Parameters:
base
- The supplier returning the recursion's base caserecur
- The function to extend the base caseminDepth
- The minimum number of times to invoke recursionmaxDepth
- The maximum number of times to invoke recursion- Returns:
- a new arbitrary instance
- See Also:
-
lazyOf
@SafeVarargs @API(status=MAINTAINED, since="1.3.4") public static <T> Arbitrary<T> lazyOf(Supplier<Arbitrary<? extends T>> first, Supplier<Arbitrary<? extends T>>... rest) Create an arbitrary by lazy supplying one of several arbitraries. The main use of this function is to allow recursive generation of structured values without overflowing the stack.One alternative is to use lazy(Supplier) combined with oneOf(Arbitrary, Arbitrary[]) or frequencyOf(Tuple.Tuple2[]). But
lazyOf()
has considerably better shrinking behaviour with recursion.Caveat: Never use this construct if suppliers make use of variable state like method parameters or changing instance members. In those cases use lazy(Supplier) instead.
- Type Parameters:
T
- The type of values to generate- Parameters:
first
- The first supplier to choose fromrest
- The rest of suppliers to choose from- Returns:
- a (potentially cached) arbitrary instance
- See Also:
-
sequences
@API(status=MAINTAINED, since="1.0") public static <M> ActionSequenceArbitrary<M> sequences(Arbitrary<? extends Action<M>> actionArbitrary) Create an arbitrary to create a sequence of actions. Useful for stateful testing.- Type Parameters:
M
- The type of actions to generate- Parameters:
actionArbitrary
- The arbitrary to generate individual actions.- Returns:
- a new arbitrary instance
-
maps
@API(status=MAINTAINED, since="1.1.6") public static <K,V> MapArbitrary<K,V> maps(Arbitrary<K> keysArbitrary, Arbitrary<V> valuesArbitrary) Create an arbitrary to create instances of Map. The generated maps are mutable.- Type Parameters:
K
- type of keysV
- type of values- Parameters:
keysArbitrary
- The arbitrary to generate the keysvaluesArbitrary
- The arbitrary to generate the values- Returns:
- a new arbitrary instance
-
entries
@API(status=MAINTAINED, since="1.2.0") public static <K,V> Arbitrary<Map.Entry<K,V>> entries(Arbitrary<K> keysArbitrary, Arbitrary<V> valuesArbitrary) Create an arbitrary to create instances of Map.Entry. The generated entries are mutable.- Type Parameters:
K
- type of keysV
- type of values- Parameters:
keysArbitrary
- The arbitrary to generate the keysvaluesArbitrary
- The arbitrary to generate the values- Returns:
- a new arbitrary instance
-
nothing
Create an arbitrary that never creates anything. Sometimes useful when generating arbitraries of "functions" that have void as return type.- Returns:
- arbitrary instance that will generate nothing
-
subsetOf
@API(status=MAINTAINED, since="1.6.4") public static <T> SetArbitrary<T> subsetOf(Collection<T> values) Create a new arbitrary of element typeSet<T>
using the handed in values as elements of the set.- Returns:
- a new arbitrary instance
-
subsetOf
@SafeVarargs @API(status=MAINTAINED, since="1.6.4") public static <T> SetArbitrary<T> subsetOf(T... values) Create a new arbitrary of element typeSet<T>
using the handed in values as elements of the set.- Returns:
- a new arbitrary instance
-