In a Karate feature file, why can the XPath written into a match step not contain a variable, and what does karate.xmlPath(xml, expression) give you instead?

## Why the step's path is literal There is no glue layer here. Karate reads a `match` step, dispatches on its leading keyword, and then parses what remains into a **variable part** and a **path part** using the text as written. Nothing runs a template engine over it first. That is deliberate - it is what makes `match response /Envelope/Body/Result == 'OK'` unambiguous - but it means a path cannot be assembled from data: ```gherkin * def xml = <query><name><foo>bar</foo></name></query> * def elementName = 'name' # this looks for a child literally called elementName, and finds nothing * match xml /query/elementName/foo == 'bar' ``` The reference documentation states the restriction for the named-path form of the left side directly, and points at an extra step as the fix. ## The escape hatch `karate.xmlPath(xml, expression)` is a function on the built-in `karate` object. Its second argument is an ordinary string, evaluated by the JavaScript engine like any other expression, so it can be concatenated, interpolated, or returned from a function: ```gherkin * def xml = <query><name><foo>bar</foo></name></query> * def elementName = 'name' * def name = karate.xmlPath(xml, '/query/' + elementName + '/foo') * match name == 'bar' * def queryName = karate.xmlPath(xml, '/query/' + elementName) * match queryName == <name><foo>bar</foo></name> ``` The pattern is always the same: compute, `def`, then `match` on the plain variable. The assertion stays readable because the interesting part - the path - has a name. ## What it returns It applies exactly the same conversion the match left side applies, so nothing new has to be learned: - an element with no child elements gives its **text**, as a string; - an element with children gives an **XML chunk**; - two or more nodes give a **list**; - `karate.xmlPath(foo, 'count(/root/a)')` gives a **number**, so `match tmp == 2` is the right shape. The first argument is flexible: a variable already parsed as XML, or a raw XML string, which the function parses for you. ## Where it earns its place Three situations, in rough order of how often they come up: 1. **A path element that comes from data.** A table-driven scenario walking a list of field names, or a path whose segment is an id returned by an earlier call. 2. **Inside a JavaScript function.** Feature steps are not available in a JS body, so when a helper function has to read a document, `karate.xmlPath` is the only way in. The same is true inside a `karate.forEach` callback. 3. **A path built once and reused.** Assign the path to a variable, then reuse it across several documents, keeping the XPath in one place instead of copied across four steps. ## The habit to avoid Do not reach for string surgery in the step text itself - embedded expressions belong in the payload you build, not in the path you read. And do not skip the `def`: writing the call inline as the left side of a match works, but it hides the value from `print`, and the first thing you want when an XML assertion fails is to see what the path actually selected. ```gherkin * def path = '/records/record[' + index + ']' * def value = karate.xmlPath(response, path) * print 'selected:', value * match value == expected ``` ## What it does not change Using the helper does not soften any of the other rules. A path that selects nothing still selects nothing; a single node is still unwrapped rather than wrapped in a list; a leaf element's value is still a string, so a computed path over `<age>30</age>` gives `'30'` exactly as the step form does. Nothing about moving the path into JavaScript makes the result more JavaScript-ish - the conversion happens before the value reaches the engine, so both routes hand you the same object. Nor does it change how the assertion is reported. The report shows the step that failed, so a `match value == expected` line tells a reader less about the intent than `match response /Envelope/Body/Result == 'OK'` does. That is a genuine cost of the indirection, and the reason to reach for it only when the path really is dynamic. ## The JSON twin, and the reason both exist The same shape exists for JSON, and for the same reason: a JsonPath written into a step is also literal. Recognising that the pair are siblings is the point - the rule is not "XPath is special", it is "a path in a step is text, a path in a function is data". Once that lands, the choice between the two forms stops being a matter of taste: write the path in the step whenever it is fixed, because it reads better and appears in the report; move it into the function the moment any part of it depends on a value.