public @Interface CsvSource

The character used to denote comments in a text block.

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

The column delimiter character to use when reading the records.

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

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

The column delimiter string to use when reading the records.

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

The empty value to use when reading the records.

This value replaces quoted empty strings read from the input.

Defaults to "".

Since

5.5

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

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

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

The quote character to use for quoted strings.

Defaults to a single quote (').

You may change the quote character to anything that makes sense for your use case; however, the primary use case is to allow you to use double quotes in textBlock.

Annotations

@API

status:STABLE

since:5.10

Since

5.8.2

See Also

textBlock

The CSV records to use as the source of arguments, supplied as a single text block; must not be empty.

Defaults to an empty string. You therefore must supply CSV content via this attribute or the value attribute.

Text block syntax is supported by various languages on the JVM including Java SE. If text blocks are not supported, you should declare your CSV content via the value attribute.

Each record in the text block corresponds to a record in a CSV file and will be split using the specified delimiter or delimiterString. Note that the first record may optionally be used to supply CSV headers (see useHeadersInDisplayName).

In contrast to CSV records supplied via value, a text block can contain comments. Any line beginning with a commentCharacter will be treated as a comment and ignored. 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. It is therefore recommended that the closing text block delimiter """ be placed either at the end of the last line of input or on the following line, vertically aligned with the rest of the input (as can be seen in the example below).

Java's text block feature automatically removes incidental whitespace when the code is compiled. However, other JVM languages such as Groovy and Kotlin do not. Thus, if you are using a programming language other than Java and your text block contains comments or new lines within quoted strings, you will need to ensure that there is no leading whitespace within your text block.

Example

@ParameterizedTest
@CsvSource(quoteCharacter = '"', textBlock = """
    # FRUIT,       RANK
    apple,         1
    banana,        2
    "lemon, lime", 0xF1
    strawberry,    700_000
    """)
void test(String fruit, int rank) {
    // ...
}

Annotations

@API

status:STABLE

since:5.10

Since

5.8.1

See Also

value, quoteCharacter

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}")
@CsvSource(useHeadersInDisplayName = true, textBlock = """
    FRUIT,         RANK
    apple,         1
    banana,        2
    'lemon, lime', 0xF1
    strawberry,    700_000
    """)
void test(String fruit, int rank) {
    // ...
}

Annotations

@API

status:STABLE

since:5.10

Since

5.8.2

The CSV records to use as the source of arguments; must not be empty.

Defaults to an empty array. You therefore must supply CSV content via this attribute or the textBlock attribute.

Each value corresponds to a record in a CSV file and will be split using the specified delimiter or delimiterString. Note that the first value may optionally be used to supply CSV headers (see useHeadersInDisplayName). Moreover, each specified value must not be blank.

If text block syntax is supported by your programming language, you may find it more convenient to declare your CSV content via the textBlock attribute.

Example

@ParameterizedTest
@CsvSource({
    "apple,         1",
    "banana,        2",
    "'lemon, lime', 0xF1",
    "strawberry,    700_000"
})
void test(String fruit, int rank) {
    // ...
}

See Also

textBlock