Package org.junit.jupiter.params.provider

Annotation Type MethodSource

  • @Target({ANNOTATION_TYPE,METHOD,TYPE})
@Retention(RUNTIME)
@Documented
@Inherited
@Repeatable(MethodSources.class)
@API(status=STABLE,
     since="5.7")
@ArgumentsSource(MethodArgumentsProvider.class)
public @interface MethodSource
    @MethodSource is a repeatable ArgumentsSource which provides access to values returned from factory methods of the class in which this annotation is declared or from static factory methods in external classes referenced by fully qualified method name.

    Each factory method must generate a stream of arguments, and each set of "arguments" within the "stream" will be provided as the physical arguments for individual invocations of the annotated org.junit.jupiter.params.ParameterizedClass @ParameterizedClass or @ParameterizedTest. Generally speaking this translates to a Stream of Arguments (i.e., Stream<Arguments>); however, the actual concrete return type can take on many forms. In this context, a "stream" is anything that JUnit can reliably convert into a Stream, such as Stream, DoubleStream, LongStream, IntStream, Collection, Iterator, an array of objects or primitives, or any type that provides an Iterator-returning iterator() method (such as, for example, a kotlin.sequences.Sequence). Each set of "arguments" within the "stream" can be supplied as an instance of Arguments, an array of objects (e.g., Object[], String[], etc.), or a single value if the parameterized test method accepts a single argument.

    If the return type is Stream or one of the primitive streams, JUnit will properly close it by calling BaseStream.close(), making it safe to use a resource such as Files.lines().

    Please note that a one-dimensional array of objects supplied as a set of "arguments" will be handled differently than other types of arguments. Specifically, all of the elements of a one-dimensional array of objects will be passed as individual physical arguments to the @ParameterizedTest method. This behavior can be seen in the table below for the static Stream<Object[]> factory() method: the @ParameterizedTest method accepts individual String and int arguments rather than a single Object[] array. In contrast, any multidimensional array supplied as a set of "arguments" will be passed as a single physical argument to the @ParameterizedTest method without modification. This behavior can be seen in the table below for the static Stream<int[][]> factory() and static Stream<Object[][]> factory() methods: the @ParameterizedTest methods for those factories accept individual int[][] and Object[][] arguments, respectively.

    Examples

    The following table displays compatible method signatures for parameterized test methods and their corresponding factory methods.

    Compatible method signatures and factory methods
    @ParameterizedTest methodFactory method
    void test(int)static int[] factory()
    void test(int)static IntStream factory()
    void test(String)static String[] factory()
    void test(String)static List<String> factory()
    void test(String)static Stream<String> factory()
    void test(String, String)static String[][] factory()
    void test(String, int)static Object[][] factory()
    void test(String, int)static Stream<Object[]> factory()
    void test(String, int)static Stream<Arguments> factory()
    void test(int[])static int[][] factory()
    void test(int[])static Stream<int[]> factory()
    void test(int[][])static Stream<int[][]> factory()
    void test(Object[][])static Stream<Object[][]> factory()

    Factory methods within the test class must be static unless the PER_CLASS test instance lifecycle mode is used; whereas, factory methods in external classes must always be static.

    This behavior and the above examples also apply to parameters of a @ParameterizedClass, regardless whether field or constructor injection is used.

    Factory methods can declare parameters, which will be provided by registered implementations of ParameterResolver.

    Inheritance

    This annotation is inherited to subclasses.

    Since:
    5.0
    See Also:
    FieldSource, Arguments, ArgumentsSource, ParameterizedClass, ParameterizedTest, TestInstance

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.String[] value
      The names of factory methods within the test class or in external classes to use as sources for arguments.

    • Element Detail

      • value

        java.lang.String[] value
        The names of factory methods within the test class or in external classes to use as sources for arguments.

        Factory methods in external classes must be referenced by fully qualified method name — for example, "com.example.StringsProviders#blankStrings" or "com.example.TopLevelClass$NestedClass#classMethod" for a factory method in a static nested class.

        If a factory method accepts arguments that are provided by a ParameterResolver, you can supply the formal parameter list in the qualified method name to disambiguate between overloaded variants of the factory method. For example, "blankStrings(int)" for a local qualified method name or "com.example.StringsProviders#blankStrings(int)" for a fully qualified method name.

        If no factory method names are declared, a method within the test class that has the same name as the test method will be used as the factory method by default in case this annotation is applied to a @ParameterizedTest method. For a @ParameterizedClass, at least one method name must be declared explicitly.

        For further information, see the class-level Javadoc.

        Default:
        {""}