CsvSource

```
@Target(value={ANNOTATION_TYPE,METHOD})
 @Retention(value=RUNTIME)
 @Documented
 @API(status=STABLE,
     since="5.7")
 @ArgumentsSource(value=CsvArgumentsProvider.class)
public @interface CsvSource
```
@CsvSource is an ArgumentsSource which reads comma-separated values (CSV) from one or more CSV records supplied via the value() attribute or textBlock() attribute.
The supplied values will be provided as arguments to the annotated @ParameterizedTest method.
The column delimiter (which defaults to a comma (,)) can be customized via either delimiter() or delimiterString().
By default, @CsvSource uses a single quote (') as its quote character, but this can be changed via quoteCharacter(). See the 'lemon, lime' examples in the documentation for the value() and textBlock() attributes. 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.
In general, CSV records should not contain explicit newlines (\n) unless they are placed within quoted strings. Note that CSV records supplied via textBlock() will implicitly contain newlines at the end of each physical line within the text block. Thus, if a CSV column wraps across a new line in a text block, the column must be a quoted string.

Since:

5.0

See Also:

CsvFileSource, ArgumentsSource, ParameterizedTest

Optional Element Summary

Optional Elements
Modifier and Type	Optional Element and Description
`char`	`delimiter` The column delimiter character to use when reading the records.
`java.lang.String`	`delimiterString` The column delimiter string to use when reading the records.
`java.lang.String`	`emptyValue` The empty value to use when reading the records.
`boolean`	`ignoreLeadingAndTrailingWhitespace` Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.
`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.
`char`	`quoteCharacter` The quote character to use for quoted strings.
`java.lang.String`	`textBlock` The CSV records to use as the source of arguments, supplied as a single text block; must not be empty.
`boolean`	`useHeadersInDisplayName` Configures whether the first CSV record should be treated as header names for columns.
`java.lang.String[]`	`value` The CSV records to use as the source of arguments; must not be empty.

- Element Detail
  - value
```
public abstract java.lang.String[] value
```
    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()).
    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()
    
    Default:
    
    {}
- - textBlock
```
@API(status=STABLE,
     since="5.10")
public abstract java.lang.String 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 15 or higher. 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 hash tag (#) will be treated as a comment and ignored. Note, however, that the # symbol 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) {
     // ...
 }
```
    Since:
    
    5.8.1
    
    See Also:
    
    value(), quoteCharacter()
    
    Default:
    
    ""
- - useHeadersInDisplayName
```
@API(status=STABLE,
     since="5.10")
public abstract 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}")
 @CsvSource(useHeadersInDisplayName = true, textBlock = """
     FRUIT,         RANK
     apple,         1
     banana,        2
     'lemon, lime', 0xF1
     strawberry,    700_000
     """)
 void test(String fruit, int rank) {
     // ...
 }
```
    Since:
    
    5.8.2
    
    Default:
    
    false
- - quoteCharacter
```
@API(status=STABLE,
     since="5.10")
public abstract char quoteCharacter
```
    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().
    
    Since:
    
    5.8.2
    
    See Also:
    
    textBlock()
    
    Default:
    
    39
- - delimiter
```
public abstract char delimiter
```
    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.
    
    Default:
    
    0
- - delimiterString
```
public abstract java.lang.String delimiterString
```
    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
    
    Default:
    
    ""
- - emptyValue
```
public abstract java.lang.String emptyValue
```
    The empty value to use when reading the records.
    This value replaces quoted empty strings read from the input.
    Defaults to "".
    
    Since:
    
    5.5
    
    Default:
    
    ""
- - nullValues
```
public abstract 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")
public abstract int maxCharsPerColumn
```
    The maximum number of characters allowed per CSV column.
    Must be a positive number.
    Defaults to 4096.
    
    Since:
    
    5.7
    
    Default:
    
    4096
- - ignoreLeadingAndTrailingWhitespace
```
@API(status=STABLE,
     since="5.10")
public abstract boolean ignoreLeadingAndTrailingWhitespace
```
    Controls whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.
    Defaults to true.
    
    Since:
    
    5.8
    
    Default:
    
    true

Annotation Type CsvSource

Optional Element Summary

Element Detail

value

Example

textBlock

Example

useHeadersInDisplayName

Example

quoteCharacter

delimiter

delimiterString

emptyValue

nullValues

maxCharsPerColumn

ignoreLeadingAndTrailingWhitespace