Package net.jqwik.api

Schnittstelle Arbitrary<T extends @Nullable Object>

Typparameter:
T - The type of generated objects. Primitive objects (e.g. int, boolean etc.) are represented by their boxed type (e.g. Integer, Boolean).
Alle bekannten Unterschnittstellen:
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
Alle bekannten Implementierungsklassen:
ArbitraryDecorator
@API(status=STABLE, since="1.0") @CheckReturnValue public interface Arbitrary<T extends @Nullable Object>
The main interface for representing objects that can be generated and shrunk.

  • Verschachtelte Klassen - Übersicht

    Verschachtelte Klassen
    Modifizierer und Typ
    Schnittstelle
    Beschreibung
    static class 
    Arbitrary.ArbitraryFacade
     

  • Methodenübersicht

    Modifizierer und Typ
    Methode
    Beschreibung
    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<? super List<? extends 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<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<? super 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<? super 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 extends @Nullable Object>
    Arbitrary<U>
    flatMap(Function<? super T,? extends 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 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 extends @Nullable Object>
    Arbitrary<U>
    map(Function<? super T,? extends 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.

  • Methodendetails

    • 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)

      Parameter:
      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.

      Gibt zurück:
      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.

      Parameter:
      genSize - See generator(int) about meaning of this parameter
      withEdgeCases - True if edge cases should be injected into the stream of generated values
      Gibt zurück:
      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

      Parameter:
      genSize - See generator(int) about meaning of this parameter
      Gibt zurück:
      a new random generator instance

    • asGeneric

      @API(status=INTERNAL) default Arbitrary<Object> asGeneric()
      Gibt zurück:
      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.
      Gibt zurück:
      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.
      Parameter:
      maxNumberOfSamples - The maximum number of samples considered. If during generation it becomes clear that this number will be exceeded generation stops.
      Gibt zurück:
      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.

      Gibt zurück:
      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.
      Gibt zurück:
      optional stream of all possible values

    • forEachValue

      @API(status=MAINTAINED, since="1.1.2") default void forEachValue(Consumer<? super T> action)
      Iterate through each value this arbitrary can generate if - and only if - exhaustive generation is possible. This method can be used for example to make assertions about a set of values described by an arbitrary.
      Parameter:
      action - the consumer function to be invoked for each value
      Löst aus:
      AssertionError - if exhaustive generation is not possible

    • filter

      default Arbitrary<T> filter(Predicate<? super 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.
      Parameter:
      filterPredicate - The predicate used for filtering
      Gibt zurück:
      a new arbitrary instance
      Löst aus:
      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<? super 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.
      Parameter:
      maxMisses - The max number of misses allowed for filtering
      filterPredicate - The predicate used for filtering
      Gibt zurück:
      a new arbitrary instance
      Löst aus:
      TooManyFilterMissesException - if filtering will fail to come up with a value after maxMisses tries

    • map

      default <U extends @Nullable Object> Arbitrary<U> map(Function<? super T,? extends U> mapper)
      Create a new arbitrary of type U that maps the values of the original arbitrary using the mapper function.
      Typparameter:
      U - type of resulting object
      Parameter:
      mapper - the function used to map
      Gibt zurück:
      a new arbitrary instance

    • flatMap

      default <U extends @Nullable Object> Arbitrary<U> flatMap(Function<? super T,? extends 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.
      Typparameter:
      U - type of resulting object
      Parameter:
      mapper - the function used to map to arbitrary
      Gibt zurück:
      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.
      Parameter:
      nullProbability - the probability. ≥ 0 and ≤ 1.
      Gibt zurück:
      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
      Parameter:
      genSize - The size used in arbitrary instead of the dynamic one
      Gibt zurück:
      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.
      Gibt zurück:
      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.
      Gibt zurück:
      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.
      Gibt zurück:
      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.
      Gibt zurück:
      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.
      Typparameter:
      A - Type of resulting array class
      Parameter:
      arrayClass - The arrays class to create, e.g. String[].class. This is required due to limitations in Java's reflection capabilities.
      Gibt zurück:
      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).

      Gibt zurück:
      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.

      Parameter:
      presenceProbability - The probability with which a value is present, i.e. not empty
      Gibt zurück:
      a new arbitrary instance

    • collect

      @API(status=MAINTAINED, since="1.3.0") default Arbitrary<List<T>> collect(Predicate<? super List<? extends T>> until)
      Create a new arbitrary of type List<T> by adding elements of type T until condition until is fulfilled.
      Parameter:
      until - predicate to check if final condition has been reached
      Gibt zurück:
      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.

      Gibt zurück:
      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.
      Gibt zurück:
      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.

      Parameter:
      duplicateProbability - The probability with which a previous value will be generated
      Gibt zurück:
      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;
      Gibt zurück:
      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;
      Gibt zurück:
      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;
      Gibt zurück:
      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;
      Gibt zurück:
      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;
      Gibt zurück:
      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.
      Parameter:
      exceptionType - The exception type to ignore
      Gibt zurück:
      a new arbitrary instance
      Löst aus:
      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.
      Parameter:
      maxThrows - The maximum number of subsequent exception throws before generation is stopped.
      exceptionType - The exception type to ignore
      Gibt zurück:
      a new arbitrary instance
      Löst aus:
      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.

      Parameter:
      exceptionTypes - The exception types to ignore
      Gibt zurück:
      a new arbitrary instance
      Löst aus:
      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.

      Parameter:
      maxThrows - The maximum number of subsequent exception throws before generation is stopped.
      exceptionTypes - The exception types to ignore
      Gibt zurück:
      a new arbitrary instance
      Löst aus:
      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

      Gibt zurück:
      a new arbitrary instance

    • edgeCases

      @API(status=MAINTAINED, since="1.8.0") default Arbitrary<T> edgeCases(Consumer<EdgeCases.Config<T>> configurator)
      Experimental interface to change generated edge cases of a specific arbitrary.
      Parameter:
      configurator - A consumer that configures deviating edge cases behaviour
      Gibt zurück:
      a new arbitrary instance
      Siehe auch:

    • 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.
      Gibt zurück:
      a new arbitrary instance