Annotation Interface CsvSource


@Target({ANNOTATION_TYPE,METHOD}) @Retention(RUNTIME) @Documented @API(status=STABLE, since="5.7") @ArgumentsSource(org.junit.jupiter.params.provider.CsvArgumentsProvider.class) public @interface CsvSource
@CsvSource is an ArgumentsSource which reads comma-separated values (CSV) from one or more CSV lines supplied via the value() attribute or textBlock() attribute.

The supplied values will be provided as arguments to the annotated @ParameterizedTest method.

The column delimiter (defaults to comma) can be customized with 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.

Since:
5.0
See Also:
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    char
    The column delimiter character to use when reading the lines.
    The column delimiter string to use when reading the lines.
    The empty value to use when reading the lines.
    boolean
    Identifies whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.
    int
    The maximum characters of per CSV column allowed.
    A list of strings that should be interpreted as null references.
    char
    The quote character to use for quoted strings.
    The CSV lines to use as the source of arguments, supplied as a single text block; must not be empty.
    The CSV lines to use as the source of arguments; must not be empty.
  • Element Details

    • value

      String[] value
      The CSV lines to use as the source of arguments; must not be empty.

      Each value corresponds to a line in a CSV file and will be split using the specified delimiter() or delimiterString().

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

      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:
      Default:
      {}
    • textBlock

      @API(status=EXPERIMENTAL, since="5.8.1") String textBlock
      The CSV lines to use as the source of arguments, supplied as a single text block; must not be empty.

      Each line in the text block corresponds to a line in a CSV file and will be split using the specified delimiter() or delimiterString().

      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.

      Example

       @ParameterizedTest
       @CsvSource(textBlock = """
           apple,         1
           banana,        2
           'lemon, lime', 0xF1
           strawberry,    700_000
           """)
       void test(String fruit, int rank) {
           // ...
       }
      Since:
      5.8.1
      See Also:
      Default:
      ""
    • quoteCharacter

      @API(status=EXPERIMENTAL, since="5.8.2") 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:
      Default:
      '\''
    • delimiter

      char delimiter
      The column delimiter character to use when reading the lines.

      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:
      '\u0000'
    • delimiterString

      String delimiterString
      The column delimiter string to use when reading the lines.

      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

      String emptyValue
      The empty value to use when reading the lines.

      This value replaces quoted empty strings read from the input.

      Defaults to "".

      Since:
      5.5
      Default:
      ""
    • nullValues

      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=EXPERIMENTAL, since="5.7") int maxCharsPerColumn
      The maximum characters of per CSV column allowed.

      Must be a positive number.

      Defaults to 4096.

      Since:
      5.7
      Default:
      4096
    • ignoreLeadingAndTrailingWhitespace

      @API(status=EXPERIMENTAL, since="5.8") boolean ignoreLeadingAndTrailingWhitespace
      Identifies whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.

      Defaults to true.

      Since:
      5.8
      Default:
      true