> ## 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.

# Check tools

> Start a check on a simulator or an iPhone, wait for it and get its verdict.

## `verify_start`

Start a check: Mobster prepares its simulator, launches the app and fixes the expectations. Drive the app, then call `verify_finish`; with smart, Mobster runs the steps and you wait.

**Acts on the device.**

**Arguments**

| Name | Type | Default | Description |
| - | - | - | - |
| `app_path` | string | | Absolute path to the .app built for the iOS Simulator; it is installed before the run. |
| `bundle_id` | string | | The app's bundle ID; read from `app_path` when omitted. |
| `device` | string | | A device from `list_devices` (its id or name), or a simulator device type such as iPhone 17 Pro; a USB iPhone runs an app already on it (`bundle_id`). At most 128 characters. |
| `runtime` | string | the newest | The iOS runtime, such as iOS 26.4. |
| `reset` | string | reinstall with `app_path`, else data | App state cleared before launch. One of `none`, `data` or `reinstall`. |
| `launch_args` | array of strings | | Launch arguments. At most 20 items. |
| `launch_env` | object | | Launch environment variables, KEY to value. |
| `open_url` | string | | A deep link opened after launch. At most 2,000 characters. |
| `name` | string | | The check's name in reports. At most 120 characters. |
| `steps` | array of strings | required | The steps: the ones you will take, or with smart the ones Mobster takes, in plain English; may be empty. At most 20 items. Each item: 1 to 500 characters. |
| `expect` | array of objects | | The accessibility-tree assertions checked at `verify_finish`; declare ones that only hold after the steps. Required without smart. A navigation bar's title is its id: \{visible: \{role: navbar, id: General}}. At most 50 items. |
| `image` | boolean | `true` | Include a 390-px-wide JPEG of the screen. |
| `smart` | boolean | | Mobster runs the steps itself with `<model>`, on the user's `<provider>` key; wait for the verdict. |
| `max_usd` | number | `0.25` | With smart, the run's model spend cap in US dollars. More than 0 and at most 1. |
| `max_seconds` | number | `180` | With smart, the time limit for the steps. More than 0 and at most 600. |

**Fields of `expect[]`**

| Name | Type | Description |
| - | - | - |
| `text` | string | Holds when a shown element's label or value contains this text, in any case. |
| `no_text` | string | Holds when no shown element's label or value contains it. |
| `visible` | object | Holds when at least one shown element matches. |
| `absent` | object | Holds when no shown element matches. |
| `value` | object | With equals: exactly one shown element matches and its value equals it. |
| `count` | object | With equals, `at_least` or `at_most`: the number of shown elements that match. |
| `equals` | any | For value: text, a number or true/false; for count: a whole number. |
| `at_least` | integer | For count: at least this many. At least 0. |
| `at_most` | integer | For count: at most this many. At least 0. |
| `name` | string | A label for the report. At most 120 characters. |

**Fields of `expect[].visible`, `expect[].absent`, `expect[].value` and `expect[].count`**

| Name | Type | Description |
| - | - | - |
| `id` | string | The accessibility identifier, exactly or as /regex/. |
| `label` | string | The label, exactly or as /regex/ (add i for any case: /about/i). |
| `value` | string | The value, exactly or as /regex/; a switch reads 1 or 0. |
| `role` | string | Button, text, field, switch, cell, image, link, tab, slider, stepper, picker, segment, navbar or alert. |
| `enabled` | boolean | Whether the element is enabled. |
| `selected` | boolean | Whether the element is selected. |

**Example**

```json tools/call params theme={"theme":"css-variables"}
{
  "name": "verify_start",
  "arguments": {
    "app_path": "/abs/path/YourApp/.mobster/build/Build/Products/Debug-iphonesimulator/YourApp.app",
    "launch_args": ["-SkipOnboarding", "YES"],
    "launch_env": {"SEED_TASKS": "3"},
    "open_url": "yourapp://tasks",
    "steps": ["Tap the first task to mark it done."],
    "expect": [
      {"visible": {"id": "task_1", "selected": true}},
      {"value": {"id": "done_count"}, "equals": 1},
      {"value": {"id": "tasks_left"}, "equals": 2}
    ]
  }
}
```

**Returns**

The run's `status` and `run_id`, as text and in `structuredContent`. While it is `preparing`, `running` (a Smart run) or `finishing`, call `wait`. At `ready`, `screen` holds the screen as an outline, with a JPEG of it unless the run started with `image` false. A finished run returns its verdict, as `verify_finish` does.

