In Karate, in what order are `karate-base.js`, `karate-config.js` and `karate-config-<env>.js` evaluated, and what happens when two of them return the same key?

## The three files and their fixed order Karate evaluates up to three JavaScript config sources before a top-level scenario, always in this order: 1. **`karate-base.js`** — optional, and rare. It exists for teams shipping a reusable framework layer in a JAR that wants to hand downstream projects a set of defaults and helpers. 2. **`karate-config.js`** — the one every project has. This is where the variables common to all environments live. 3. **`karate-config-<env>.js`** — optional, and looked for **only when `karate.env` holds a value**. With `karate.env` set to `qa`, Karate looks for `karate-config-qa.js`. The order is not configurable: no priority setting, no list to reorder, no fourth file. | File | Position | Required | Typical job | |---|---|---|---| | `karate-base.js` | first | no | shared helpers a framework layer ships to its consumers | | `karate-config.js` | second | expected in every project | the variables common to every environment | | `karate-config-<env>.js` | third, only when `karate.env` is set | no | the per-environment differences | ## One JavaScript context, three evaluations All three files are evaluated in the **same** JavaScript context for that scenario, one after the other, and each returned map is applied as variables before the next file runs. That single detail explains the whole design: - A function returned by `karate-base.js` is already a **bare callable name** by the time `karate-config.js` is evaluated. A base file returning `{ urlFor: function (env) { ... } }` lets the config file write `baseUrl: urlFor(karate.env)` with no import and no `read()`. - The same is true one step further down: `karate-config-<env>.js` sees everything the two files before it applied. - It also means a name declared in two files collides in the obvious way — the later declaration wins. ## The merge is a top-level replace This is the part that bites. Each returned map is applied **key by key at the top level**. It is not a recursive merge. ```javascript // karate-config.js function fn() { return { urls: { api: 'http://api.dev', web: 'http://web.dev' }, retries: 3 }; } // karate-config-qa.js function fn() { return { urls: { api: 'http://api.qa' } }; } ``` Run with `karate.env` set to `qa`, a scenario sees `retries` as `3` — the env file said nothing about it, so the earlier value stands — but `urls` is now `{ api: 'http://api.qa' }` and **`urls.web` no longer exists**. The whole `urls` object was replaced. The practical rules that follow: - Keep values that differ per environment as **flat top-level keys**, not as branches of one nested object. - If you do keep a nested block, an env file that touches it must return the block **whole**. - A key an env file never mentions is simply left alone — partial override at the top level works exactly as expected. ## What is optional, and what a failure looks like `karate-base.js` and `karate-config-<env>.js` are both optional and their absence is unremarkable — most projects have neither. `karate-config.js` is expected, but its absence is still not an error: the run continues with no config variables at all. A file that **throws**, however, is different. The chain stops at the file that threw, the remaining files are not evaluated, and the scenario fails — the failure attaches to the scenario's first step, naming the config file that blew up. That is a good thing: it means a broken env file cannot half-apply and leave the suite pointed at a mixture of two environments. ## Reading the chain in a real project When a variable is not what you expected, walk the chain in order and ask three questions: 1. Which of the three files sets that key? 2. Is `karate.env` actually set, so the third file was even looked for? 3. Is the key nested inside an object that a later file replaced wholesale? Most "my override did not apply" reports are the second question, and most "my override applied too much" reports are the third. ## When a config file throws Absence and failure are handled very differently. `karate-base.js` and `karate-config-<env>.js` are both optional, and `karate-config.js` — while expected in every project — is not fatal by its absence either: the run simply continues with no config variables set. A file that **throws** stops the chain. The files after it are not evaluated, and the scenario fails with the error attached to its **first step**, naming the config file that blew up. That is the right behaviour, and it is worth being able to explain why: a half-applied chain would leave a scenario holding some keys from the common config and none of the environment overrides, which is a suite silently pointed at a mixture of two environments. Failing the scenario outright is strictly safer than running it against an incoherent configuration. ## Telling which files actually loaded The commonest support question on this mechanism is not "what is the order" but "did my file even load". Two habits settle it quickly: - Log the file's own identity from inside each config file — a single `karate.log('config:', ...)` line per file — so the run output states which of the three actually ran. - Return a marker key from each file, a distinct `configSource` value say, and print it in a smoke scenario. A common-file marker where you expected the env file's tells you two things at once: the env file did not load, and `karate.env` is probably unset.