Package org.junit.jupiter.params.provider

Annotation Type CsvFileSource

@Target({ANNOTATION_TYPE,METHOD,TYPE})
@Retention(RUNTIME)
@Documented
@Inherited
@Repeatable(CsvFileSources.class)
@API(status=STABLE,
     since="5.7")
@ArgumentsSource(CsvFileArgumentsProvider.class)
public @interface CsvFileSource

@CsvFileSource is a repeatable ArgumentsSource which is used to load comma-separated value (CSV) files from one or more classpath resources() or files().

The CSV records parsed from these resources and files will be provided as arguments to the annotated @ParameterizedClass or @ParameterizedTest. Note that the first record may optionally be used to supply CSV headers (see useHeadersInDisplayName()).

Any line beginning with a # symbol will be interpreted as a comment and will be ignored.

The column delimiter (which defaults to a comma (,)) can be customized via either delimiter() or delimiterString().

In contrast to the default syntax used in @CsvSource, @CsvFileSource uses a double quote (") as its quote character by default, but this can be changed via quoteCharacter(). An empty, quoted value ("") results in an empty String unless the emptyValue() attribute is set; whereas, an entirely empty value is interpreted as a null reference. By specifying one or more nullValues() a custom value can be interpreted as a null reference (see the User Guide for an example). An ArgumentConversionException is thrown if the target type of a null reference is a primitive type.

NOTE: An unquoted empty value will always be converted to a null reference regardless of any custom values configured via the nullValues() attribute.

Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed by default. This behavior can be changed by setting the ignoreLeadingAndTrailingWhitespace() attribute to true.

Inheritance

This annotation is inherited to subclasses.

Since:

5.0

See Also:

CsvSource, ArgumentsSource, ParameterizedClass, ParameterizedTest

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
char	delimiter	The column delimiter character to use when reading the CSV files.
java.lang.String	delimiterString	The column delimiter string to use when reading the CSV files.
java.lang.String	emptyValue	The empty value to use when reading the CSV files.
java.lang.String	encoding	The encoding to use when reading the CSV files; must be a valid charset.
java.lang.String[]	files	The CSV files to use as the sources of arguments; must not be empty unless resources() is non-empty.
boolean	ignoreLeadingAndTrailingWhitespace	Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.
java.lang.String	lineSeparator	The line separator to use when reading the CSV files; must consist of 1 or 2 characters, typically "\r", "\n", or "\r\n".
int	maxCharsPerColumn	The maximum number of characters allowed per CSV column.
java.lang.String[]	nullValues	A list of strings that should be interpreted as null references.
int	numLinesToSkip	The number of lines to skip when reading the CSV files.
char	quoteCharacter	The quote character to use for quoted strings.
java.lang.String[]	resources	The CSV classpath resources to use as the sources of arguments; must not be empty unless files() is non-empty.
boolean	useHeadersInDisplayName	Configures whether the first CSV record should be treated as header names for columns.

Element Detail

resources

java.lang.String[] resources

The CSV classpath resources to use as the sources of arguments; must not be empty unless files() is non-empty.

Default:

{}

files

java.lang.String[] files

The CSV files to use as the sources of arguments; must not be empty unless resources() is non-empty.

Default:

{}

encoding

java.lang.String encoding

The encoding to use when reading the CSV files; must be a valid charset.

Defaults to "UTF-8".

See Also:

StandardCharsets

Default:

"UTF-8"

lineSeparator

java.lang.String lineSeparator

The line separator to use when reading the CSV files; must consist of 1 or 2 characters, typically "\r", "\n", or "\r\n".

Defaults to "\n".

Default:

"\n"

useHeadersInDisplayName

@API(status=STABLE,
     since="5.10")
boolean useHeadersInDisplayName

Configures whether the first CSV record should be treated as header names for columns.

When set to true, the header names will be used in the generated display name for each @ParameterizedClass or @ParameterizedTest invocation. When using this feature, you must ensure that the display name pattern for @ParameterizedClass or @ParameterizedTest includes "{arguments}" instead of "{argumentsWithNames}" as demonstrated in the example below.

Defaults to false.

Example

 @ParameterizedTest(name = "[{index}] {arguments}")
 @CsvFileSource(resources = "fruits.csv", useHeadersInDisplayName = true)
 void test(String fruit, int rank) {
     // ...
 }

Since:

5.8.2

Default:

false

quoteCharacter

@API(status=STABLE,
     since="5.10")
char quoteCharacter

The quote character to use for quoted strings.

Defaults to a double quote (").

You may change the quote character to anything that makes sense for your use case.

Since:

5.8.2

Default:

'\"'

delimiter

char delimiter

The column delimiter character to use when reading the CSV files.

This is an alternative to delimiterString() and cannot be used in conjunction with delimiterString().

Defaults implicitly to ',', if neither delimiter attribute is explicitly set.

Default:

'\u0000'

delimiterString

java.lang.String delimiterString

The column delimiter string to use when reading the CSV files.

This is an alternative to delimiter() and cannot be used in conjunction with delimiter().

Defaults implicitly to ",", if neither delimiter attribute is explicitly set.

Since:

5.6

Default:

""

numLinesToSkip

int numLinesToSkip

The number of lines to skip when reading the CSV files.

Typically used to skip header lines.

Defaults to 0.

Since:

5.1

Default:

0

emptyValue

java.lang.String emptyValue

The empty value to use when reading the CSV files.

This value replaces quoted empty strings read from the input.

Defaults to "".

Since:

5.5

Default:

""

nullValues

java.lang.String[] nullValues

A list of strings that should be interpreted as null references.

For example, you may wish for certain values such as "N/A" or "NIL" to be converted to null references.

Please note that unquoted empty values will always be converted to null references regardless of the value of this nullValues attribute; whereas, a quoted empty string will be treated as an emptyValue().

Defaults to {}.

Since:

5.6

Default:

{}

maxCharsPerColumn

@API(status=STABLE,
     since="5.10")
int maxCharsPerColumn

The maximum number of characters allowed per CSV column.

Must be a positive number or -1 to allow an unlimited number of characters.

Defaults to 4096.

Since:

5.7

Default:

4096

ignoreLeadingAndTrailingWhitespace

@API(status=STABLE,
     since="5.10")
boolean ignoreLeadingAndTrailingWhitespace

Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.

Defaults to true.

Since:

5.8

Default:

true