Module org.junit.jupiter.params
Package org.junit.jupiter.params.provider

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

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

Since:
5.0
See Also:
CsvFileSource, ArgumentsSource, ParameterizedTest

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    char
    delimiter
    The column delimiter character to use when reading the lines.
    String
    delimiterString
    The column delimiter string to use when reading the lines.
    String
    emptyValue
    The empty value to use when reading the lines.
    boolean
    ignoreLeadingAndTrailingWhitespace
    Identifies whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.
    int
    maxCharsPerColumn
    The maximum characters of per CSV column allowed.
    String[]
    nullValues
    A list of strings that should be interpreted as null references.
    String
    textBlock
    The CSV lines to use as the source of arguments, supplied as a single text block; must not be empty.
    String[]
    value
    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(). Any line beginning with a # symbol will be interpreted as a comment and will be ignored.

      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:
      textBlock()
      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(). Any line beginning with a # symbol will be interpreted as a comment and will be ignored.

      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:
      value()
      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