In a Karate mock feature, what do configure responseHeaders and configure cors = true in the Background do to every reply, and how does a scenario's own responseHeaders interact with them?

## Two knobs that belong to the server, not to a request A mock feature's `Background` is the only part of the file that runs at server start-up, and it is where both of these settings are read. The mock handler harvests them once, when it initialises the feature, and keeps them for the life of the server: ```gherkin Background: * configure responseHeaders = { 'X-Env': 'mock', 'Cache-Control': 'max-age=60' } * configure cors = true ``` Putting them anywhere else is a mistake of kind, not of style. They describe how *the mock server* answers, so there is no request context in which they would mean anything; the per-endpoint knob is the `responseHeaders` **variable**, which is a different thing with a deliberately similar name. ## `configure responseHeaders`: a default header map The map is applied to the reply of every request that a scenario matched and served successfully. It exists because most mocks carry the same handful of headers everywhere — a caching directive, an environment marker, a trace id — and repeating them in twenty scenarios is how a mock drifts. Note that the media type is usually **not** what you need it for: Karate already derives `Content-Type` from the runtime type of `response`, so a Map body is announced as JSON without any configuration. ## The scenario-level variable merges, it does not replace When a scenario sets `* def responseHeaders = { ... }`, the handler applies the configured map first and then the scenario's map **over it, key by key**. That has two consequences worth stating out loud: - a scenario that overrides one header **keeps** every other configured header — this is pinned by Karate's own test, where a configured `X-Special-Header` and a scenario's `X-Custom-Header` both arrive on the same reply; - there is no way to *remove* a configured header from one scenario, only to give it a different value. If one endpoint must not carry a header, it does not belong in the configured map. ## `configure cors = true`: preflight plus a wildcard origin Switching CORS on does two separate things: 1. an `OPTIONS` request is answered directly by the handler with `200`, an `Allow` header, an `Access-Control-Allow-Origin: *`, the allowed-methods header, and the requested headers echoed back — **before any scenario matching happens**; 2. every reply a scenario serves successfully also carries `Access-Control-Allow-Origin: *`. Point 1 is the one that surprises people: while CORS is on you cannot write your own `OPTIONS` scenario, because the preflight short-circuit runs first and your scenario is never consulted. ## The replies these settings never reach Both settings live on the **success path only**, which is the highest-value detail in this whole area: | outcome | configured headers | CORS header | delay | |---|---|---|---| | a scenario matched and every step passed | applied | applied | applied | | a step in the matched scenario failed (500) | skipped | skipped | skipped | | no scenario matched at all (404) | skipped | skipped | skipped | The 404 row is the one that costs debugging hours. A browser calling a CORS-enabled Karate mock on a path no scenario matches gets a 404 **with no `Access-Control-Allow-Origin` header**, so the browser reports it as a CORS failure rather than as a 404. The console says "blocked by CORS policy"; the actual defect is a matcher that does not match. Check the mock's log for the *"no scenarios matched, returning 404"* line before you touch the CORS configuration. ## A disclosure header you did not configure Karate 2.x adds one header of its own on top of whatever you configured: every reply the mock **fabricates** carries `Karate-Mock: true`. It is on by default, it is stamped even on the unmatched-request 404, and it is deliberately *not* stamped on a reply that came from a real upstream through `karate.proceed()`. The point is that a consumer cannot otherwise tell a stand-in from the real system — an address proves nothing, since real services live on `localhost` too — so the responder says so itself. Read it in one direction only: its presence is certain, its absence proves nothing, because any other stub answers exactly like a real server. It is suppressed from the Java API rather than from the feature file, for the case where a mock has to imitate a real service's header set byte for byte. Karate 1.x adds no such header, so a test that asserts on the exact header set will see a difference between the lines.