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> ArrayArbitrary<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()  
      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.
      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​(java.util.function.Consumer<EdgeCases.Config<T>> configurator)
      Experimental interface to change generated edge cases of a specific arbitrary.
      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​(int maxMisses, 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> 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 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, 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> 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> ignoreExceptions​(int maxThrows, java.lang.Class<? extends java.lang.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​(java.lang.Class<? extends java.lang.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<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​(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 Arbitrary<java.util.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 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> withoutEdgeCases()
      Create a new arbitrary of type T that will not explicitly generate any edge cases, neither directly or in embedded arbitraries.

    • Method Detail

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

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

      • 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 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.
        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,
                            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.
        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​(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.
        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​(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.
        Type Parameters:
        U - type of resulting object
        Parameters:
        mapper - the function used to map to arbitrary
        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.
        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​(java.lang.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<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 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<java.util.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<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.
        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 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=MAINTAINED,
     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
        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,
                                     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:
        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​(java.lang.Class<? extends java.lang.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,
                                      java.lang.Class<? extends java.lang.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=EXPERIMENTAL,
     since="1.3.9")
default Arbitrary<T> edgeCases​(java.util.function.Consumer<EdgeCases.Config<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:
        EdgeCases.Config

      • withoutEdgeCases

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