Package net.jqwik.api

Interface Arbitrary<T>

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default java.util.Optional<java.util.stream.Stream<T>> allValues()
      Create optional stream of all possible values this arbitrary could generate.
      default <A> StreamableArbitrary<T,​A> array​(java.lang.Class<A> arrayClass)
      Create a new arbitrary of type T[] using the existing arbitrary for generating the elements of the array.
      default Arbitrary<java.lang.Object> asGeneric()
      Sometimes simplifies test writing
      default Arbitrary<java.util.List<T>> collect​(java.util.function.Predicate<java.util.List<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.
      EdgeCases<T> edgeCases()  
      default java.util.Optional<ExhaustiveGenerator<T>> exhaustive()
      Create the exhaustive generator for an arbitrary using the maximum allowed number of generated samples.
      default java.util.Optional<ExhaustiveGenerator<T>> exhaustive​(long maxNumberOfSamples)
      Create the exhaustive generator for an arbitrary.
      default Arbitrary<T> filter​(java.util.function.Predicate<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​(java.util.function.Function<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​(java.util.function.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 Arbitrary<T> ignoreException​(java.lang.Class<? extends java.lang.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> 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<T> injectNull​(double nullProbability)
      Create a new arbitrary of the same type but inject null values with a probability of nullProbability.
      default boolean isUnique()
      All arbitraries whose base generator is supposed to produce no duplicates should return true.
      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​(java.util.function.Function<T,​U> mapper)
      Create a new arbitrary of type U that maps the values of the original arbitrary using the mapper function.
      default Arbitrary<java.util.Optional<T>> optional()
      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 java.util.stream.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> unique()
      Create a new arbitrary of the same type T that creates and shrinks the original arbitrary but will never generate the same value twice.

    • Method Detail

      • generator

        RandomGenerator<T> generator​(int genSize)
        Create the random generator for an arbitrary
        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

      • asGeneric

        @API(status=INTERNAL)
default Arbitrary<java.lang.Object> asGeneric()
        Sometimes simplifies test writing
        Returns:
        The same instance but with type Arbitrary<Object>

      • isUnique

        @API(status=INTERNAL)
default boolean isUnique()
        All arbitraries whose base generator is supposed to produce no duplicates should return true.
        Returns:
        true if base genator is supposed to produce no duplicates

      • exhaustive

        @API(status=INTERNAL)
default java.util.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 java.util.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.

      • edgeCases

        @API(status=EXPERIMENTAL,
     since="1.3.0")
EdgeCases<T> edgeCases()

      • allValues

        default java.util.Optional<java.util.stream.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​(java.util.function.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.
        Parameters:
        action - the consumer function to be invoked for each value
        Throws:
        java.lang.AssertionError - if exhaustive generation is not possible

      • filter

        default Arbitrary<T> filter​(java.util.function.Predicate<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.
        Returns:
        a new arbitrary instance
        Throws:
        JqwikException - if filtering will fail to come up with a value after 10000 tries

      • map

        default <U> Arbitrary<U> map​(java.util.function.Function<T,​U> mapper)
        Create a new arbitrary of type U that maps the values of the original arbitrary using the mapper function.
        Returns:
        a new arbitrary instance

      • flatMap

        default <U> Arbitrary<U> flatMap​(java.util.function.Function<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.
        Returns:
        a new arbitrary instance

      • injectNull

        default Arbitrary<T> injectNull​(double nullProbability)
        Create a new arbitrary of the same type but inject null values with a probability of nullProbability.
        Returns:
        a new arbitrary instance

      • unique

        default Arbitrary<T> unique()
        Create a new arbitrary of the same type T that creates and shrinks the original arbitrary but will never generate the same value twice.

        Uniqueness is only held up for a single use of this arbitrary. If the same arbitrary instance is used in several places, e.g. for creating several lists, the different lists may share values between them.

        Returns:
        a new arbitrary instance
        Throws:
        JqwikException - if filtering will fail to come up with a value after 10000 tries

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

      • 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> StreamableArbitrary<T,​A> array​(java.lang.Class<A> arrayClass)
        Create a new arbitrary of type T[] using the existing arbitrary for generating the elements of the array.
        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<java.util.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 also generates Optional.empty() values with a probability of 0.05 (i.e. 1 in 20).

        Returns:
        a new arbitrary instance

      • collect

        @API(status=MAINTAINED,
     since="1.3.0")
default Arbitrary<java.util.List<T>> collect​(java.util.function.Predicate<java.util.List<T>> until)
        Create a new arbitrary of type List<T> by adding elements of type T until condition until is fulfilled.
        Returns:
        a new arbitrary instance

      • sampleStream

        @API(status=MAINTAINED,
     since="1.3.0")
default java.util.stream.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=EXPERIMENTAL,
     since="1.3.1")
default Arbitrary<T> ignoreException​(java.lang.Class<? extends java.lang.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

      • dontShrink

        @API(status=EXPERIMENTAL,
     since="1.3.2")
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