Module org.junit.jupiter.params
Package org.junit.jupiter.params.provider

Annotation Interface FieldSource

@Target({ANNOTATION_TYPE,METHOD}) @Retention(RUNTIME) @Documented @API(status=EXPERIMENTAL, since="5.11") @ArgumentsSource(org.junit.jupiter.params.provider.FieldArgumentsProvider.class) public @interface FieldSource
@FieldSource is an ArgumentsSource which provides access to values of fields of the class in which this annotation is declared or from static fields in external classes referenced by fully qualified field name.

Each field must be able to supply 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 @ParameterizedTest method.

In this context, a "stream" is anything that JUnit can reliably convert to a Stream; however, the actual concrete field type can take on many forms. Generally speaking this translates to a Collection, an Iterable, a Supplier of a stream (Stream, DoubleStream, LongStream, or IntStream), a Supplier of an Iterator, an array of objects, or an array of primitives. Each set of "arguments" within the "stream" can be supplied as an instance of Arguments, an array of objects (for example, Object[], String[], etc.), or a single value if the parameterized test method accepts a single argument.

In contrast to the supported return types for @MethodSource factory methods, the value of a @FieldSource field cannot be an instance of Stream, DoubleStream, LongStream, IntStream, or Iterator, since the values of such types are consumed the first time they are processed. However, if you wish to use one of these types, you can wrap it in a Supplier — for example, Supplier<IntStream>.

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 Supplier<Stream<Object[]>> objectArrayStreamSupplier field: 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 Supplier<Stream<int[][]>> twoDimensionalIntArrayStreamSupplier and Supplier<Stream<Object[][]>> twoDimensionalObjectArrayStreamSupplier fields: the @ParameterizedTest methods for those fields accept individual int[][] and Object[][] arguments, respectively.

Examples

The following table displays compatible method signatures for parameterized test methods and their corresponding @FieldSource fields.

Compatible method signatures and field declarations
@ParameterizedTest method@FieldSource field
void test(String)static List<String> listOfStrings
void test(String)static String[] arrayOfStrings
void test(int)static int[] intArray
void test(int[])static int[][] twoDimensionalIntArray
void test(String, String)static String[][] twoDimensionalStringArray
void test(String, int)static Object[][] twoDimensionalObjectArray
void test(int)static Supplier<IntStream> intStreamSupplier
void test(String)static Supplier<Stream<String>> stringStreamSupplier
void test(String, int)static Supplier<Stream<Object[]>> objectArrayStreamSupplier
void test(String, int)static Supplier<Stream<Arguments>> argumentsStreamSupplier
void test(int[])static Supplier<Stream<int[]>> intArrayStreamSupplier
void test(int[][])static Supplier<Stream<int[][]>> twoDimensionalIntArrayStreamSupplier
void test(Object[][])static Supplier<Stream<Object[][]>> twoDimensionalObjectArrayStreamSupplier

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

Since:
5.11
See Also:

  • Optional Element Summary

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

  • Element Details

    • value

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

      Fields in external classes must be referenced by fully qualified field name — for example, "com.example.WebUtils#httpMethodNames" or "com.example.TopLevelClass$NestedClass#numbers" for a field in a static nested class.

      If no field names are declared, a field within the test class that has the same name as the test method will be used as the field by default.

      For further information, see the class-level Javadoc.

      Default:
      {}