Parameterized Classes and Tests

Parameterized test methods consume arguments directly from the configured source (see Sources of Arguments) following a one-to-one correlation between argument source index and method parameter index (see examples in @CsvSource). However, a parameterized test method may also choose to aggregate arguments from the source into a single object passed to the method (see Argument Aggregation). Additional arguments may also be provided by a ParameterResolver (e.g., to obtain an instance of TestInfo, TestReporter, etc.). Specifically, a parameterized test method must declare formal parameters according to the following rules.

In this context, an indexed parameter is an argument for a given index in the Arguments provided by an ArgumentsProvider that is passed as an argument to the parameterized method at the same index in the method’s formal parameter list. An aggregator is any parameter of type ArgumentsAccessor or any parameter annotated with @AggregateWith.

Parameterized classes consume arguments directly from the configured source (see Sources of Arguments); either via their unique constructor or via field injection. If a @Parameter-annotated field is declared in the parameterized class or one of its superclasses, field injection will be used. Otherwise, constructor injection will be used.

Other extensions can access the parameters and resolved arguments of a parameterized test or class by retrieving a ParameterInfo object from the Store. Please refer to the Javadoc of ParameterInfo for details.

@ValueSource is one of the simplest possible sources. It lets you specify a single array of literal values and can only be used for providing a single argument per parameterized test invocation.

The following types of literal values are supported by @ValueSource.

For example, the following @ParameterizedTest method will be invoked three times, with the values 1, 2, and 3 respectively.

In order to check corner cases and verify proper behavior of our software when it is supplied bad input, it can be useful to have null and empty values supplied to our parameterized tests. The following annotations serve as sources of null and empty values for parameterized tests that accept a single argument.

If you need to supply multiple varying types of blank strings to a parameterized class or test, you can achieve that using @ValueSource — for example, @ValueSource(strings = {" ", "   ", "\t", "\n"}).

You can also combine @NullSource, @EmptySource, and @ValueSource to test a wider range of null, empty, and blank input. The following example demonstrates how to achieve this for strings.

Making use of the composed @NullAndEmptySource annotation simplifies the above as follows.

@EnumSource provides a convenient way to use Enum constants.

The annotation’s value attribute is optional. When omitted, the declared type of the first parameter is used. The test will fail if it does not reference an enum type. Thus, the value attribute is required in the above example because the method parameter is declared as TemporalUnit, i.e. the interface implemented by ChronoUnit, which isn’t an enum type. Changing the method parameter type to ChronoUnit allows you to omit the explicit enum type from the annotation as follows.

The annotation provides an optional names attribute that lets you specify which constants shall be used, like in the following example.

In addition to names, you can use the from and to attributes to specify a range of constants. The range starts from the constant specified in the from attribute and includes all subsequent constants up to and including the one specified in the to attribute, based on the natural order of the enum constants.

If from and to attributes are omitted, they default to the first and last constants in the enum type, respectively. If all names, from, and to attributes are omitted, all constants will be used. The following example demonstrates how to specify a range of constants.

The @EnumSource annotation also provides an optional mode attribute that enables fine-grained control over which constants are passed to the test method. For example, you can exclude names from the enum constant pool or specify regular expressions as in the following examples.

You can also combine mode with the from, to and names attributes to define a range of constants while excluding specific values from that range as shown below.

@MethodSource allows you to refer to one or more factory methods of the test class or external classes.

Factory methods within the test class must be static unless the test class is annotated with @TestInstance(Lifecycle.PER_CLASS); whereas, factory methods in external classes must always be static.

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 @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, Iterable, an array of objects or primitives, or any type that provides an iterator(): Iterator method (such as, for example, a kotlin.sequences.Sequence). The "arguments" within the stream can be supplied as an instance of Arguments, an array of objects (e.g., Object[]), or a single value if the parameterized class or 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().

If you only need a single parameter, you can return a Stream of instances of the parameter type as demonstrated in the following example.

For a @ParameterizedClass, providing a factory method name via @MethodSource is mandatory. For a @ParameterizedTest, if you do not explicitly provide a factory method name, JUnit Jupiter will search for a factory method with the same name as the current @ParameterizedTest method by convention. This is demonstrated in the following example.

