In a Karate `Scenario Outline` step, what is the difference between writing `<name>` and `'#(name)'`, and which one preserves the column's type?

## Two mechanisms, two different moments `<name>` and `#(name)` look like variations on one idea. They are not. | | `<name>` | `'#(name)'` | |---|---|---| | What it is | text substitution | embedded expression | | When it happens | before the scenario runs | while the step runs | | What it inserts | the **raw cell text** | the **evaluated value** | | Type preserved | no — it is characters | yes — number stays number | | Affected by a `!` hint | no | yes | | Works in the scenario name | yes | no | `<name>` is Cucumber-shaped: Karate walks the generated scenario and does a literal string replace of `<name>` across the scenario's **name**, each of its **steps' text**, their **doc strings** and any **step data table**. By the time the first step executes there is no placeholder left — the step's text simply *is* the substituted text. `#(name)` is Karate's own. It survives into execution and is resolved by the engine against the variable `name`, which Karate bound automatically from the column of the same name. ## Why the difference shows up in a request body ```gherkin Scenario Outline: create a cat Given url 'https://api.example.com' And path 'cats' And request { name: '#(name)', age: '#(age)' } When method post Then status 200 Examples: | name | age! | | Bob | 5 | ``` Here `'#(age)'` puts the **number** `5` into the JSON, because the `!` hint made the variable a number. Writing `{ age: '<age>' }` would put the **string** `'5'` there, because the placeholder splices the characters `5` and your own quotes wrap them. Writing `{ age: <age> }` happens to work — the characters `5` land unquoted and JavaScript parses them as a number — but it is fragile: it depends on the cell's text being valid syntax at that spot, and it breaks the moment a value contains a space, a comma, or a quote. The rule of thumb that survives review: **inside anything JSON-shaped, use `#(...)`; outside it, use `<...>`.** ## What `<name>` reaches, and what it does not - It reaches the **scenario name**, which is why a report can show `create a cat: Bob` per row. - It reaches the **outline's own steps**, their doc strings and their data tables. - It does **not** reach the `Background`. Background steps are shared across every scenario in the feature, so they are never rewritten per row. The *variables* still reach the `Background` — a `Background` step can say `* def x = name` — but a literal `<name>` there stays literal. - In a hand-written table, a blank cell splices the empty string, not a literal `<name>`. ## The whole-value rule, and where the lines differ An embedded expression is written as a **string that is entirely** `#(...)`. `'#(name)'` substitutes the value of `name`; `##(name)` does the same but removes the key from the JSON being built when the value is null, which pairs neatly with a blank `Examples:` cell. Whether `#(...)` also interpolates **inside a longer string** is version-sensitive. On the 1.5.2 line only the whole-value form is substituted — `'Hello #(name)!'` stays a literal string. The 2.x line added inline interpolation, so the same text becomes `Hello Bob!` there. Keep the whole-value form and the feature behaves the same on both; reach for interpolation and you have pinned yourself to 2.x. ## Choosing between them 1. **Values that go into JSON or XML** — request bodies, `match` right-hand sides, `def` of an object — take `#(...)`, so the type survives. 2. **Values that go into text** — the scenario name, a URL path segment, a doc string, a quoted literal — take `<...>`, because there is no type to preserve anyway. 3. **When the value came from a dynamic single-cell table**, prefer the variable or `#(...)`. Placeholders still work there, but the substituted text for an object value is its JSON form, and reasoning about that inside a step body is harder than just using the variable. 4. **Never mix them for the same value in the same step.** Two mechanisms resolving at two different moments in one line is where the confusing failures come from. ## The symptom to recognise A `match` that fails showing what looks like the same value on both sides — `5` against `5`, `true` against `true` — is nearly always a placeholder where an embedded expression belonged, or a missing `!` on the column. The message cannot show quotation marks around a type, so the two sides look identical. Assert `match __row == { age: '#number' }` once per row and the cause surfaces at the row instead of at the assertion.