> [accordion] Input schema and annotations of verify\_start
>
> Annotations: `title: "Start a check"`, `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`
>
> ```json theme={"theme":"css-variables"}
> {
>   "type": "object",
>   "properties": {
>     "app_path": {
>       "type": "string",
>       "description": "absolute path to the .app built for the iOS Simulator; it is installed before the run"
>     },
>     "bundle_id": {
>       "type": "string",
>       "description": "the app's bundle ID; read from app_path when omitted"
>     },
>     "device": {
>       "type": "string",
>       "maxLength": 128,
>       "description": "a device from list_devices (its id or name), or a simulator device type such as iPhone 17 Pro; a USB iPhone runs an app already on it (bundle_id)"
>     },
>     "runtime": {
>       "type": "string",
>       "description": "the iOS runtime, such as iOS 26.4; default the newest"
>     },
>     "reset": {
>       "type": "string",
>       "enum": [
>         "none",
>         "data",
>         "reinstall"
>       ],
>       "description": "app state cleared before launch; default reinstall with app_path, else data"
>     },
>     "launch_args": {
>       "type": "array",
>       "items": {
>         "type": "string"
>       },
>       "maxItems": 20,
>       "description": "launch arguments"
>     },
>     "launch_env": {
>       "type": "object",
>       "additionalProperties": {
>         "type": "string"
>       },
>       "description": "launch environment variables, KEY to value"
>     },
>     "open_url": {
>       "type": "string",
>       "maxLength": 2000,
>       "description": "a deep link opened after launch"
>     },
>     "name": {
>       "type": "string",
>       "maxLength": 120,
>       "description": "the check's name in reports"
>     },
>     "steps": {
>       "type": "array",
>       "items": {
>         "type": "string",
>         "minLength": 1,
>         "maxLength": 500
>       },
>       "maxItems": 20,
>       "description": "the steps: the ones you will take, or with smart the ones Mobster takes, in plain English; may be empty"
>     },
>     "expect": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "description": "one assertion: exactly one of text, no_text, visible, absent, value, count",
>         "properties": {
>           "text": {
>             "type": "string",
>             "description": "holds when a shown element's label or value contains this text, in any case"
>           },
>           "no_text": {
>             "type": "string",
>             "description": "holds when no shown element's label or value contains it"
>           },
>           "visible": {
>             "type": "object",
>             "description": "holds when at least one shown element matches",
>             "properties": {
>               "id": {
>                 "type": "string",
>                 "description": "the accessibility identifier, exactly or as /regex/"
>               },
>               "label": {
>                 "type": "string",
>                 "description": "the label, exactly or as /regex/ (add i for any case: /about/i)"
>               },
>               "value": {
>                 "type": "string",
>                 "description": "the value, exactly or as /regex/; a switch reads 1 or 0"
>               },
>               "role": {
>                 "type": "string",
>                 "description": "button, text, field, switch, cell, image, link, tab, slider, stepper, picker, segment, navbar or alert"
>               },
>               "enabled": {
>                 "type": "boolean",
>                 "description": "whether the element is enabled"
>               },
>               "selected": {
>                 "type": "boolean",
>                 "description": "whether the element is selected"
>               }
>             },
>             "additionalProperties": false
>           },
>           "absent": {
>             "type": "object",
>             "description": "holds when no shown element matches",
>             "properties": {
>               "id": {
>                 "type": "string",
>                 "description": "the accessibility identifier, exactly or as /regex/"
>               },
>               "label": {
>                 "type": "string",
>                 "description": "the label, exactly or as /regex/ (add i for any case: /about/i)"
>               },
>               "value": {
>                 "type": "string",
>                 "description": "the value, exactly or as /regex/; a switch reads 1 or 0"
>               },
>               "role": {
>                 "type": "string",
>                 "description": "button, text, field, switch, cell, image, link, tab, slider, stepper, picker, segment, navbar or alert"
>               },
>               "enabled": {
>                 "type": "boolean",
>                 "description": "whether the element is enabled"
>               },
>               "selected": {
>                 "type": "boolean",
>                 "description": "whether the element is selected"
>               }
>             },
>             "additionalProperties": false
>           },
>           "value": {
>             "type": "object",
>             "description": "with equals: exactly one shown element matches and its value equals it",
>             "properties": {
>               "id": {
>                 "type": "string",
>                 "description": "the accessibility identifier, exactly or as /regex/"
>               },
>               "label": {
>                 "type": "string",
>                 "description": "the label, exactly or as /regex/ (add i for any case: /about/i)"
>               },
>               "value": {
>                 "type": "string",
>                 "description": "the value, exactly or as /regex/; a switch reads 1 or 0"
>               },
>               "role": {
>                 "type": "string",
>                 "description": "button, text, field, switch, cell, image, link, tab, slider, stepper, picker, segment, navbar or alert"
>               },
>               "enabled": {
>                 "type": "boolean",
>                 "description": "whether the element is enabled"
>               },
>               "selected": {
>                 "type": "boolean",
>                 "description": "whether the element is selected"
>               }
>             },
>             "additionalProperties": false
>           },
>           "count": {
>             "type": "object",
>             "description": "with equals, at_least or at_most: the number of shown elements that match",
>             "properties": {
>               "id": {
>                 "type": "string",
>                 "description": "the accessibility identifier, exactly or as /regex/"
>               },
>               "label": {
>                 "type": "string",
>                 "description": "the label, exactly or as /regex/ (add i for any case: /about/i)"
>               },
>               "value": {
>                 "type": "string",
>                 "description": "the value, exactly or as /regex/; a switch reads 1 or 0"
>               },
>               "role": {
>                 "type": "string",
>                 "description": "button, text, field, switch, cell, image, link, tab, slider, stepper, picker, segment, navbar or alert"
>               },
>               "enabled": {
>                 "type": "boolean",
>                 "description": "whether the element is enabled"
>               },
>               "selected": {
>                 "type": "boolean",
>                 "description": "whether the element is selected"
>               }
>             },
>             "additionalProperties": false
>           },
>           "equals": {
>             "description": "for value: text, a number or true/false; for count: a whole number"
>           },
>           "at_least": {
>             "type": "integer",
>             "minimum": 0,
>             "description": "for count: at least this many"
>           },
>           "at_most": {
>             "type": "integer",
>             "minimum": 0,
>             "description": "for count: at most this many"
>           },
>           "name": {
>             "type": "string",
>             "maxLength": 120,
>             "description": "a label for the report"
>           }
>         },
>         "additionalProperties": false
>       },
>       "maxItems": 50,
>       "description": "the accessibility-tree assertions checked at verify_finish; declare ones that only hold after the steps. Required without smart. A navigation bar's title is its id: {visible: {role: navbar, id: General}}."
>     },
>     "image": {
>       "type": "boolean",
>       "default": true,
>       "description": "include a 390-px-wide JPEG of the screen (default true)"
>     },
>     "smart": {
>       "type": "boolean",
>       "description": "Mobster runs the steps itself with `<model>`, on the user's `<provider>` key; wait for the verdict"
>     },
>     "max_usd": {
>       "type": "number",
>       "exclusiveMinimum": 0,
>       "maximum": 1.0,
>       "description": "with smart, the run's model spend cap in US dollars (default 0.25)"
>     },
>     "max_seconds": {
>       "type": "number",
>       "exclusiveMinimum": 0,
>       "maximum": 600,
>       "description": "with smart, the time limit for the steps (default 180)"
>     }
>   },
>   "required": [
>     "steps"
>   ],
>   "additionalProperties": false
> }
> ```

