Annotation 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
@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.
@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
-
Element Details
-
value
String[] valueThe 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:
{}
-