> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobster.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Fixtures

> Name the state a check starts from once, in .mobster/fixtures/, and use it in every check: a reset, launch arguments, seed files, the keychain, the pasteboard and a sign-in.

A fixture is the state your app is in before a check's steps begin: signed in, a cart with two items, a clean install. You write it once in `.mobster/fixtures/` and name it in each check that needs it.

```yaml theme={"theme":"css-variables"}
# .mobster/fixtures/signed-in.yaml
launch:
  args: [-UITests]
  env: {API_HOST: staging.example.com}
steps:
  - type ${TEST_EMAIL} into Email
  - type ${TEST_PASSWORD} into Password and tap Sign in
```

```yaml theme={"theme":"css-variables"}
# .mobster/fixtures/logged-in-cart.yaml
extends: signed-in
reset: data
keychain: reset
files:
  - from: files/cart.json        # inside .mobster/fixtures/
    to: Documents/cart.json      # inside the app's data container
pasteboard: SAVE10
```

```yaml theme={"theme":"css-variables"}
# .mobster/checks/checkout.yaml
app: {bundle: com.example.shop}
fixture: logged-in-cart          # or a list: [clean, logged-in-cart]
steps:
  - tap Checkout
expect:
  - text: Order summary
```

## What a fixture holds

| Key | What it does | Where |
| - | - | - |
| `extends` | Fixtures this one builds on, applied first | Anywhere |
| `reset` | `none`, `data` or `reinstall`, as in [Reset levels](/simulators#reset-levels). The check's own `reset` wins | Simulators |
| `launch.args`, `launch.env` | Added to the check's. For a name in both, the check's env wins | Anywhere |
| `steps` | Run before the check's steps, such as signing in | Anywhere |
| `files` | Copied into the app's data container before it launches. A folder copies whole | Simulators |
| `keychain: reset` | Empties the simulator's keychain | Simulators |
| `pasteboard` | Sets the simulator's clipboard | Simulators |

A sign-in uses the project's secrets: `${TEST_EMAIL}` and `${TEST_PASSWORD}` come from `mobster env` ([Checks](/checks#secrets-and-test-credentials)), are filled in when the run starts, and never reach a report.

Fixtures compose in the order you name them. `reset` and nonempty `pasteboard` take the last one set. Keychain resets accumulate. `args` and `steps` add up. `env` and a file's destination are replaced by a later fixture. A fixture used twice runs once, and a circle (`a` extends `b` extends `a`) is refused with the chain.

## List and apply

```sh theme={"theme":"css-variables"}
mobster fixtures list
```

```text theme={"theme":"css-variables"}
demo-seed: 1 file, keychain reset, pasteboard  [simulators only]
logged-in-cart: reset data, 1 file, keychain reset, pasteboard, 1 arg, 1 env, 2 steps  (builds on signed-in)  [simulators only]
signed-in: 1 arg, 1 env, 2 steps
```

`mobster fixtures apply` does the same to a simulator now, without a check: it resets the app, resets the keychain, copies the files and sets the pasteboard. It doesn't launch the app, and it leaves a fixture's args, env and steps for a check to use. Run on 18 Oct 2026 on an iPhone 17 Pro simulator (iOS 26.4):

```sh theme={"theme":"css-variables"}
mobster fixtures apply demo-seed --bundle dev.mobster.daybreak --sim "iPhone 17 Pro"
```

```text theme={"theme":"css-variables"}
Simulator: Mobster · iPhone 17 Pro · iOS 26.4 · 3
Applied demo-seed to dev.mobster.daybreak on Mobster · iPhone 17 Pro · iOS 26.4 · 3: keychain reset, 1 file copied, pasteboard set.
```

`cat` of the file in the app's container then read `{"items": 2}`, and `xcrun simctl pbpaste` read `SAVE10`. The first run on a simulator also builds WebDriverAgent, which took 92 s that day.

`--json` prints the list as JSON, and `GET /api/tests/fixtures?project=/abs/path` returns it to the Mac app: each fixture's flattened `reset`, `args`, `env`, `steps`, `files`, `keychain`, `destructive`, and whether a `pasteboard` is set (never its text).

## What it won't do to your iPhone

A reset, seed files, a keychain reset and a pasteboard change a device's state, so they run on simulators only. A check on a real iPhone whose fixture holds any of them doesn't run, and says why before it touches the phone:

```text theme={"theme":"css-variables"}
mobster fixtures: a reset changes the state of a phone, and fixtures do that on simulators only (from signed-in, logged-in-cart). Run the check on a simulator, or use a fixture with only launch args, env and steps on the phone.
```

On a phone, args, env and steps work, so a sign-in fixture runs there.

Files go only inside the app's data container on a simulator Mobster made. A destination that leaves the container, a symbolic link in the way, a source outside `.mobster/fixtures/` and more than 20 MB are refused, and nothing is copied.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.