## `wait`

Wait up to `timeout_s` seconds for a run that is preparing or running, and return what it became.

**Read-only.**

**Arguments**

| Name | Type | Default | Description |
| - | - | - | - |
| `run_id` | string | required | The run's id, from `verify_start`. |
| `timeout_s` | number | `40` | Seconds to wait. 1 to 50. |

**Example**

```json tools/call params theme={"theme":"css-variables"}
{"name": "wait", "arguments": {"run_id": "20260928-151841-816e"}}
```

**Returns**

The run's `status` and `run_id`, as text and in `structuredContent`. While it is `preparing`, `running` (a Smart run) or `finishing`, call `wait`. At `ready`, `screen` holds the screen as an outline, with a JPEG of it unless the run started with `image` false. A finished run returns its verdict, as `verify_finish` does.

> [accordion] Input schema and annotations of wait
>
> Annotations: `title: "Wait for a run"`, `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`
>
> ```json theme={"theme":"css-variables"}
> {
>   "type": "object",
>   "properties": {
>     "run_id": {
>       "type": "string",
>       "description": "the run's id, from verify_start"
>     },
>     "timeout_s": {
>       "type": "number",
>       "minimum": 1,
>       "maximum": 50.0,
>       "description": "seconds to wait (default 40)"
>     }
>   },
>   "required": [
>     "run_id"
>   ],
>   "additionalProperties": false
> }
> ```

## `verify_finish`

Judge the run by the expectations from `verify_start` and return the verdict, the proof frames and the report.

**Local.**

**Arguments**

| Name | Type | Default | Description |
| - | - | - | - |
| `run_id` | string | required | The run's id, from `verify_start`. |
| `image` | boolean | `true` | Include a 390-px-wide JPEG of the screen. |

**Example**

```json tools/call params theme={"theme":"css-variables"}
{"name": "verify_finish", "arguments": {"run_id": "20260928-151841-816e"}}
```

**Returns**

