Package org.junit.jupiter.params.provider

Annotation Type FieldSource

@Target({ANNOTATION_TYPE,METHOD,TYPE})
@Retention(RUNTIME)
@Documented
@Inherited
@Repeatable(FieldSources.class)
@API(status=MAINTAINED,
     since="5.13.3")
@ArgumentsSource(FieldArgumentsProvider.class)
public @interface FieldSource

@FieldSource is a repeatable 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 @ParameterizedClass or @ParameterizedTest.

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 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 (for example, Object[], String[], etc.), or a single value if the parameterized class or test 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>.

If the Supplier 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 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.

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

Inheritance

This annotation is inherited to subclasses.

Since:

5.11

See Also:

MethodSource, Arguments, ArgumentsSource, ParameterizedClass, ParameterizedTest, TestInstance

Optional Element Summary

Optional Elements

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

Element Detail

value

java.lang.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 in case this annotation is applied to a @ParameterizedTest method. For a @ParameterizedClass, at least one field name must be declared explicitly.

For further information, see the class-level Javadoc.

Default:

{}