In a Karate feature file, what turns an `Examples:` table into a dynamic one — so its rows come from `read('cats.json')` or `karate.setup()` instead of being typed out — and what must that cell evaluate to?

## The trigger is the shape of the table, not a keyword Karate has no `@dynamic` tag and no special `Examples:` syntax for this. The switch is structural. When the parser builds an `Examples:` table it looks at two numbers and only two: the column count and the row count. If the table has **exactly one column and exactly one row** — a header line with nothing beneath it — Karate keeps the text of that lone cell as the outline's *dynamic expression* and discards the table. Every other shape is an ordinary row-by-row table. ```gherkin Scenario Outline: create <name> * print 'creating', name Examples: | read('cats.json') | ``` That cell is read as a Karate expression, never as a column name. There is no header to name, so there is nothing to write `<...>` against until the expression has produced a row. ## What the expression must return Karate evaluates the cell in a throwaway runtime of its own, before any of the outline's scenarios exist, and accepts exactly two results: 1. **A list of objects.** Each element must be a map, and each map becomes one scenario's row data. An element that is not a map does not produce a scenario. 2. **A generator function.** Karate calls it repeatedly with the row index — `0`, `1`, `2`, … — and keeps going until a call returns `null`, or anything that is not an object. This is the option for data you do not want to materialise: only one row exists at a time. Anything else — a bare number, a string, a single object — is rejected, and the outline fails with an error naming the expression that produced it. ## Where the rows normally come from | Source cell | What each row is | Types | |---|---|---| | `read('cats.json')` | one element of the JSON array | preserved from the file | | `read('users.csv')` | one CSV record | **every field a string** | | `karate.setup().data` | one element of a variable built by an `@setup` scenario | preserved | | `karate.mapWithKey(karate.range(1, 50), 'i')` | `{ i: 1 }`, `{ i: 2 }`, … | preserved | | `[{ a: 1 }, { a: 2 }]` | a literal element | preserved | The CSV row is the one people get wrong. A CSV carries no type information, so `age` arrives as `'30'` rather than `30`. The `!` type hint that fixes that on a hand-written table is a *column header* feature, and a dynamic table has no headers to hint. ## `karate.setup()` and the `@setup` scenario `karate.setup()` is the built-in way to build rows with real Karate steps instead of cramming everything into one expression: - Tag a `Scenario` in the same feature with `@setup`. A scenario carrying that tag is **excluded from normal selection** — it runs only when `karate.setup()` asks for it, and it never appears as a result of its own. - `karate.setup()` runs it and returns **all** of its variables as one object, so `karate.setup().kittens` pulls out the array you built inside it. - It runs with the **`Background` skipped**, so it cannot depend on anything the `Background` defines. The `Background` still runs for each spawned row scenario, as usual. - `karate.setup('name')` picks one when a feature carries several, matched against `@setup=name`. This is what lets the rows come from a live source — an HTTP call that lists what actually exists, a query through Java interop — rather than a checked-in fixture. ## The quiet failure modes - **A one-column table with no data rows is dynamic whether you meant it or not.** Write `| name |` and forget the rows, and Karate evaluates `name` as an expression instead of telling you the table is empty. - **A two-column header with no data rows produces zero scenarios and no complaint.** The row loop starts after the header and there is nothing after it. A green run with a suspiciously low scenario count is the only symptom. - **The `Background` has not run when the cell is evaluated**, so a variable defined there is not in scope for the expression. - **The row count does not exist until run time.** Anything that wants it up front — a shard planner, a fixed-size report, a per-case dashboard keyed on a known set — has to cope with a number that cannot be read out of the file. ## Why it earns its place Cucumber's `Examples:` is fixed at parse time: the rows in the file are the rows you get. Karate's single-cell form removes that ceiling without adding syntax. The same outline body runs against three rows in a smoke profile and three thousand in a nightly, purely by swapping what the cell reads, and the generator form does it without ever holding the set in memory. Paired with the column variables Karate binds automatically, it is the reason a Karate suite rarely grows a separate data-provider layer at all.