The verdict (`passed`, `failed`, `needs_review` or `couldnt_run`) and each assertion with what the screen showed. `structuredContent` has `verdict`, `assertions`, `reason`, `report`, `run_dir`, `proof` and `cost_usd`. With `image` true, the proof frame comes as a JPEG.

> [accordion] Input schema and annotations of verify\_finish
>
> Annotations: `title: "Finish a check"`, `readOnlyHint: false`, `destructiveHint: false`, `openWorldHint: false`, `idempotentHint: true`
>
> ```json theme={"theme":"css-variables"}
> {
>   "type": "object",
>   "properties": {
>     "run_id": {
>       "type": "string",
>       "description": "the run's id, from verify_start"
>     },
>     "image": {
>       "type": "boolean",
>       "default": true,
>       "description": "include a 390-px-wide JPEG of the screen (default true)"
>     }
>   },
>   "required": [
>     "run_id"
>   ],
>   "additionalProperties": false
> }
> ```

## `stop`

Stop a run (its result is `couldnt_run`, class stopped), or release a device driven directly.

**Cancels.**

**Arguments**

| Name | Type | Default | Description |
| - | - | - | - |
| `run_id` | string | | The run's id, from `verify_start` or a device tool. |
| `device` | string | | A device from `list_devices` (its id or name): without `run_id`, drive it directly; with neither, drive this session's own simulator. 1 to 128 characters. |

**Example**

```json tools/call params theme={"theme":"css-variables"}
{"name": "stop", "arguments": {"run_id": "20260928-151841-816e"}}
```

**Returns**

The run's verdict, as `verify_finish` returns it: a run stopped before it finished is `couldnt_run`, class `stopped`. A run still in a step returns `status` `stopping`: call `wait`. A device driven directly is released, with the run's steps and its frames folder.

> [accordion] Input schema and annotations of stop
>
> Annotations: `title: "Stop the run"`, `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: false`, `idempotentHint: true`
>
> ```json theme={"theme":"css-variables"}
> {
>   "type": "object",
>   "properties": {
>     "run_id": {
>       "type": "string",
>       "description": "the run's id, from verify_start or a device tool"
>     },
>     "device": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128,
>       "description": "a device from list_devices (its id or name): without run_id, drive it directly; with neither, drive this session's own simulator"
>     }
>   },
>   "required": [],
>   "additionalProperties": false
> }
> ```

## `save_check`

Save a check as checks/\<name>.yaml for `mobster test` and `run_tests`: from a finished check run, or a task in the Mobster app (its id from `mobster history`).

**Local.**

**Arguments**

| Name | Type | Default | Description |
| - | - | - | - |
| `run_id` | string | required | The run's id, from `verify_start`. |
| `name` | string | required | Lowercase letters, digits and dashes, such as paywall-plans. Matches `^[a-z0-9][a-z0-9-]{0,59}$`. |

**Example**

```json tools/call params theme={"theme":"css-variables"}
{
  "name": "save_check",
  "arguments": {"run_id": "20260928-151841-816e", "name": "mark-task-done"}
}
```

**Returns**

The saved file's path and the `mobster test` command that runs it again. `structuredContent` has `path` and `replaced`.

> [accordion] Input schema and annotations of save\_check
>
> Annotations: `title: "Save a check"`, `readOnlyHint: false`, `destructiveHint: false`, `openWorldHint: false`
>
> ```json theme={"theme":"css-variables"}
> {
>   "type": "object",
>   "properties": {
>     "run_id": {
>       "type": "string",
>       "description": "the run's id, from verify_start"
>     },
>     "name": {
>       "type": "string",
>       "pattern": "^[a-z0-9][a-z0-9-]{0,59}$",
>       "description": "lowercase letters, digits and dashes, such as paywall-plans"
>     }
>   },
>   "required": [
>     "run_id",
>     "name"
>   ],
>   "additionalProperties": false
> }
> ```

## `status`

Report Mobster's version, the simulator setup, whether Smart is available, where runs go, and the open run.

**Read-only.**

**Arguments**

Takes no arguments.

**Example**

```json tools/call params theme={"theme":"css-variables"}
{"name": "status", "arguments": {}}
```

**Returns**

The Mobster version, whether Smart is on, the runs folder, the open run and the simulator setup. `structuredContent` has `mobster_version`, `smart_available`, `smart_model`, `runs_dir`, `open_run` and `devices_open`, with the simulator setup.

> [accordion] Input schema and annotations of status
>
> Annotations: `title: "Check Mobster"`, `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`
>
> ```json theme={"theme":"css-variables"}
> {
>   "type": "object",
>   "properties": {},
>   "required": [],
>   "additionalProperties": false
> }
> ```


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