Package net.jqwik.api

Klasse Arbitraries

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

  • Methodendetails

    • fromGenerator

      public static <T extends @Nullable Object> Arbitrary<T> fromGenerator(RandomGenerator<T> generator)
      Create an arbitrary of type T from a corresponding generator of type T.
      Typparameter:
      T - The type of values to generate
      Parameter:
      generator - The generator to be used for generating the values
      Gibt zurück:
      a new arbitrary instance

    • fromGeneratorWithSize

      @API(status=EXPERIMENTAL, since="1.8.0") public static <T extends @Nullable Object> Arbitrary<T> fromGeneratorWithSize(IntFunction<RandomGenerator<T>> generatorSupplier)
      Create an arbitrary of type T by supplying a corresponding generator of type T.
      Typparameter:
      T - The type of values to generate
      Parameter:
      generatorSupplier - A function to supply a generator instance given the "size" of a generation attempt
      Gibt zurück:
      a new arbitrary instance

    • randomValue

      public static <T extends @Nullable Object> Arbitrary<T> randomValue(Function<Random,T> generator)
      Create an arbitrary that will generate values of type T using a generator function. The generated values are unshrinkable.
      Typparameter:
      T - The type of values to generate
      Parameter:
      generator - The generator function to be used for generating the values
      Gibt zurück:
      a new arbitrary instance

    • randoms

      public static Arbitrary<Random> randoms()
      Create an arbitrary for Random objects.
      Gibt zurück:
      a new arbitrary instance

    • of

      @SafeVarargs public static <T extends @Nullable Object> 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 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      values - The array of values to choose from
      Gibt zurück:
      a new arbitrary instance

    • of

      @API(status=MAINTAINED, since="1.3.1") public static <T extends @Nullable Object> Arbitrary<T> of(Collection<? extends 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 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      values - The collection of values to choose from
      Gibt zurück:
      a new arbitrary instance

    • ofSuppliers

      @API(status=MAINTAINED, since="1.3.0") @SafeVarargs public static <T extends @Nullable Object> 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      valueSuppliers - The array of values to choose from
      Gibt zurück:
      a new arbitrary instance

    • ofSuppliers

      @API(status=MAINTAINED, since="1.3.1") public static <T extends @Nullable Object> 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      valueSuppliers - The collection of values to choose from
      Gibt zurück:
      a new arbitrary instance

    • of

      public static Arbitrary<Character> of(char[] values)
      Create an arbitrary of character values.
      Parameter:
      values - The array of characters to choose from.
      Gibt zurück:
      a new arbitrary instance

    • of

      public static <T extends Enum<T>> Arbitrary<T> of(Class<T> enumClass)
      Create an arbitrary for enum values of type T.
      Typparameter:
      T - The type of values to generate
      Parameter:
      enumClass - The enum class.
      Gibt zurück:
      a new arbitrary instance

    • oneOf

      @SafeVarargs public static <T extends @Nullable Object> 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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      first - The first arbitrary to choose form
      rest - An array of arbitraries to choose from
      Gibt zurück:
      a new arbitrary instance

    • oneOf

      public static <T extends @Nullable Object> Arbitrary<T> oneOf(Collection<? extends Arbitrary<? extends T>> choices)
      Create an arbitrary that will randomly choose between all given arbitraries of the same type T.
      Typparameter:
      T - The type of values to generate
      Parameter:
      choices - A collection of arbitraries to choose from
      Gibt zurück:
      a new arbitrary instance

    • frequency

      @SafeVarargs public static <T extends @Nullable Object> Arbitrary<T> frequency(Tuple.Tuple2<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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      frequencies - An array of tuples of which the first parameter gives the weight and the second the value.
      Gibt zurück:
      a new arbitrary instance

    • frequency

      public static <T extends @Nullable Object> Arbitrary<T> frequency(List<? extends Tuple.Tuple2<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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      frequencies - A list of tuples of which the first parameter gives the weight and the second the value.
      Gibt zurück:
      a new arbitrary instance

    • frequencyOf

      @SafeVarargs public static <T extends @Nullable Object> 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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      frequencies - An array of tuples of which the first parameter gives the weight and the second the arbitrary.
      Gibt zurück:
      a new arbitrary instance

    • frequencyOf

      public static <T extends @Nullable Object> Arbitrary<T> frequencyOf(List<? extends Tuple.Tuple2<Integer,? extends 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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      frequencies - A list of tuples of which the first parameter gives the weight and the second the arbitrary.
      Gibt zurück:
      a new arbitrary instance

    • integers

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

    • longs

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

    • bigIntegers

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

    • floats

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

    • bigDecimals

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

    • doubles

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

    • bytes

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

    • shorts

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

    • strings

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

    • chars

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

    • just

      @API(status=MAINTAINED, since="1.3.2") public static <T extends @Nullable Object> Arbitrary<T> just(T value)
      Create an arbitrary that will always generate the same value.
      Typparameter:
      T - The type of the value
      Parameter:
      value - The value to "generate".
      Gibt zurück:
      a new arbitrary instance

    • create

      @API(status=MAINTAINED, since="1.1.1") public static <T extends @Nullable Object> Arbitrary<T> create(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.

      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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      supplier - The supplier use to generate a value
      Gibt zurück:
      a new arbitrary instance

    • shuffle

      @SafeVarargs public static <T extends @Nullable Object> Arbitrary<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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      values - The values to permute
      Gibt zurück:
      a new arbitrary instance

    • shuffle

      public static <T extends @Nullable Object> Arbitrary<List<T>> shuffle(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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      values - The values to permute
      Gibt zurück:
      a new arbitrary instance

    • defaultFor

      public static <T> Arbitrary<T> defaultFor(Class<T> type, 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.
      Typparameter:
      T - The type of values to generate
      Parameter:
      type - The type of the value to find an arbitrary for
      typeParameters - The type parameters if type is a generic type
      Gibt zurück:
      a new arbitrary instance
      Löst aus:
      CannotFindArbitraryException - if there is no registered arbitrary provider to serve this type

    • defaultFor

      @API(status=MAINTAINED, since="1.1") public static <T extends @Nullable Object> 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.

      The returned arbitrary is lazy, i.e. it be evaluated at generation time to allow domain contexts to be used.

      Typparameter:
      T - The type of values to generate
      Parameter:
      typeUsage - The type of the value to find an arbitrary for
      Gibt zurück:
      a new arbitrary instance

    • defaultFor

      @API(status=EXPERIMENTAL, since="1.6.1") public static <T> Arbitrary<T> defaultFor(TypeUsage typeUsage, Function<? super TypeUsage,? extends Arbitrary<T>> 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

      Typparameter:
      T - The type of values to generate
      Parameter:
      typeUsage - The type of the value to find an arbitrary for
      noDefaultResolver - Alternative resolution when no default arbitrary can be found at generation time
      Gibt zurück:
      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 type T that will by default use the type's public constructors and public factory methods.
      Typparameter:
      T - The type of values to generate
      Parameter:
      targetType - The class of the type to create an arbitrary for
      Gibt zurück:
      a new arbitrary instance
      Siehe auch:

    • traverse

      @API(status=EXPERIMENTAL, since="1.6.1") public static <T> TraverseArbitrary<T> traverse(Class<T> targetType, TraverseArbitrary.Traverser traverser)
      Create an arbitrary for type T 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      targetType - The class of the type to create an arbitrary for
      traverser - The traversing strategy specification
      Gibt zurück:
      a new arbitrary instance
      Siehe auch:

    • lazy

      public static <T extends @Nullable Object> Arbitrary<T> lazy(Supplier<? extends 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      arbitrarySupplier - The supplier function being used to generate an arbitrary
      Gibt zurück:
      a new arbitrary instance
      Siehe auch:

    • recursive

      public static <T extends @Nullable Object> Arbitrary<T> recursive(Supplier<? extends Arbitrary<T>> base, Function<? super Arbitrary<T>,? extends 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      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
      Gibt zurück:
      a new arbitrary instance
      Siehe auch:

    • recursive

      @API(status=MAINTAINED, since="1.6.4") public static <T extends @Nullable Object> Arbitrary<T> recursive(Supplier<? extends Arbitrary<T>> base, Function<? super Arbitrary<T>,? extends 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      base - The supplier returning the recursion's base case
      recur - The function to extend the base case
      minDepth - The minimum number of times to invoke recursion
      maxDepth - The maximum number of times to invoke recursion
      Gibt zurück:
      a new arbitrary instance
      Siehe auch:

    • lazyOf

      @SafeVarargs @API(status=MAINTAINED, since="1.3.4") public static <T extends @Nullable Object> 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.

      Typparameter:
      T - The type of values to generate
      Parameter:
      first - The first supplier to choose from
      rest - The rest of suppliers to choose from
      Gibt zurück:
      a (potentially cached) arbitrary instance
      Siehe auch:

    • 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.
      Typparameter:
      M - The type of actions to generate
      Parameter:
      actionArbitrary - The arbitrary to generate individual actions.
      Gibt zurück:
      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.
      Typparameter:
      K - type of keys
      V - type of values
      Parameter:
      keysArbitrary - The arbitrary to generate the keys
      valuesArbitrary - The arbitrary to generate the values
      Gibt zurück:
      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.
      Typparameter:
      K - type of keys
      V - type of values
      Parameter:
      keysArbitrary - The arbitrary to generate the keys
      valuesArbitrary - The arbitrary to generate the values
      Gibt zurück:
      a new arbitrary instance

    • nothing

      @API(status=MAINTAINED, since="1.3.0") public static Arbitrary<Void> nothing()
      Create an arbitrary that never creates anything. Sometimes useful when generating arbitraries of "functions" that have void as return type.
      Gibt zurück:
      arbitrary instance that will generate nothing

    • subsetOf

      @API(status=MAINTAINED, since="1.6.4") public static <T extends @Nullable Object> SetArbitrary<T> subsetOf(Collection<? extends T> values)
      Create a new arbitrary of element type Set<T> using the handed in values as elements of the set.
      Gibt zurück:
      a new arbitrary instance

    • subsetOf

      @SafeVarargs @API(status=MAINTAINED, since="1.6.4") public static <T extends @Nullable Object> SetArbitrary<T> subsetOf(T... values)
      Create a new arbitrary of element type Set<T> using the handed in values as elements of the set.
      Gibt zurück:
      a new arbitrary instance