Config File Chain

## What the file must contain `karate-config.js` is not a properties file and not a Karate-specific format. It is plain JavaScript, and Karate evaluates the whole source expecting it to yield a **function**. The conventional shape is a single named function that builds an object and returns it: ```javascript function fn() { var config = { baseUrl: 'http://localhost:8080', adminUser: 'admin', timeoutMs: 5000 }; return config; } ``` What matters is not the function's name but that the source produces something callable returning a map. ## What Karate does with the returned map Every **top-level key** of that map is applied as a scenario variable of the same name. There is no import, no registration and no accessor: a key called `baseUrl` is readable in the very next step as `baseUrl`. ```gherkin Scenario: uses a config variable directly Given url baseUrl And path 'cats' When method get Then status 200 ``` That is the mechanical difference from a step-definition framework. There is no glue package to point at, no hook class to register, and no context object to inject — the config file simply seeds the variable space that every step already reads from. Values are ordinary Karate variables once applied, so a scenario can shadow one with its own `def` without touching the file, and a JavaScript **function** returned in the map becomes a callable helper available to every scenario. ## How often it runs This is the part that surprises people: the function is evaluated **before every top-level scenario**, not once per suite, and a `Scenario Outline` counts each `Examples` row as its own scenario. A hundred scenarios means a hundred evaluations. | Aspect | `karate-config.js` | |---|---| | Format | JavaScript source evaluating to a function | | Return value | a map (JSON-like object) | | Effect of each key | becomes a scenario variable of that name | | Evaluated | before every top-level scenario, and every `Examples` row | | Not evaluated for | a feature reached through `call` / `callonce` | | Missing file | not an error — no config variables are set | Two consequences follow directly: 1. **Anything expensive in the file is paid per scenario.** A blocking HTTP sign-in written straight into the function multiplies across the suite, and across every thread in a parallel run. 2. **Nothing mutated by one scenario survives into the next.** Each scenario gets a freshly evaluated map, so a scenario that mutates a config-supplied object cannot leak that mutation into its neighbours — which is exactly what makes scenarios independently runnable. ## What is in scope inside the file The `karate` object is bound before the config function runs, so the function can branch on run-time inputs: - `karate.env` — the current environment name, or `null` when nothing set it. - `karate.properties['some.prop']` — reads a JVM system property, the usual way a build passes a port or a URL in. - `karate.log(...)` — useful for proving which config actually loaded. ## Common traps - **Treating it as suite-level setup.** It is per-scenario. If you need something done once, the config file is the wrong place to do the work directly. - **Expecting a missing file to fail loudly.** It does not. The run proceeds and fails later, in a step, on a name that was never defined — a much worse error message than a missing-file error would have been. - **Returning nothing.** A function that computes variables but forgets `return config` contributes no variables at all, silently. - **Assuming a called feature re-runs it.** It does not; a feature reached through `call` inherits the caller's variables instead. - **Putting large helper libraries in it.** Everything in the returned map is re-created per scenario. ## It is the same mechanism as a shared-scope call The config file is not a special case bolted onto the engine. Karate already has one rule that says *a map-like value applied without an assignment contributes each of its key-value pairs as a variable* — the same rule behind `call read('helpers.feature')` written with no `def` in front of it. `karate-config.js` is that rule, applied automatically at scenario start. Knowing that removes most of the mystery: there is nothing a config file can produce that a step could not have produced, a config key is not privileged and can be shadowed like any other name, and everything true of a returned map elsewhere in Karate — including that a JavaScript function in the map becomes a callable name — is true here too. ## Keep it to what nearly everything needs Because it is evaluated per scenario, `karate-config.js` is the wrong place for anything that is only needed by a few features. Moving a routine into it makes the routine global, and global has a price paid on every scenario in the suite: the object is rebuilt, the function is re-created, and any work in the function body runs again. The guidance that ships with Karate is explicit about this — move something into the config file only when nearly *all* your feature files need it, because a bloated configuration costs both run time and readability. A useful test before adding a key: would you be comfortable with this value being re-computed once per scenario, on every thread, for the whole suite? If not, it does not belong in the raw body of the config function.