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

Annotation Interface ParameterizedClass

@Target({ANNOTATION_TYPE,TYPE}) @Retention(RUNTIME) @Documented @API(status=EXPERIMENTAL, since="5.13") @ContainerTemplate @ExtendWith(org.junit.jupiter.params.ParameterizedClassExtension.class) public @interface ParameterizedClass
@ParameterizedClass is used to signal that the annotated class is a parameterized test class.

Arguments Providers and Sources

A @ParameterizedClass 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 class.

Field or Constructor Injection

The provided arguments can either be injected into fields annotated with @Parameter or passed to the unique constructor of the parameterized class. 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.

Constructor Injection

A @ParameterizedClass constructor may declare additional parameters at the end of its parameter list to be resolved by other ParameterResolvers (e.g., TestInfo, TestReporter, etc.). Specifically, such a constructor must declare formal parameters according to the following rules.

  1. Zero or more indexed parameters must be declared first.
  2. Zero or more aggregators must be declared next.
  3. Zero or more parameters supplied by other ParameterResolver implementations must be declared last.

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 class at the same index in the constructor's formal parameter list. An aggregator is any parameter of type ArgumentsAccessor or any parameter annotated with @AggregateWith.

Field injection

Fields annotated with @Parameter must be declared according to the following rules.

  1. Zero or more indexed parameters may be declared; each must have a unique index specified in its @Parameter(index) annotation. The index may be omitted if there is only one indexed parameter. If there are at least two indexed parameter declarations, there must be declarations for all indexes from 0 to the largest declared index.
  2. Zero or more aggregators may be declared; each without specifying an index in its @Parameter annotation.
  3. Zero or more other fields may be declared as usual as long as they're not annotated with @Parameter.

In this context, an indexed parameter is an argument for a given index in the Arguments provided by an ArgumentsProvider that is injected into a field annotated with @Parameter(index). An aggregator is any @Parameter-annotated field of type ArgumentsAccessor or any field annotated with @AggregateWith.

Argument Conversion

@Parameter-annotated fields or constructor 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

@ParameterizedClass may also be used as a meta-annotation in order to create a custom composed annotation that inherits the semantics of @ParameterizedClass.

Inheritance

The @ParameterizedClass annotation is not inherited from superclasses but may be (re-)declared on a concrete parameterized class. Parameter-annotated fields from superclasses are detected and used for field injection as if they were declared on the concrete parameterized class.

Since:
5.13
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    allowZeroInvocations
    Configure whether zero invocations are allowed for this parameterized class.
    ArgumentCountValidationMode
    argumentCountValidation
    Configure how the number of arguments provided by an ArgumentsSource are validated.
    boolean
    autoCloseArguments
    Configure whether all arguments of the parameterized class that implement AutoCloseable will be closed after their corresponding invocation.
    String
    name
    The display name to be used for individual invocations of the parameterized class; never blank or consisting solely of whitespace.

  • Element Details

    • name

      String name
      The display name to be used for individual invocations of the parameterized class; 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, "[{index}] {argumentSetNameOrArgumentsWithNames}" will be used.

      Supported placeholders

      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}"

    • autoCloseArguments

      boolean autoCloseArguments
      Configure whether all arguments of the parameterized class that implement AutoCloseable will be closed after their corresponding invocation.

      Defaults to true.

      WARNING: if an argument that implements AutoCloseable is reused for multiple invocations of the same parameterized class, you must set autoCloseArguments to false to ensure that the argument is not closed between invocations.

      See Also:
      Default:
      true

    • allowZeroInvocations

      boolean allowZeroInvocations
      Configure whether zero invocations are allowed for this parameterized class.

      Set this attribute to true if the absence of invocations is expected in some cases and should not cause a test failure.

      Defaults to false.

      Default:
      false

    • argumentCountValidation

      ArgumentCountValidationMode argumentCountValidation
      Configure how the number of arguments provided by an ArgumentsSource are validated.

      Defaults to ArgumentCountValidationMode.DEFAULT.

      When an ArgumentsSource provides more arguments than declared by the parameterized class constructor or Parameter-annotated fields, there might be a bug in the parameterized class or the ArgumentsSource. By default, the additional arguments are ignored. argumentCountValidation allows you to control how additional arguments are handled. The default can be configured via the "junit.jupiter.params.argumentCountValidation" configuration parameter (see the User Guide for details on configuration parameters).

      See Also:
      Default:
      DEFAULT