Annotation Interface ParameterizedTest
@ParameterizedTest
is used to signal that the annotated method is a
parameterized test method.
Such methods must not be private
or static
.
Arguments Providers and Sources
@ParameterizedTest
methods must specify at least one
ArgumentsProvider
via @ArgumentsSource
or a corresponding composed annotation (e.g., @ValueSource
,
@CsvSource
, etc.). The provider is responsible for providing a
Stream
of
Arguments
that will be
used to invoke the parameterized test method.
Formal Parameter List
A @ParameterizedTest
method may declare additional parameters at
the end of the method's parameter list to be resolved by other
ParameterResolvers
(e.g., TestInfo
, TestReporter
, etc). Specifically, a
parameterized test method must declare formal parameters according to the
following rules.
- Zero or more indexed arguments must be declared first.
- Zero or more aggregators must be declared next.
- Zero or more arguments supplied by other
ParameterResolver
implementations must be declared last.
In this context, an indexed argument 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
.
Argument Conversion
Method parameters may be annotated with
@ConvertWith
or a corresponding composed annotation to specify an explicit
ArgumentConverter
.
Otherwise, JUnit Jupiter will attempt to perform an implicit
conversion to the target type automatically (see the User Guide for further
details).
Composed Annotations
@ParameterizedTest
may also be used as a meta-annotation in order
to create a custom composed annotation that inherits the semantics
of @ParameterizedTest
.
Inheritance
@ParameterizedTest
methods are inherited from superclasses as long
as they are not overridden according to the visibility rules of the
Java language. Similarly, @ParameterizedTest
methods declared as
interface default methods are inherited as long as they are not
overridden.
Test Execution Order
By default, test methods will be ordered using an algorithm that is
deterministic but intentionally nonobvious. This ensures that subsequent runs
of a test suite execute test methods in the same order, thereby allowing for
repeatable builds. In this context, a test method is any instance
method that is directly annotated or meta-annotated with @Test
,
@RepeatedTest
, @ParameterizedTest
, @TestFactory
, or
@TestTemplate
.
Although true unit tests typically should not rely on the order
in which they are executed, there are times when it is necessary to enforce
a specific test method execution order — for example, when writing
integration tests or functional tests where the sequence of
the tests is important, especially in conjunction with
@TestInstance(Lifecycle.PER_CLASS)
.
To control the order in which test methods are executed, annotate your
test class or test interface with
@TestMethodOrder
and specify
the desired MethodOrderer
implementation.
- Since:
- 5.0
- See Also:
-
Optional Element Summary
Modifier and TypeOptional ElementDescriptionboolean
Configure whether all arguments of the parameterized test that implementAutoCloseable
will be closed after@AfterEach
methods andAfterEachCallback
extensions have been called for the current parameterized test invocation.The display name to be used for individual invocations of the parameterized test; never blank or consisting solely of whitespace. -
Field Summary
Modifier and TypeFieldDescriptionstatic final String
Placeholder for eitherARGUMENT_SET_NAME_PLACEHOLDER
orARGUMENTS_WITH_NAMES_PLACEHOLDER
, depending on whether the current set of arguments was created viaargumentSet()
:{argumentSetNameOrArgumentsWithNames}
.static final String
Placeholder for the name of the argument set for the current invocation of a@ParameterizedTest
method:{argumentSetName}
.static final String
Placeholder for the complete, comma-separated arguments list of the current invocation of a@ParameterizedTest
method:{arguments}
static final String
Placeholder for the complete, comma-separated named arguments list of the current invocation of a@ParameterizedTest
method:{argumentsWithNames}
static final String
Default display name pattern for the current invocation of a@ParameterizedTest
method: "[{index}] {argumentSetNameOrArgumentsWithNames}"static final String
static final String
Placeholder for the current invocation index of a@ParameterizedTest
method (1-based):{index}
-
Field Details
-
DISPLAY_NAME_PLACEHOLDER
- Since:
- 5.3
- See Also:
-
INDEX_PLACEHOLDER
Placeholder for the current invocation index of a@ParameterizedTest
method (1-based):{index}
- Since:
- 5.3
- See Also:
-
ARGUMENTS_PLACEHOLDER
Placeholder for the complete, comma-separated arguments list of the current invocation of a@ParameterizedTest
method:{arguments}
- Since:
- 5.3
- See Also:
-
ARGUMENTS_WITH_NAMES_PLACEHOLDER
Placeholder for the complete, comma-separated named arguments list of the current invocation of a@ParameterizedTest
method:{argumentsWithNames}
Argument names will be retrieved via the
Parameter.getName()
API if the byte code contains parameter names — for example, if the code was compiled with the-parameters
command line argument forjavac
.- Since:
- 5.6
- See Also:
-
ARGUMENT_SET_NAME_PLACEHOLDER
Placeholder for the name of the argument set for the current invocation of a@ParameterizedTest
method:{argumentSetName}
.This placeholder can be used when the current set of arguments was created via
argumentSet()
.- Since:
- 5.11
- See Also:
-
ARGUMENT_SET_NAME_OR_ARGUMENTS_WITH_NAMES_PLACEHOLDER
@API(status=EXPERIMENTAL, since="5.11") static final String ARGUMENT_SET_NAME_OR_ARGUMENTS_WITH_NAMES_PLACEHOLDERPlaceholder for eitherARGUMENT_SET_NAME_PLACEHOLDER
orARGUMENTS_WITH_NAMES_PLACEHOLDER
, depending on whether the current set of arguments was created viaargumentSet()
:{argumentSetNameOrArgumentsWithNames}
.- Since:
- 5.11
- See Also:
-
DEFAULT_DISPLAY_NAME
Default display name pattern for the current invocation of a@ParameterizedTest
method: "[{index}] {argumentSetNameOrArgumentsWithNames}"Note that the default pattern does not include the display name of the
@ParameterizedTest
method.- Since:
- 5.3
- See Also:
-
-
Element Details
-
name
String nameThe display name to be used for individual invocations of the parameterized test; never blank or consisting solely of whitespace.Defaults to
"{default_display_name}"
.If the default display name flag (
"{default_display_name}"
) is not overridden, JUnit will:- Look up the "junit.jupiter.params.displayname.default"
configuration parameter and use it if available. The configuration
parameter can be supplied via the
Launcher
API, build tools (e.g., Gradle and Maven), a JVM system property, or the JUnit Platform configuration file (i.e., a file namedjunit-platform.properties
in the root of the class path). Consult the User Guide for further information. - Otherwise,
"[{index}] {argumentSetNameOrArgumentsWithNames}"
will be used.
Supported placeholders
"{displayName}"
"{index}"
"{argumentSetName}"
"{arguments}"
"{argumentsWithNames}"
"{argumentSetNameOrArgumentsWithNames}"
"{0}"
,"{1}"
, etc.: an individual argument (0-based)
For the latter, you may use
MessageFormat
patterns to customize formatting (for example,{0,number,#.###}
). Please note that the original arguments are passed when formatting, regardless of any implicit or explicit argument conversions.Note that
"{default_display_name}"
is a flag rather than a placeholder.- See Also:
- Default:
"{default_display_name}"
- Look up the "junit.jupiter.params.displayname.default"
configuration parameter and use it if available. The configuration
parameter can be supplied via the
-
autoCloseArguments
Configure whether all arguments of the parameterized test that implementAutoCloseable
will be closed after@AfterEach
methods andAfterEachCallback
extensions have been called for the current parameterized test invocation.Defaults to
true
.WARNING: if an argument that implements
AutoCloseable
is reused for multiple invocations of the same parameterized test method, you must setautoCloseArguments
tofalse
to ensure that the argument is not closed between invocations.- Since:
- 5.8
- See Also:
- Default:
true
-