Streams for primitive types (DoubleStream, IntStream, and LongStream) are also supported as demonstrated by the following example.

If a parameterized class or test method declares multiple parameters, you need to return a collection, stream, or array of Arguments instances or object arrays as shown below (see the Javadoc for @MethodSource for further details on supported return types). Note that arguments(Object…​) is a static factory method defined in the Arguments interface. In addition, Arguments.of(Object…​) may be used as an alternative to arguments(Object…​).

An external, static factory method can be referenced by providing its fully qualified method name as demonstrated in the following example.

Factory methods can declare parameters, which will be provided by registered implementations of the ParameterResolver extension API. In the following example, the factory method is referenced by its name since there is only one such method in the test class. If there are several local methods with the same name, parameters can also be provided to differentiate them – for example, @MethodSource("factoryMethod()") or @MethodSource("factoryMethod(java.lang.String)"). Alternatively, the factory method can be referenced by its fully qualified method name, e.g. @MethodSource("example.MyTests#factoryMethod(java.lang.String)").

@FieldSource allows you to refer to one or more fields of the test class or external classes.

Fields within the test class must be static unless the test class is annotated with @TestInstance(Lifecycle.PER_CLASS); whereas, fields in external classes must always be static.

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(): 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 method accepts a single argument.

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 the elements of a one-dimensional array of objects will be passed as individual physical arguments to the @ParameterizedClass or @ParameterizedTest. See the Javadoc for @FieldSource for further details.

For a @ParameterizedClass, providing a field name via @FieldSource is mandatory. For a @ParameterizedTest, if you do not explicitly provide a field name, JUnit Jupiter will search in the test class for a field that has the same name as the current @ParameterizedTest method by convention. This is demonstrated in the following example. This parameterized test method will be invoked twice: with the values "apple" and "banana".

The following example demonstrates how to provide a single explicit field name via @FieldSource. This parameterized test method will be invoked twice: with the values "apple" and "banana".

The following example demonstrates how to provide multiple explicit field names via @FieldSource. This example uses the listOfFruits field from the previous example as well as the additionalFruits field. Consequently, this parameterized test method will be invoked four times: with the values "apple", "banana", "cherry", and "dewberry".

It is also possible to provide a Stream, DoubleStream, IntStream, LongStream, or Iterator as the source of arguments via a @FieldSource field as long as the stream or iterator is wrapped in a java.util.function.Supplier. The following example demonstrates how to provide a Supplier of a Stream of named arguments. This parameterized test method will be invoked twice: with the values "apple" and "banana" and with display names "Apple" and "Banana", respectively.

If a parameterized class or test method declares multiple parameters, the corresponding @FieldSource field must be able to provide a collection, stream supplier, or array of Arguments instances or object arrays as shown below (see the Javadoc for @FieldSource for further details on supported types).

An external, static @FieldSource field can be referenced by providing its fully qualified field name as demonstrated in the following example.

@CsvSource allows you to express argument lists as comma-separated values (i.e., CSV String literals). Each string provided via the value attribute in @CsvSource represents a CSV record and results in one invocation of the parameterized class or test. The first record may optionally be used to supply CSV headers (see the Javadoc for the useHeadersInDisplayName attribute for details and an example).

The default delimiter is a comma (,), but you can use another character by setting the delimiter attribute. Alternatively, the delimiterString attribute allows you to use a String delimiter instead of a single character. However, both delimiter attributes cannot be set simultaneously.

