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

Annotation Interface ParameterizedTest

@Target({ANNOTATION_TYPE,METHOD}) @Retention(RUNTIME) @Documented @API(status=STABLE, since="5.7") @TestTemplate @ExtendWith(org.junit.jupiter.params.ParameterizedTestExtension.class) public @interface ParameterizedTest
@ParameterizedTest is used to signal that the annotated method is a parameterized test method.

Such methods must not be private or static.

Argument 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.

  1. Zero or more indexed arguments must be declared first.
  2. Zero or more aggregators must be declared next.
  3. 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.

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

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    autoCloseArguments
    Configure whether all arguments of the parameterized test that implement AutoCloseable will be closed after @AfterEach methods and AfterEachCallback extensions have been called for the current parameterized test invocation.
    String
    name
    The display name to be used for individual invocations of the parameterized test; never blank or consisting solely of whitespace.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ARGUMENTS_PLACEHOLDER
    Placeholder for the complete, comma-separated arguments list of the current invocation of a @ParameterizedTest method: {arguments}
    static final String
    ARGUMENTS_WITH_NAMES_PLACEHOLDER
    Placeholder for the complete, comma-separated named arguments list of the current invocation of a @ParameterizedTest method: {argumentsWithNames}
    static final String
    DEFAULT_DISPLAY_NAME
    Default display name pattern for the current invocation of a @ParameterizedTest method: "[{index}] {argumentsWithNames}"
    static final String
    DISPLAY_NAME_PLACEHOLDER
    Placeholder for the display name of a @ParameterizedTest method: {displayName}
    static final String
    INDEX_PLACEHOLDER
    Placeholder for the current invocation index of a @ParameterizedTest method (1-based): {index}

  • Field Details

    • DISPLAY_NAME_PLACEHOLDER

      static final String DISPLAY_NAME_PLACEHOLDER
      Placeholder for the display name of a @ParameterizedTest method: {displayName}
      Since:
      5.3
      See Also:

    • INDEX_PLACEHOLDER

      static final String INDEX_PLACEHOLDER
      Placeholder for the current invocation index of a @ParameterizedTest method (1-based): {index}
      Since:
      5.3
      See Also:

    • ARGUMENTS_PLACEHOLDER

      static final String 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

      static final String 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 for javac.

      Since:
      5.6
      See Also:

    • DEFAULT_DISPLAY_NAME

      static final String DEFAULT_DISPLAY_NAME
      Default display name pattern for the current invocation of a @ParameterizedTest method: "[{index}] {argumentsWithNames}"

      Note that the default pattern does not include the display name of the @ParameterizedTest method.

      Since:
      5.3
      See Also:

  • Element Details

    • name

      String name
      The 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 named junit-platform.properties in the root of the class path). Consult the User Guide for further information.
      • Otherwise, the value of the DEFAULT_DISPLAY_NAME constant will be used.

      Supported placeholders

      For the latter, you may use MessageFormat patterns to customize formatting. 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}"

    • autoCloseArguments

      @API(status=STABLE, since="5.10") boolean autoCloseArguments
      Configure whether all arguments of the parameterized test that implement AutoCloseable will be closed after @AfterEach methods and AfterEachCallback 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 set autoCloseArguments to false to ensure that the argument is not closed between invocations.

      Since:
      5.8
      See Also:
      Default:
      true