What is a data-driven test, and why does each row need its own case name?

## Two things that beginners keep together A data-driven test separates the **logic** of a check from the **inputs and expected outcomes** it runs against. The logic is written once, in code. The inputs live outside it — a table embedded in the case file, a delimited file, a structured data file, a sheet exported by an analyst, or rows read from a store — and the runner executes that one piece of logic once per row. Moving the data out changes three things. Adding a case becomes an edit to data rather than an edit to code, so someone who is not fluent in the codebase can extend coverage. The same logic gets exercised across a wide input space, so drift in the behaviour shows up as *one row* failing rather than as a rewrite of a hand-written case. And the report becomes the contract with whoever reads it: if the report cannot say which row broke, the whole arrangement has bought you nothing. ## Why each row must be its own case Two implementations look equivalent and are not. In the first, a single case loads the table and loops over the rows inside its own body. The first row that fails aborts the case; every remaining row is never executed. The report shows one case and one failure. Unless the failure message was hand-built to include the row, the reader is told that "the invitation rules test failed" and nothing more. In the second, the table is expanded *before* execution into one discrete case per row, each with a display name derived from that row. The report shows as many results as there are rows, failures are counted per row, and a run history can track a single row's stability over time. A worked example. A suite covers the signing-invitation step of a document e-signing flow. The table carries 47 rows with four input columns — signer role (sender, counterparty, witness), delivery channel, invitation expiry in days — and one expected-outcome column: the number of `INVITATION_SENT` entries the envelope's audit trail should hold afterwards, normally one. Three rows fail. The witness role, re-invited inside the expiry window, records **two** invitation entries instead of one: a duplicated side effect. With one case per row, the report prints "witness / resend-within-expiry / 5-day expiry — expected 1 invitation entry, found 2" three times, and the shared factor is visible in seconds. With the loop-inside-one-case shape, the run reports a single failure on row 12, rows 13 through 47 never execute, and the team spends part of a 3-week release train believing it has 47 rows of evidence when it has 12. The unexecuted mass is the real damage; the missing row name is only the first symptom. ## Naming a row so the failure names itself The case name is the diagnostic surface, so it deserves design. * **Give the table a label column** rather than deriving the name from the raw inputs. A hand-written label such as `witness/resend-within-expiry/5d` says what the row is *for*; a name auto-built from every column is long, changes whenever an unrelated column changes, and is unreadable in a report. * **Keep it unique.** Two rows sharing a name collapse in most reporting formats, and one of the two results silently wins. * **Keep it stable across runs.** A name built from a row index shifts the moment someone inserts a row; every stability record attached to the old name now points at a different case. A name built from meaning survives edits. * **Keep secrets and personal data out of it.** The name travels into reports, dashboards and tickets — none of which are as protected as the test data itself. * **Keep it short.** It is a title, not a description; the detail belongs in the failure message. ## What belongs in the table, and what does not Inputs and the expected outcome for those inputs. That is the whole list. The assertion *mechanism*, the waiting, the environment wiring and the control flow stay in code. A column that reads "if the role is witness, skip the audit check" is control flow that has leaked into data: it is now a conditional written in a notation with no editor support, no review tooling that understands it, and no way to test it. When a table starts sprouting such columns, the honest move is to split it into two tables with two pieces of logic. An expected-outcome column is not optional. A row that supplies only inputs and asserts that nothing threw is a row that can only fail on a crash; it will pass through almost any behavioural regression in the flow it claims to cover. ## Rows are not free Every row costs run time, and rows that differ only cosmetically add minutes and no information. Choosing rows deliberately — boundaries, representative classes, the combinations that a real defect history says matter — beats generating a cross-product of every column and letting the suite grow until it no longer fits its feedback budget. A table that has quietly become the slowest thing in the pipeline is a design decision nobody made. ## The cost you have taken on The compensation for all this is that the failure no longer points at a line of code you wrote for this case; it points at a generic body and a row. That price is manageable while the indirection is one level deep — data outside, logic inside — and it grows sharply once the *steps* move out too.