Annotation 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 @ParameterizedTest
method. 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
.
- Since:
- 5.0
- See Also:
-
Optional Element Summary
Modifier and TypeOptional ElementDescriptionchar
The column delimiter character to use when reading the CSV files.The column delimiter string to use when reading the CSV files.The empty value to use when reading the CSV files.The encoding to use when reading the CSV files; must be a valid charset.String[]
The CSV files to use as the sources of arguments; must not be empty unlessresources()
is non-empty.boolean
Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.The line separator to use when reading the CSV files; must consist of 1 or 2 characters, typically"\r"
,"\n"
, or"\r\n"
.int
The maximum number of characters allowed per CSV column.String[]
A list of strings that should be interpreted asnull
references.int
The number of lines to skip when reading the CSV files.char
The quote character to use for quoted strings.String[]
The CSV classpath resources to use as the sources of arguments; must not be empty unlessfiles()
is non-empty.boolean
Configures whether the first CSV record should be treated as header names for columns.
-
Element Details
-
resources
String[] resourcesThe CSV classpath resources to use as the sources of arguments; must not be empty unlessfiles()
is non-empty.- Default:
{}
-
files
String[] filesThe CSV files to use as the sources of arguments; must not be empty unlessresources()
is non-empty.- Default:
{}
-
encoding
String encodingThe encoding to use when reading the CSV files; must be a valid charset.Defaults to
"UTF-8"
.- See Also:
- Default:
"UTF-8"
-
lineSeparator
String lineSeparatorThe 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
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@ParameterizedTest
method invocation. When using this feature, you must ensure that the display name pattern for@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
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 delimiterThe column delimiter character to use when reading the CSV files.This is an alternative to
delimiterString()
and cannot be used in conjunction withdelimiterString()
.Defaults implicitly to
','
, if neither delimiter attribute is explicitly set.- Default:
'\u0000'
-
delimiterString
String delimiterStringThe column delimiter string to use when reading the CSV files.This is an alternative to
delimiter()
and cannot be used in conjunction withdelimiter()
.Defaults implicitly to
","
, if neither delimiter attribute is explicitly set.- Since:
- 5.6
- Default:
""
-
numLinesToSkip
int numLinesToSkipThe 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
String emptyValueThe 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
String[] nullValuesA list of strings that should be interpreted asnull
references.For example, you may wish for certain values such as
"N/A"
or"NIL"
to be converted tonull
references.Please note that unquoted empty values will always be converted to
null
references regardless of the value of thisnullValues
attribute; whereas, a quoted empty string will be treated as anemptyValue()
.Defaults to
{}
.- Since:
- 5.6
- Default:
{}
-
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
Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.Defaults to
true
.- Since:
- 5.8
- Default:
true
-