Module com.github.robtimus.junit.support
Package com.github.robtimus.junit.support.params

Class ArgumentsCombiner

  • public final class ArgumentsCombiner
extends Object
    A class that can combine multiple arguments. Instances of this class can be used in ArgumentsProvider implementations or provider methods to produce argument combinations.

    This class has quite some overlapping functionality with JUnit Pioneer's @CartesianTest. What this class adds that @CartesianTest doesn't is filtering out combinations.

    This class has no special support for enums like @CartesianTest and @EnumSource do. That's because with(Collection) and crossJoin(Collection) can be used in combination with EnumSet. For instance, to exclude some enum constants, use EnumSet.complementOf(EnumSet) in combination with one of the other EnumSet factory methods.

    Note that instances of this class can be considered as builders for Streams of Arguments instances. Like Streams they should not be used more than once.

    Author:
    Rob Spoor
    Since:
    2.0

    • Method Detail

      • withBooleans

        public static ArgumentsCombiner withBooleans​(boolean[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • withChars

        public static ArgumentsCombiner withChars​(char[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • withBytes

        public static ArgumentsCombiner withBytes​(byte[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • withShorts

        public static ArgumentsCombiner withShorts​(short[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • withInts

        public static ArgumentsCombiner withInts​(int[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • withLongs

        public static ArgumentsCombiner withLongs​(long[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • withFloats

        public static ArgumentsCombiner withFloats​(float[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • withDoubles

        public static ArgumentsCombiner withDoubles​(double[] arguments)
        Creates an arguments combiner with an initial set of arguments.

        Note that this method does not support variable arguments; use with(Object...) for that.

        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • with

        public static ArgumentsCombiner with​(Object... arguments)
        Creates an arguments combiner with an initial set of arguments.
        Parameters:
        arguments - The initial set of arguments.
        Returns:
        The created arguments combiner.

      • with

        public static ArgumentsCombiner with​(Collection<?> arguments)
        Creates an arguments combiner with an initial set of arguments.
        Parameters:
        arguments - A collection with the initial set of arguments.
        Returns:
        The created arguments combiner.
        Throws:
        NullPointerException - If the given collection is null.

      • with

        public static ArgumentsCombiner with​(Stream<?> arguments)
        Creates an arguments combiner with an initial set of arguments.
        Parameters:
        arguments - A stream with the initial set of arguments. Note that this stream should not be used outside the returned instance anymore.
        Returns:
        The created arguments combiner.
        Throws:
        NullPointerException - If the given stream is null.

      • crossJoinBooleans

        public ArgumentsCombiner crossJoinBooleans​(boolean[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoinChars

        public ArgumentsCombiner crossJoinChars​(char[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoinBytes

        public ArgumentsCombiner crossJoinBytes​(byte[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoinShorts

        public ArgumentsCombiner crossJoinShorts​(short[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoinInts

        public ArgumentsCombiner crossJoinInts​(int[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoinLongs

        public ArgumentsCombiner crossJoinLongs​(long[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoinFloats

        public ArgumentsCombiner crossJoinFloats​(float[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoinDoubles

        public ArgumentsCombiner crossJoinDoubles​(double[] arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that this method does not support variable arguments; use crossJoin(Object...) for that.

        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoin

        public ArgumentsCombiner crossJoin​(Object... arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.
        Parameters:
        arguments - The arguments to add.
        Returns:
        This object.

      • crossJoin

        public ArgumentsCombiner crossJoin​(Collection<?> arguments)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.
        Parameters:
        arguments - A collection with the arguments to add.
        Returns:
        This object.
        Throws:
        NullPointerException - If the given collection is null.

      • crossJoin

        public ArgumentsCombiner crossJoin​(Supplier<? extends Stream<?>> argumentsProvider)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.
        Parameters:
        argumentsProvider - A supplier for a stream with the arguments to add. Each invocation of the supplier should return a fresh new stream that is not used for any other purposes.
        Returns:
        This object.
        Throws:
        NullPointerException - If the given supplier is null.

      • crossJoin

        public ArgumentsCombiner crossJoin​(ArgumentsProvider argumentsProvider,
                                   ExtensionContext context)
        Adds a set of arguments. The resulting arguments will be a cross join or Cartesian product of the current arguments and the given arguments.

        Note that if the arguments provider throws an exception from its ArgumentsProvider.provideArguments(ExtensionContext) method, that exception will be re-thrown as is but as an unchecked exception.

        Parameters:
        argumentsProvider - The provider for the arguments to add.
        context - The current extension context.
        Returns:
        This object.
        Throws:
        NullPointerException - If the given arguments provider or context is null.

      • excludeCombination

        public ArgumentsCombiner excludeCombination​(Object... values)
        Excludes a combination of values from the current combinations of arguments. If the combination occurs multiple times, all occurrences will be removed.

        Note that the number of values given should be equal to the number of arguments in each current combination. Otherwise, an exception will be thrown when the stream returned by stream() is consumed.

        Parameters:
        values - The combination of values to exclude.
        Returns:
        This object.

      • excludeCombinations

        public ArgumentsCombiner excludeCombinations​(Predicate<? super Object[]> filter)
        Excludes all combinations of arguments that match a filter.
        Parameters:
        filter - The filter to use. Every Arguments instance for which filter.test returns true will be excluded.
        Returns:
        This object.
        Throws:
        NullPointerException - If the given filter is null.

      • stream

        public Stream<? extends Arguments> stream()
        Returns a stream with all combinations of arguments. This stream should be consumed at most once, and afterwards this ArgumentsCombiner should no longer be used.
        Returns:
        A stream with all combinations of arguments.

      • combineArguments

        public static Arguments combineArguments​(Object o1,
                                         Object o2)
        Combines two (sets of) arguments into one Arguments object. If either argument is an instance of Arguments, its elements will be used as separate arguments in the result. Otherwise, the argument is used as a single argument.
        Parameters:
        o1 - The first argument or set of arguments.
        o2 - The second argument or set of arguments.
        Returns:
        The result of combining the two (sets of) arguments.