Top Description Methods
org.junit.jupiter.params

public @Interface ParameterizedClass

extends Annotation
Annotations
@Target:ANNOTATION_TYPE, TYPE
@Retention:RUNTIME
@Documented
@Inherited
@API
status:EXPERIMENTAL
since:6.0
@ClassTemplate
@ExtendWith:ParameterizedClassExtension
@SuppressWarnings:exports
Static Imports
org.apiguardian.api.API.Status.EXPERIMENTAL
@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, org.junit.jupiter.params.provider.Arguments, org.junit.jupiter.params.provider.ArgumentsProvider, org.junit.jupiter.params.provider.ArgumentsSource, org.junit.jupiter.params.provider.CsvFileSource, org.junit.jupiter.params.provider.CsvSource, org.junit.jupiter.params.provider.EnumSource, org.junit.jupiter.params.provider.MethodSource, org.junit.jupiter.params.provider.ValueSource, org.junit.jupiter.params.aggregator.ArgumentsAccessor, org.junit.jupiter.params.aggregator.AggregateWith, org.junit.jupiter.params.converter.ArgumentConverter, org.junit.jupiter.params.converter.ConvertWith

Method Summary

Modifier and TypeMethod and Description
public boolean
allowZeroInvocations()

Configure whether zero invocations are allowed for this parameterized class.

public ArgumentCountValidationMode
argumentCountValidation()

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

public boolean
autoCloseArguments()

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

public String
name()

The display name to be used for individual invocations of the parameterized class; never blank or consisting solely of whitespace.

public boolean
quoteTextArguments()

Configure whether to enclose text-based argument values in quotes within display names.

Inherited from java.lang.annotation.Annotation:
annotationTypeequalshashCodetoString

Method Detail

allowZeroInvocationsback to summary
public 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.

argumentCountValidationback to summary
public 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
autoCloseArgumentsback to summary
public 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
java.lang.AutoCloseable
nameback to summary
public 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 java.text.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
java.text.MessageFormat, quoteTextArguments()
quoteTextArgumentsback to summary
public boolean quoteTextArguments()

Configure whether to enclose text-based argument values in quotes within display names.

Defaults to true.

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 in Java strings and characters will be escaped in the quoted text — for example, carriage returns and line feeds will be escaped as \\r and \\n, respectively. In addition, any ISO control character will be represented as a question mark (?) in the quoted text.

For example, given a string argument "line 1\nline 2", the representation in the display name would be "\"line 1\\nline 2\"" (printed as "line 1\nline 2") with the newline character escaped as "\\n". Similarly, given a string argument "\t", the representation in the display name would be "\"\\t\"" (printed as "\t") instead of a blank string or invisible tab character. The same applies for a character argument '\t', whose representation in the display name would be "'\\t'" (printed as '\t').

Please note that original source arguments are quoted when generating a display name, before any implicit or explicit argument conversion is performed. For example, if a parameterized class accepts 3.14 as a float argument that was converted from "3.14" as an input string, "3.14" will be present in the display name instead of 3.14.

Annotations
@API
status:EXPERIMENTAL
since:6.0
Since
6.0
See Also
name()