By default, @CsvSource uses a single quote (') as its quote character, but this can be changed via the quoteCharacter attribute. See the 'lemon, lime' value in the example above and in the table below. An empty, quoted value ('') results in an empty String unless the emptyValue attribute is set; whereas, an entirely empty value is interpreted as a null reference. By specifying one or more nullValues, a custom value can be interpreted as a null reference (see the NIL example in the table below). An ArgumentConversionException is thrown if the target type of a null reference is a primitive type.

Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed by default. This behavior can be changed by setting the ignoreLeadingAndTrailingWhitespace attribute to true.

If the programming language you are using supports Java text blocks or equivalent multi-line string literals, you can alternatively use the textBlock attribute of @CsvSource. Each record within a text block represents a CSV record and results in one invocation of the parameterized class or test. The first record may optionally be used to supply CSV headers by setting the useHeadersInDisplayName attribute to true as in the example below.

Using a text block, the previous example can be implemented as follows.

The generated display names for the previous example include the CSV header names.

In contrast to CSV records supplied via the value attribute, a text block can contain comments. Any line beginning with the value of the commentCharacter attribute (# by default) will be treated as a comment and ignored. Note that there is one exception to this rule: if the comment character appears within a quoted field, it loses its special meaning.

The comment character must be the first character on the line without any leading whitespace. It is therefore recommended that the closing text block delimiter (""") be placed either at the end of the last line of input or on the following line, left aligned with the rest of the input (as can be seen in the example below which demonstrates formatting similar to a table).

@CsvFileSource lets you use comma-separated value (CSV) files from the classpath or the local file system. Each record from a CSV file results in one invocation of the parameterized class or test. The first record may optionally be used to supply CSV headers. You can instruct JUnit to ignore the headers via the numLinesToSkip attribute. If you would like for the headers to be used in the display names, you can set the useHeadersInDisplayName attribute to true. The examples below demonstrate the use of numLinesToSkip and useHeadersInDisplayName.

The default delimiter is a comma (,), but you can use another character by setting the delimiter attribute. Alternatively, the delimiterString attribute allows you to use a String delimiter instead of a single character. However, both delimiter attributes cannot be set simultaneously.

The following listing shows the generated display names for the first two parameterized test methods above.

The following listing shows the generated display names for the last parameterized test method above that uses CSV header names.

In contrast to the default syntax used in @CsvSource, @CsvFileSource uses a double quote (") as the quote character by default, but this can be changed via the quoteCharacter attribute. See the "United States of America" value in the example above. An empty, quoted value ("") results in an empty String unless the emptyValue attribute is set; whereas, an entirely empty value is interpreted as a null reference. By specifying one or more nullValues, a custom value can be interpreted as a null reference. An ArgumentConversionException is thrown if the target type of a null reference is a primitive type.

Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed by default. This behavior can be changed by setting the ignoreLeadingAndTrailingWhitespace attribute to true.

@ArgumentsSource can be used to specify a custom, reusable ArgumentsProvider. Note that an implementation of ArgumentsProvider must be declared as either a top-level class or as a static nested class.

If you wish to implement a custom ArgumentsProvider that also consumes an annotation (like built-in providers such as ValueArgumentsProvider or CsvArgumentsProvider), you have the possibility to extend the AnnotationBasedArgumentsProvider class.

Moreover, ArgumentsProvider implementations may declare constructor parameters in case they need to be resolved by a registered ParameterResolver as demonstrated in the following example.

Repeatable annotations provide a convenient way to specify multiple sources from different providers.

Following the above parameterized test, a test case will run for each argument:

The following annotations are repeatable:

JUnit Jupiter supports Widening Primitive Conversion for arguments supplied to a @ParameterizedClass or @ParameterizedTest. For example, a parameterized class or test method annotated with @ValueSource(ints = { 1, 2, 3 }) can be declared to accept not only an argument of type int but also an argument of type long, float, or double.

To support use cases like @CsvSource, JUnit Jupiter provides a number of built-in implicit type converters. The conversion process depends on the declared type of each method parameter.

For example, if a @ParameterizedClass or @ParameterizedTest declares a parameter of type TimeUnit and the actual type supplied by the declared source is a String, the string will be automatically converted into the corresponding TimeUnit enum constant.

String instances are implicitly converted to the following target types.

Instead of relying on implicit argument conversion, you may explicitly specify an ArgumentConverter to use for a certain parameter using the @ConvertWith annotation like in the following example. Note that an implementation of ArgumentConverter must be declared as either a top-level class or as a static nested class.

If the converter is only meant to convert one type to another, you can extend TypedArgumentConverter to avoid boilerplate type checks.

Explicit argument converters are meant to be implemented by test and extension authors. Thus, junit-jupiter-params only provides a single explicit argument converter that may also serve as a reference implementation: JavaTimeArgumentConverter. It is used via the composed annotation JavaTimeConversionPattern.

If you wish to implement a custom ArgumentConverter that also consumes an annotation (like JavaTimeArgumentConverter), you have the possibility to extend the AnnotationBasedArgumentConverter class.

Apart from direct access to the arguments of a @ParameterizedClass or @ParameterizedTest using an ArgumentsAccessor, JUnit Jupiter also supports the usage of custom, reusable aggregators.

To use a custom aggregator, implement the ArgumentsAggregator interface and register it via the @AggregateWith annotation on a compatible parameter of the @ParameterizedClass or @ParameterizedTest. The result of the aggregation will then be provided as an argument for the corresponding parameter when the parameterized test is invoked. Note that an implementation of ArgumentsAggregator must be declared as either a top-level class or as a static nested class.

If you find yourself repeatedly declaring @AggregateWith(MyTypeAggregator.class) for multiple parameterized classes or methods across your codebase, you may wish to create a custom composed annotation such as @CsvToMyType that is meta-annotated with @AggregateWith(MyTypeAggregator.class). The following example demonstrates this in action with a custom @CsvToPerson annotation.

As of JUnit Jupiter 6.0, text-based arguments in display names for parameterized tests are quoted by default. In this context, any CharSequence (such as a String) or Character is considered text. A CharSequence is wrapped in double quotes ("), and a Character is wrapped in single quotes (').

Special characters will be escaped in the quoted text. For example, carriage returns and line feeds will be escaped as \\r and \\n, respectively.

For example, given a string argument "line 1\nline 2", the physical representation in the display name will be "\"line 1\\nline 2\"" which is printed as "line 1\nline 2". Similarly, given a string argument "\t", the physical representation in the display name will be "\"\\t\"" which is printed as "\t" instead of a blank string or invisible tab character. The same applies for a character argument '\t', whose physical representation in the display name would be "'\\t'" which is printed as '\t'.

For a concrete example, if you run the first nullEmptyAndBlankStrings(String text) parameterized test method from the Null and Empty Sources section above, the following display names are generated.

If you run the first testWithCsvSource(String fruit, int rank) parameterized test method from the @CsvSource section above, the following display names are generated.

If you’d like to set a default name pattern for all parameterized classes and tests in your project, you can declare the junit.jupiter.params.displayname.default configuration parameter in the junit-platform.properties file as demonstrated in the following example (see Configuration Parameters for other options).

The display name for a parameterized class or test is determined according to the following precedence rules:

Each invocation of a parameterized test has the same lifecycle as a regular @Test method. For example, @BeforeEach methods will be executed before each invocation. Similar to Dynamic Tests, invocations will appear one by one in the test tree of an IDE. You may at will mix regular @Test methods and @ParameterizedTest methods within the same test class.

You may use ParameterResolver extensions with @ParameterizedTest methods. However, method parameters that are resolved by argument sources need to come first in the parameter list. Since a test class may contain regular tests as well as parameterized tests with different parameter lists, values from argument sources are not resolved for lifecycle methods (e.g. @BeforeEach) and test class constructors.

Each invocation of a parameterized class has the same lifecycle as a regular test class. For example, @BeforeAll methods will be executed once before all invocations and @BeforeEach methods will be executed before each test method invocation. Similar to Dynamic Tests, invocations will appear one by one in the test tree of an IDE.

You may use ParameterResolver extensions with @ParameterizedClass constructors. However, if constructor injection is used, constructor parameters that are resolved by argument sources need to come first in the parameter list. Values from argument sources are not resolved for regular lifecycle methods (e.g. @BeforeEach).

In addition to regular lifecycle methods, parameterized classes may declare @BeforeParameterizedClassInvocation and @AfterParameterizedClassInvocation lifecycle methods that are called once before/after each invocation of the parameterized class. These methods must be static unless the parameterized class is configured to use @TestInstance(Lifecycle.PER_CLASS) (see Test Instance Lifecycle).

These lifecycle methods may optionally declare parameters that are resolved depending on the setting of the injectArguments annotation attribute. If it is set to false, the parameters must be resolved by other registered ParameterResolver extensions. If the attribute is set to true (the default), the method may declare parameters that match the arguments of the parameterized class (see the Javadoc of @BeforeParameterizedClassInvocation and @AfterParameterizedClassInvocation for details). This may, for example, be used to initialize the used arguments as demonstrated by the following example.