JUnit 6.0.1 · org.junit.jupiter.params.provider.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 commentCharacter 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.

The line separator is detected automatically, meaning that any of "\r", "\n", or "\r\n" is treated as a line separator.

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.

Note that delimiter (or delimiterString), quoteCharacter, and commentCharacter are treated as control characters and must all be distinct.

Inheritance

This annotation is inherited to subclasses.

Method Summary

Modifier and Type	Method and Description
public char	commentCharacter() The character used to denote comments when reading the CSV files.
public char	delimiter() The column delimiter character to use when reading the CSV files.
public String	delimiterString() The column delimiter string to use when reading the CSV files.
public String	emptyValue() The empty value to use when reading the CSV files.
public String	encoding() The encoding to use when reading the CSV files; must be a valid charset.
public String[]	files() The CSV files to use as the sources of arguments; must not be empty unless `resources` is non-empty.
public boolean	ignoreLeadingAndTrailingWhitespace() Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.
public int	maxCharsPerColumn() The maximum number of characters allowed per CSV column.
public String[]	nullValues() A list of strings that should be interpreted as `null` references.
public int	numLinesToSkip() The number of lines to skip when reading the CSV files.
public char	quoteCharacter() The quote character to use for quoted strings.
public String[]	resources() The CSV classpath resources to use as the sources of arguments; must not be empty unless `files` is non-empty.
public boolean	useHeadersInDisplayName() Configures whether the first CSV record should be treated as header names for columns.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

commentCharacter back to summary

commentCharacter	back to summary
public char commentCharacter() The character used to denote comments when reading the CSV files. Any line that begins with this character will be treated as a comment and ignored during parsing. Note that there is one exception to this rule: if the comment character appears within a quoted field, it loses its special meaning. The comment character must be the first character on the line without any leading whitespace. Defaults to `'#'`. Annotations @API status:EXPERIMENTAL since:6.0.1 Since 6.0.1

public char commentCharacter()

The character used to denote comments when reading the CSV files.

Any line that begins with this character will be treated as a comment and ignored during parsing. Note that there is one exception to this rule: if the comment character appears within a quoted field, it loses its special meaning.

The comment character must be the first character on the line without any leading whitespace.

Defaults to '#'.

Annotations

@API
status:EXPERIMENTAL
since:6.0.1

Since

6.0.1

delimiter back to summary

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

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

delimiterString back to summary

delimiterString	back to summary
public 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

public 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

emptyValue back to summary

emptyValue	back to summary
public 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

public 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

encoding back to summary

encoding	back to summary
public String encoding() The encoding to use when reading the CSV files; must be a valid charset. Defaults to `"UTF-8"`. See Also `java.nio.charset.StandardCharsets`

public String encoding()

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

Defaults to "UTF-8".

See Also: java.nio.charset.StandardCharsets

files	back to summary
public String[] files() The CSV files to use as the sources of arguments; must not be empty unless `resources` is non-empty.

ignoreLeadingAndTrailingWhitespace back to summary

ignoreLeadingAndTrailingWhitespace	back to summary
public boolean ignoreLeadingAndTrailingWhitespace() Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored. Whitespace refers to characters with Unicode code points less than or equal to `U+0020`, as defined by `String#trim()`. Defaults to `true`. Annotations @API status:STABLE since:5.10 Since 5.8

public boolean ignoreLeadingAndTrailingWhitespace()

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

Whitespace refers to characters with Unicode code points less than or equal to U+0020, as defined by String#trim().

Defaults to true.

Annotations

@API
status:STABLE
since:5.10

Since

5.8

maxCharsPerColumn back to summary

maxCharsPerColumn	back to summary
public 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`. Annotations @API status:STABLE since:5.10 Since 5.7

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

Annotations

@API
status:STABLE
since:5.10

Since

5.7

nullValues back to summary

nullValues	back to summary
public 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

public 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

numLinesToSkip back to summary

numLinesToSkip	back to summary
public 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

public 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

quoteCharacter back to summary

quoteCharacter	back to summary
public 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. Annotations @API status:STABLE since:5.10 Since 5.8.2

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

Annotations

@API
status:STABLE
since:5.10

Since

5.8.2

resources	back to summary
public String[] resources() The CSV classpath resources to use as the sources of arguments; must not be empty unless `files` is non-empty.

useHeadersInDisplayName back to summary

useHeadersInDisplayName	back to summary
public 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) { // ... } Annotations @API status:STABLE since:5.10 Since 5.8.2

public 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) {
    // ...
}

Annotations

@API
status:STABLE
since:5.10

Since

5.8.2

public @Interface CsvFileSource

Inheritance

Method Summary

Method Detail

Example