Annotation Type CsvFileSource
-
@Target({ANNOTATION_TYPE,METHOD}) @Retention(RUNTIME) @Documented @API(status=STABLE, since="5.7") @ArgumentsSource(CsvFileArgumentsProvider.class) public @interface CsvFileSource
@CsvFileSource
is anArgumentsSource
which is used to load comma-separated value (CSV) files from one or more classpathresources()
orfiles()
.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 (seeuseHeadersInDisplayName()
).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 eitherdelimiter()
ordelimiterString()
.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 viaquoteCharacter()
. An empty, quoted value (""
) results in an emptyString
unless theemptyValue()
attribute is set; whereas, an entirely empty value is interpreted as anull
reference. By specifying one or morenullValues()
a custom value can be interpreted as anull
reference (see the User Guide for an example). AnArgumentConversionException
is thrown if the target type of anull
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 thenullValues()
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 totrue
.- Since:
- 5.0
- See Also:
CsvSource
,ArgumentsSource
,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 unlessresources()
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 asnull
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 unlessfiles()
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 unlessfiles()
is non-empty.- Default:
- {}
-
-
-
files
java.lang.String[] files
The CSV files to use as the sources of arguments; must not be empty unlessresources()
is non-empty.- Default:
- {}
-
-
-
useHeadersInDisplayName
@API(status=EXPERIMENTAL, since="5.8.2") 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@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
-
-
-
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 withdelimiterString()
.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 withdelimiter()
.Defaults implicitly to
","
, if neither delimiter attribute is explicitly set.- Since:
- 5.6
- Default:
- ""
-
-
-
nullValues
java.lang.String[] nullValues
A 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:
- {}
-
-