Package org.junit.jupiter.params

Annotation Type ParameterizedClass

@Target({ANNOTATION_TYPE,TYPE})
@Retention(RUNTIME)
@Documented
@Inherited
@API(status=MAINTAINED,
     since="5.13.3")
@ClassTemplate
@ExtendWith(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).

Lifecycle Methods

If you wish to execute custom code before or after each invocation of the parameterized class, you may declare methods annotated with @BeforeParameterizedClassInvocation or @AfterParameterizedClassInvocation. This can, for example, be useful to initialize the arguments before they are used.

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

This annotation is inherited to subclasses.

Since:

5.13

See Also:

Parameter, BeforeParameterizedClassInvocation, AfterParameterizedClassInvocation, ParameterizedTest, Arguments, ArgumentsProvider, ArgumentsSource, CsvFileSource, CsvSource, EnumSource, MethodSource, ValueSource, ArgumentsAccessor, AggregateWith, ArgumentConverter, ConvertWith

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.
java.lang.String	name	The display name to be used for individual invocations of the parameterized class; never blank or consisting solely of whitespace.

Element Detail

name

java.lang.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

• "{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:

MessageFormat

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:

AutoCloseable

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:

ArgumentCountValidationMode

Default:

org.junit.jupiter.params.ArgumentCountValidationMode.DEFAULT