Annotation Interface CsvFileSource


@Target({ANNOTATION_TYPE,METHOD}) @Retention(RUNTIME) @Documented @API(status=STABLE, since="5.7") @ArgumentsSource(org.junit.jupiter.params.provider.CsvFileArgumentsProvider.class) public @interface CsvFileSource
@CsvFileSource is an ArgumentsSource which is used to load comma-separated value (CSV) files from one or more classpath resources or files().

The lines of these CSV files will be provided as arguments to the annotated @ParameterizedTest method.

Any line beginning with a # symbol will be interpreted as a comment and will be ignored.

The column delimiter (defaults to comma) can be customized with either delimiter() or delimiterString().

In contrast to the syntax used in @CsvSource, @CsvFileSource uses a double quote (") as its quote character (see the User Guide for examples). 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 CSV files.
    The column delimiter string to use when reading the CSV files.
    The empty value to use when reading the CSV files.
    The encoding to use when reading the CSV files; must be a valid charset.
    The CSV files to use as the sources of arguments; must not be empty unless resources() is non-empty.
    boolean
    Identifies whether leading and trailing whitespace characters of unquoted CSV columns should be ignored.
    The line separator to use when reading the CSV files; must consist of 1 or 2 characters.
    int
    The maximum characters of per CSV column allowed.
    A list of strings that should be interpreted as null references.
    int
    The number of lines to skip when reading the CSV files.
    The CSV classpath resources to use as the sources of arguments; must not be empty unless files() is non-empty.
  • Element Details

    • resources

      String[] resources
      The CSV classpath resources to use as the sources of arguments; must not be empty unless files() is non-empty.
      Default:
      {}
    • files

      String[] files
      The CSV files to use as the sources of arguments; must not be empty unless resources() is non-empty.
      Default:
      {}
    • encoding

      String encoding
      The encoding to use when reading the CSV files; must be a valid charset.

      Defaults to "UTF-8".

      See Also:
      Default:
      "UTF-8"
    • lineSeparator

      String lineSeparator
      The line separator to use when reading the CSV files; must consist of 1 or 2 characters.

      Defaults to "\n".

      Default:
      "\n"
    • 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 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 CSV files.

      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:
      ""
    • numLinesToSkip

      int numLinesToSkip
      The number of lines to skip when reading the CSV files.

      Typically used to skip header lines.

      Defaults to 0.

      Since:
      5.1
      Default:
      0
    • emptyValue

      String emptyValue
      The empty value to use when reading the CSV files.

      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