Package 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<@Nullable T>
The main interface for representing objects that can be generated and shrunk.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Arbitrary.ArbitraryFacade
     

  • Method Summary

    Modifier and Type
    Method
    Description
    default Optional<Stream<T>>
    allValues()
    Create optional stream of all possible values this arbitrary could generate.
    default <A> ArrayArbitrary<T,A>
    array(Class<A> arrayClass)
    Create a new arbitrary of type T[] using the existing arbitrary for generating the elements of the array.
    default Arbitrary<Object>
    asGeneric()
     
    default Arbitrary<List<T>>
    collect(Predicate<List<@Nullable 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.
    EdgeCases<T>
    edgeCases(int maxEdgeCases)
     
    default Arbitrary<T>
    edgeCases(Consumer<EdgeCases.Config<@Nullable T>> configurator)
    Experimental interface to change generated edge cases of a specific arbitrary.
    default Optional<ExhaustiveGenerator<T>>
    exhaustive()
    Create the exhaustive generator for an arbitrary using the maximum allowed number of generated samples.
    default Optional<ExhaustiveGenerator<T>>
    exhaustive(long maxNumberOfSamples)
    Create the exhaustive generator for an arbitrary.
    default Arbitrary<T>
    filter(int maxMisses, Predicate<@Nullable 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(Predicate<@Nullable 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(Function<@Nullable 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(Consumer<? super @Nullable 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(int maxThrows, Class<? extends 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(Class<? extends 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(int maxThrows, Class<? extends 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(Class<? extends 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<@Nullable 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(Function<@Nullable T,U> mapper)
    Create a new arbitrary of type U that maps the values of the original arbitrary using the mapper function.
    default Arbitrary<Optional<T>>
    optional()
    Create a new arbitrary of type Optional<T> using the existing arbitrary for generating the elements of the stream.
    default Arbitrary<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 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 Details

    • 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<Object> asGeneric()
      Returns:
      The same instance but with type Arbitrary<Object>

    • exhaustive

      @API(status=INTERNAL) default 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 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 Optional<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(Consumer<? super @Nullable 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:
      AssertionError - if exhaustive generation is not possible

    • filter

      default Arbitrary<T> filter(Predicate<@Nullable 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, Predicate<@Nullable 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(Function<@Nullable 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(Function<@Nullable 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<@Nullable 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(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<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<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<List<T>> collect(Predicate<List<@Nullable 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 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(Class<? extends 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, Class<? extends 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(Class<? extends 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, Class<? extends 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(Consumer<EdgeCases.Config<@Nullable 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:

    • 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