Package net.jqwik.api

Class Arbitraries

  • @API(status=STABLE,
     since="1.0")
public class Arbitraries
extends java.lang.Object

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static BigDecimalArbitrary bigDecimals()
      Create an arbitrary that generates values of type BigDecimal.
      static BigIntegerArbitrary bigIntegers()
      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> constant​(T value)
      Deprecated.
      Use just(Object) instead.
      static <T> Arbitrary<T> create​(java.util.function.Supplier<T> supplier)
      Create an arbitrary that will use a supplier to generate a value.
      static <T> Arbitrary<T> defaultFor​(java.lang.Class<T> type, java.lang.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 DoubleArbitrary doubles()
      Create an arbitrary that generates values of type Double.
      static Arbitrary<java.lang.String> emails()
      Create an arbitrary that generates valid E-Mail addresses.
      static <K,​V>
      Arbitrary<java.util.Map.Entry<K,​V>>      		 entries​(Arbitrary<K> keysArbitrary, Arbitrary<V> valuesArbitrary)
      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> forType​(java.lang.Class<T> targetType)
      Create an arbitrary for type T that will by default use the type's public constructors and public factory methods.
      static <T> Arbitrary<T> frequency​(java.util.List<Tuple.Tuple2<java.lang.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<java.lang.Integer,​T>... frequencies)
      Create an arbitrary that will randomly choose between all given values of the same type T.
      static <T> Arbitrary<T> frequencyOf​(java.util.List<Tuple.Tuple2<java.lang.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<java.lang.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> lazy​(java.util.function.Supplier<Arbitrary<T>> arbitrarySupplier)
      Create an arbitrary that will evaluate arbitrarySupplier as soon as it is used for generating values.
      static <T> Arbitrary<T> lazyOf​(java.util.function.Supplier<Arbitrary<? extends T>> first, java.util.function.Supplier<Arbitrary<? extends T>>... rest)
      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>      		 maps​(Arbitrary<K> keysArbitrary, Arbitrary<V> valuesArbitrary)
      Create an arbitrary to create instances of Map.
      static Arbitrary<java.lang.Void> nothing()
      Create an arbitrary that never creates anything.
      static Arbitrary<java.lang.Character> of​(char[] values)
      Create an arbitrary of character values.
      static <T extends java.lang.Enum<T>>
      Arbitrary<T>      		 of​(java.lang.Class<T> enumClass)
      Create an arbitrary for enum values of type T.
      static <T> Arbitrary<T> of​(java.util.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​(java.util.Collection<java.util.function.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​(java.util.function.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​(java.util.List<Arbitrary<T>> all)
      Create an arbitrary that will randomly choose between all given arbitraries of the same type T.
      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.
      static Arbitrary<java.util.Random> randoms()
      Create an arbitrary for Random objects.
      static <T> Arbitrary<T> randomValue​(java.util.function.Function<java.util.Random,​T> generator)
      Create an arbitrary that will generate values of type T using a generator function.
      static <T> Arbitrary<T> recursive​(java.util.function.Supplier<Arbitrary<T>> base, java.util.function.Function<Arbitrary<T>,​Arbitrary<T>> recur, int depth)
      Create an arbitrary by deterministic recursion.
      static <T> Arbitrary<T> samples​(T... samples)
      Deprecated.
      Use of(Object[]) or move to data-driven properties if order is important.
      static <M> ActionSequenceArbitrary<M> sequences​(Arbitrary<? extends Action<M>> actionArbitrary)
      Create an arbitrary to create a sequence of actions.
      static ShortArbitrary shorts()
      Create an arbitrary that generates values of type Short.
      static <T> Arbitrary<java.util.List<T>> shuffle​(java.util.List<T> values)
      Create an arbitrary that will always generate a list which is a permutation of the values handed to it.
      static <T> Arbitrary<java.util.List<T>> 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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • fromGenerator

        public static <T> Arbitrary<T> fromGenerator​(RandomGenerator<T> generator)
        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

        public static <T> Arbitrary<T> randomValue​(java.util.function.Function<java.util.Random,​T> generator)
        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

        public static Arbitrary<java.util.Random> randoms()
        Create an arbitrary for Random objects.
        Returns:
        a new arbitrary instance

      • of

        @SafeVarargs
public static <T> Arbitrary<T> of​(T... values)
        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 values, because changing the value will change subsequent generated values as well. For mutable values use ofSuppliers(Supplier[]) instead.

        Type Parameters:
        T - The type of values to generate
        Parameters:
        values - The array of values to choose from
        Returns:
        a new arbitrary instance

      • of

        @API(status=MAINTAINED,
     since="1.3.1")
public static <T> Arbitrary<T> of​(java.util.Collection<T> values)
        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 values, because changing the value will change subsequent generated values as well. For mutable values use ofSuppliers(Collection) instead.

        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​(java.util.function.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​(java.util.Collection<java.util.function.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

        public static Arbitrary<java.lang.Character> of​(char[] values)
        Create an arbitrary of character values.
        Parameters:
        values - The array of characters to choose from.
        Returns:
        a new arbitrary instance

      • of

        public static <T extends java.lang.Enum<T>> Arbitrary<T> of​(java.lang.Class<T> enumClass)
        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 form
        rest - An array of arbitraries to choose from
        Returns:
        a new arbitrary instance

      • oneOf

        public static <T> Arbitrary<T> oneOf​(java.util.List<Arbitrary<T>> all)
        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:
        all - A list of arbitraries to choose from
        Returns:
        a new arbitrary instance

      • frequency

        @SafeVarargs
public static <T> Arbitrary<T> frequency​(Tuple.Tuple2<java.lang.Integer,​T>... frequencies)
        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

        public static <T> Arbitrary<T> frequency​(java.util.List<Tuple.Tuple2<java.lang.Integer,​T>> frequencies)
        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<java.lang.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

        public static <T> Arbitrary<T> frequencyOf​(java.util.List<Tuple.Tuple2<java.lang.Integer,​Arbitrary<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 - A list of tuples of which the first parameter gives the weight and the second the arbitrary.
        Returns:
        a new arbitrary instance

      • integers

        public static IntegerArbitrary integers()
        Create an arbitrary that generates values of type Integer.
        Returns:
        a new arbitrary instance

      • longs

        public static LongArbitrary longs()
        Create an arbitrary that generates values of type Long.
        Returns:
        a new arbitrary instance

      • bigIntegers

        public static BigIntegerArbitrary bigIntegers()
        Create an arbitrary that generates values of type BigInteger.
        Returns:
        a new arbitrary instance

      • floats

        public static FloatArbitrary floats()
        Create an arbitrary that generates values of type Float.
        Returns:
        a new arbitrary instance

      • bigDecimals

        public static BigDecimalArbitrary bigDecimals()
        Create an arbitrary that generates values of type BigDecimal.
        Returns:
        a new arbitrary instance

      • doubles

        public static DoubleArbitrary doubles()
        Create an arbitrary that generates values of type Double.
        Returns:
        a new arbitrary instance

      • bytes

        public static ByteArbitrary bytes()
        Create an arbitrary that generates values of type Byte.
        Returns:
        a new arbitrary instance

      • shorts

        public static ShortArbitrary shorts()
        Create an arbitrary that generates values of type Short.
        Returns:
        a new arbitrary instance

      • strings

        public static StringArbitrary strings()
        Create an arbitrary that generates values of type String.
        Returns:
        a new arbitrary instance

      • emails

        @API(status=EXPERIMENTAL,
     since="1.3.8")
public static Arbitrary<java.lang.String> emails()
        Create an arbitrary that generates valid E-Mail addresses.
        Returns:
        a new arbitrary instance

      • chars

        public static CharacterArbitrary chars()
        Create an arbitrary that generates values of type Character.
        Returns:
        a new arbitrary instance

      • samples

        @SafeVarargs
@Deprecated
@API(status=DEPRECATED,
     since="1.3.0")
public static <T> Arbitrary<T> samples​(T... samples)
        Deprecated.
        Use of(Object[]) or move to data-driven properties if order is important. Will be removed in version 1.4.0
        Create an arbitrary that will provide the sample values from first to last and then start again at the beginning. Shrinking of samples is tried towards the start of the samples.

        Attention: If you want to randomly choose between samples you must use of(Object[])

        Type Parameters:
        T - The type of values to generate
        Parameters:
        samples - The array of sample values
        Returns:
        a new arbitrary instance

      • constant

        @API(status=DEPRECATED,
     since="1.3.2")
public static <T> Arbitrary<T> constant​(T value)
        Deprecated.
        Use just(Object) instead. To be removed in version 2.0.
        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
        See Also:
        just(Object)

      • just

        @API(status=MAINTAINED,
     since="1.3.2")
public static <T> Arbitrary<T> just​(T value)
        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

        @API(status=MAINTAINED,
     since="1.1.1")
public static <T> Arbitrary<T> create​(java.util.function.Supplier<T> supplier)
        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.

        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

        @SafeVarargs
public static <T> Arbitrary<java.util.List<T>> shuffle​(T... values)
        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

        public static <T> Arbitrary<java.util.List<T>> shuffle​(java.util.List<T> values)
        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

        public static <T> Arbitrary<T> defaultFor​(java.lang.Class<T> type,
                                          java.lang.Class<?>... typeParameters)
        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 for
        typeParameters - 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

        @API(status=MAINTAINED,
     since="1.1")
public static <T> Arbitrary<T> defaultFor​(TypeUsage typeUsage)
        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:
        typeUsage - The type of the value to find an arbitrary for
        Returns:
        a new arbitrary instance
        Throws:
        CannotFindArbitraryException - if there is no registered arbitrary provider to serve this type

      • forType

        @API(status=MAINTAINED,
     since="1.2.0")
public static <T> TypeArbitrary<T> forType​(java.lang.Class<T> targetType)
        Create an arbitrary for type T 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:
        TypeArbitrary

      • lazy

        public static <T> Arbitrary<T> lazy​(java.util.function.Supplier<Arbitrary<T>> arbitrarySupplier)
        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(Supplier, Function, int), lazyOf(Supplier, Supplier[])

      • recursive

        public static <T> Arbitrary<T> recursive​(java.util.function.Supplier<Arbitrary<T>> base,
                                         java.util.function.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 case
        recur - The function to extend the base case
        depth - The number of times to invoke recursion
        Returns:
        a new arbitrary instance
        See Also:
        lazy(Supplier)

      • lazyOf

        @SafeVarargs
@API(status=EXPERIMENTAL,
     since="1.3.4")
public static <T> Arbitrary<T> lazyOf​(java.util.function.Supplier<Arbitrary<? extends T>> first,
                                      java.util.function.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 from
        rest - The rest of suppliers to choose from
        Returns:
        a (potentially cached) arbitrary instance
        See Also:
        lazy(Supplier), recursive(Supplier, Function, int)

      • 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 keys
        V - type of values
        Parameters:
        keysArbitrary - The arbitrary to generate the keys
        valuesArbitrary - The arbitrary to generate the values
        Returns:
        a new arbitrary instance

      • entries

        @API(status=MAINTAINED,
     since="1.2.0")
public static <K,​V> Arbitrary<java.util.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 keys
        V - type of values
        Parameters:
        keysArbitrary - The arbitrary to generate the keys
        valuesArbitrary - The arbitrary to generate the values
        Returns:
        a new arbitrary instance

      • nothing

        @API(status=MAINTAINED,
     since="1.3.0")
public static Arbitrary<java.lang.Void> 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