How does JUnit 5's @CsvFileSource load its data, what is the difference between its resources and files attributes, and what is numLinesToSkip for?

## What it is `@CsvFileSource` supplies arguments to a `@ParameterizedTest` from one or more CSV files. Semantically it is identical to `@CsvSource` — each data line becomes one invocation, columns are split on a delimiter and bound positionally to the test method's parameters, and each column is converted from text to the declared parameter type. The only difference is *where the table lives*. ```java @ParameterizedTest @CsvFileSource(resources = "/tax-brackets.csv", numLinesToSkip = 1) void computesTax(int income, String region, BigDecimal expected) { assertEquals(expected, TaxCalculator.of(region).tax(income)); } ``` ## resources versus files These are two different lookup mechanisms and choosing wrongly is the classic cause of "works in my IDE, fails in CI". **`resources`** goes through the classpath. Put the file under `src/test/resources` and the build tool copies it into the test classpath; the annotation then finds it wherever the tests run — locally, in CI, from a packaged test JAR. Path rules follow normal classpath-resource semantics: - `"/data/users.csv"` — leading slash, absolute from the classpath root. - `"users.csv"` — no leading slash, resolved **relative to the package of the test class**, so a test in `com.acme.billing` looks for `com/acme/billing/users.csv`. Most teams use absolute paths to avoid the surprise in the second rule. **`files`** goes through the filesystem. A relative path is resolved against the JVM's working directory, which is not the same in an IDE run, a Gradle run and a Maven run. Use it only for data that is deliberately outside the build — a generated fixture, a large corpus checked out separately, a path supplied by the environment. Otherwise prefer `resources`. Both attributes are arrays, so you can list several sources; their rows are concatenated in order, and each file has its own `numLinesToSkip` applied. If a named resource or file does not exist, the test fails with a clear "could not find" style error rather than silently running zero invocations. ## numLinesToSkip Real CSV files usually start with a header row: `income,region,expectedTax`. That line is not data — attempting to convert `income` into an `int` would fail. `numLinesToSkip` tells JUnit how many leading lines to discard, and the default is `0`, meaning *no* skipping. So the near-universal setting for a human-readable file is `numLinesToSkip = 1`. It is a count of lines, not a header parser: `numLinesToSkip = 2` drops two lines, whatever they contain. It applies per file when several are listed. If you forget it, the symptom is a first invocation that fails with an argument-conversion error quoting your column names — an easy diagnosis once you have seen it. ## The other attributes - **`quoteCharacter`** — defaults to the **double quote** `"` for `@CsvFileSource`. This differs from inline `@CsvSource`, whose default is the single quote `'`. Files therefore follow ordinary CSV convention; a value containing a comma is written `"United States of America"`. Doubling the quote (`""`) escapes a literal one. - **`delimiter` / `delimiterString`** — a single char or a multi-char separator; set one, not both. Useful for tab- or pipe-separated files. - **`nullValues`** — tokens such as `N/A` or `NIL` converted to `null`. Very valuable here, because files are often authored in a spreadsheet where "nothing" gets typed several different ways. The unquoted-empty-means-null and quoted-empty-means-`emptyValue` rules of `@CsvSource` apply identically. - **`encoding`** — defaults to `"UTF-8"`. Set it when the file was exported from a tool that writes something else; a mis-set encoding shows up as mangled non-ASCII values rather than an error. - **`lineSeparator`** — defaults to `"\n"`. Files with CRLF endings normally still work because the carriage return is trimmed as whitespace, but if you are matching exact string values, be aware of it. - **`maxCharsPerColumn`** — a parser guard with a modest default (4096 characters). A single very long cell — a big JSON payload, a long SQL statement — trips it with an explicit error telling you the value is too long; raise the attribute, or accept the hint that the fixture belongs in `@MethodSource` reading its own file. - **`ignoreLeadingAndTrailingWhitespace`** — trimming, on by default, same as inline. ## When to prefer it Move the table into a file when it grows past comfortable reading in an annotation, when non-developers (QA, domain experts, product) should be able to edit the cases, when the same data feeds more than one test, or when the file is itself an artefact — a regulator-supplied bracket table, an exported golden set. Keep it inline when the cases are few and their meaning is local to the test. The cost of externalising is that a reviewer now reads the test and the data in two places, and the file must stay in the classpath. That is a fair trade for a hundred rows and a bad one for three.