In a Karate feature file, what does `karate.setupOnce()` run, and how is it different from a `callonce` of another feature?

## What it is `@setup` is a built-in Karate tag, and `karate.setupOnce()` is the cached way to run the scenario carrying it. The pair exists for setup that belongs *inside* the feature it serves rather than in a separate file: ```gherkin Feature: cats Background: * url baseUrl @setup Scenario: * def data = [{ name: 'Bob' }, { name: 'Nyan' }] Scenario: first cat is present * def seeded = karate.setupOnce() * match seeded.data[0].name == 'Bob' ``` The return value is a map of every variable the `@setup` scenario created, so `karate.setupOnce().data` reaches the array above. ## Three rules that define the tag 1. **A `@setup` scenario is never selected by an ordinary run.** Karate's tag evaluation rejects it outright, the same way it rejects `@ignore`. It does not appear in the run, it does not appear in the count, and no tag expression brings it back. The only way to execute it is `karate.setup()` or `karate.setupOnce()`. 2. **It runs with the `Background` skipped.** The setup runtime is created with the background suppressed, so anything the `Background` defines is simply not there. Setup that needs a base URL or a header must establish it itself. 3. **More than one is allowed, but they need names.** Tag them `@setup=kittens` and `@setup=owners`, then call `karate.setupOnce('kittens')`. Without a name, Karate takes the first `@setup` scenario it finds; with a name that matches nothing you get an explicit failure naming the tag rather than a silent empty map. ## The caching, and how wide it is The cache is held by the running feature and keyed on the name you passed — the unnamed call has its own default slot. So: - every scenario and every `Examples` row of that feature shares the one result; - a copy is returned on each hit, not the cached map itself; - a second feature file has its own cache and runs its own `@setup` scenario; - lookups are guarded so parallel scenarios of the feature cannot execute the setup twice. The uncached sibling `karate.setup()` runs the scenario every time it is called, which is what you want when the setup must be fresh per scenario. ## How it differs from `callonce` | | `karate.setupOnce()` | `callonce` | |---|---|---| | Form | function on the `karate` object | step keyword | | Target | a `@setup` scenario in **this** file | any feature or JS function, usually via `read(...)` | | Cache key | the optional setup name | the call expression as written | | Cache width | the running feature | the running feature | | Visible to a normal run | no, the tag suppresses it | the callee is a separate file anyway | Both are feature-wide, so neither collapses work across the suite — that is `karate.callSingle()`'s job. The real choice between them is about where the setup should live. Pull it into a `@setup` scenario when it is meaningful only to this file and you would rather read it next to the scenarios it feeds. Push it into a separate feature and `callonce` it when two or more files need the same thing, since a `@setup` scenario cannot be shared. ## Failure, and what the report shows A `@setup` scenario is not a test, but it is still a scenario, and that shapes what you see when it goes wrong. A failure inside it surfaces against whichever scenario called `karate.setupOnce()`, because that is the scenario that was executing; the setup’s own steps are attached to the report underneath it rather than appearing as an independent result. Two consequences follow. First, a broken setup makes one scenario look broken and the rest of the feature look fine until they too call it. Second, nothing is cached when the setup throws, so the next caller in that feature runs it again — the same rule `callonce` follows, and the opposite of `karate.callSingle()`, which stores the failure and replays it. If the setup is doing something that must not be attempted twice, that retry is worth designing around. ## Practical notes - Because the tag makes the scenario invisible, a `@setup` block is a good place for steps you never want counted as a test — seeding, arranging, fetching reference data. It is not a place for assertions, because a failure there surfaces as a failure of whichever scenario called it. - The result is data. As with the other once-caches, keep functions and Java objects out of it; what a later scenario receives is a copy of the values, and a function handed across still resolves its variables in the scope it was created in. - The step in the `@setup` scenario runs exactly once per feature under `setupOnce`, which is easy to confirm with a `print`: the `Background` around it will run once per scenario and once per `Examples` row, and the setup line will appear once.