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

# mobster test

> Run your app's saved checks on simulators and iPhones, with reports.

Run every check in .mobster/checks (or the paths given) on one or more devices, in parallel, with retries, flake detection, and JUnit and HTML reports with the frames. A check is a saved YAML file; `mobster verify` runs one without saving it.

## Usage

```text theme={"theme":"css-variables"}
mobster test [options] [PATH ...]
```

## Arguments and options

| Name | Default | Description |
| - | - | - |
| `[PATH ...]` | .mobster/checks | check files or folders; `record` saves a task; `capsule` inspects evidence; `compare` reads suites; `scenario` runs ordered checks; `minimize` tries a paired local reproducer |
| `--sim TYPE[@RUNTIME]` | each check's own, or .mobster/matrix.yaml | a simulator device type, with an optional runtime, such as "iPhone 17 Pro\@iOS 26.4"; repeatable |
| `--device NAME` | none | a device from `mobster devices`, or all: every iPhone ready on this Mac, side by side in one report; repeatable. On a real iPhone, checks drive only builds you installed, never App Store apps |
| `--testflight BUNDLE` | none | with `--device`: your app's bundle ID, installed from TestFlight, which checks may drive as your own build; repeatable |
| `--matrix FILE` | none | a YAML file of simulators to run every check on (simulators only) |
| `--locale LANG[,LANG]` | none | run every check once in each language, such as de,ja,ar: the app launches in that language and region, and the screens are read for truncated text, untranslated strings and, in a right-to-left language, a layout that didn't mirror; repeatable |
| `--spread` | off | with two or more devices: run each check once, on whichever device is free, instead of on every one (the report groups checks by device) |
| `--parallel N` | 1 | simulators running checks at once; each iPhone runs one check at a time |
| `--retries N` | 1, or 0 with `--repeat` | attempts after a failure, from a fresh app |
| `--repeat K` | 1 | run each check K times and report its pass rate (flake hunting) |
| `--strict` | off | a flaky check fails the run |
| `--quarantine FILE` | .mobster/quarantine.yaml | checks that run and are reported but never fail the run |
| `--auto-quarantine` | off | quarantine for this run the checks whose last 20 results say flaky; without it Mobster only suggests them |
| `--tag TAG` | none | only checks with this tag; repeatable |
| `--audit NAME` | none | also audit what each check reads: a11y finds controls with no label, tap targets under 44 pt, images with no label and text clipped at a large text size; no model is called; repeatable |
| `--a11y [LEVEL]` | none | audit the screens each check reads for accessibility: warn (the default) reports findings and passes, strict fails on a new one; findings in .mobster/a11y-baseline.json never fail |
| `--update-a11y-baseline` | off | write this run's accessibility findings to .mobster/a11y-baseline.json, so later runs fail only on new ones |
| `--check NAME` | none | only the check with this name or file name; repeatable |
| `--update-snapshots` | off | write each snapshot's baseline from this run, in .mobster/snapshots/ (with `--check`, only those checks'); the run doesn't fail on a changed screen |
| `--shard I/N` | none | run the I-th of N even shards, such as 2/4 |
| `--keyless` | off | never call a model: checks with steps couldn't run |
| `--replay` | see description | replay each check's recorded path with no model, and heal a step that changed (the default) |
| `--fresh` | off | run every step with Smart and record the path again |
| `--no-heal` | off | replay, and fail a check whose screen changed instead of healing it (strict CI) |
| `--xctest` | off | also build your Xcode project once and run its XCTest and Swift Testing targets on a simulator beside the checks; failures join the report, the JUnit file, the history and the PR comment. Pass `--scheme` and `--project` to name them |
| `--test-plan NAME` | the scheme's | with `--xctest`: the test plan to run |
| `--only-testing ID` | none | with `--xctest`: run only this Target, Target/Class or Target/Class/test; repeatable |
| `--junit FILE` | none | also write the JUnit XML here |
| `--html DIR` | none | also write the HTML report (with each run's report) here |
| `--video` | off | record each run's screen, on a simulator or an iPhone, into the report |
| `--history` | off | print each check's last 20 results (pass rate, duration trend, flake score) and run nothing |
| `--json` | off | print JSON on stdout instead of the summary |
| `--include KIND` | none | with capsule export: copy selected raw junit, report or visual evidence locally; repeatable |
| `--share` | off | also upload the report, sealed, to your team's hosted reports and print its link (Team plan: one of the team's Macs, or MOBSTER\_TEAM\_KEY in CI) |
| `--share-days DAYS` | 30 | how long a shared report is kept: 7, 30 or 90 |
| `--assert-timeout S` | 5 | how long expectations may wait for the screen to settle |
| `--run RUN_ID` | none | the finished task to make a check from |
| `--name TEXT` | the task | the check's name |
| `-o, --output PATH` | none | with record: write the check here; with import: checks folder; with capsule export: new output directory |
| `--bundle ID` | none | the app's bundle ID for flows with no appId, and over the appId of the others |
| `--app PATH` | none | write this .app (built for the iOS Simulator) into each check |
| `--skip-unsupported` | off | drop commands Mobster can't run instead of turning each into a step marked TODO, and list each one; an assertion is never dropped |
| `--dry-run` | off | say what would be written, and write nothing |
| `--force` | off | replace checks that already exist |
| `--arg ARG` | none | a launch argument the crash needs, such as -MyFlag; repeatable (`--bundle` and `--app` name the app) |
| `--link URL` | none | a link that opens the app on the crashing screen |
| `--list` | off | list the recipes, one line each |
| `--set KEY=VALUE` | none | a recipe param; repeatable (`mobster test add --list` shows each recipe's) |
| `--base REF` | `$GITHUB_BASE_REF`, else origin/main | the branch the PR merges into |
| `--no-build` | off | don't build the app: test the builds the checks name |
| `--scheme NAME` | the only one | the Xcode scheme to build; also the scheme `--xctest` builds |
| `--project PATH` | the one in the project | the .xcodeproj or .xcworkspace to build; also the one `--xctest` builds |
| `--drafts {run,write,off}` | run | checks for changed screens no check covers: write and run them (default), only write them, or neither. Drafts never fail the PR |
| `--no-gifs` | off | don't make a GIF of each failed check |
| `--tested-with` | off | end the PR comment with a "Tested with Mobster" line that links to mobster.dev |
| `--comment FILE` | none | also write the PR comment's Markdown here |
| `--github {check,comment,off}` | check | put the verdict on the pull request with Mobster Checks, the GitHub App: a check run (check, the default), the check run and one comment kept up to date (comment), or nothing (off) |
| `--watch` | off | test each pull request of this repository when someone opens it or pushes to it, each in its own worktree, until you press ctrl+c |
| `--interval S` | 30 | with `--watch`: the seconds between listings of the pull requests |
| `--allow N` | none | with `--watch`: also test pull request N's waiting head from a fork, after you read it; repeatable |
| `--at HH:MM` | none | with nightly on: the time to run every night, on a 24-hour clock, such as 02:00 |
| `--accept` | all | keep the healed steps of these checks |
| `--reject` | off | keep failing: put the recorded steps back and fail when they change again |
| `--bad-app PATH` | none | with minimize: the exact saved bad simulator .app build |
| `--control-app PATH` | none | with minimize: the exact saved clean-control simulator .app build |
| `--isolated` | off | with minimize: confirm the external fixture is isolated for every trial |
| `--max-attempts N` | 8 | with minimize: total bad and control suite dispatches, 5–8 |
| `--env-file PATH` | `$MOBSTER_ENV_FILE` | load KEY=VALUE lines, such as OPENAI\_API\_KEY or ANTHROPIC\_API\_KEY for Smart steps; variables already set win |

```text theme={"theme":"css-variables"}
exit codes: 0 passed, 1 failed, 2 needs review, 3 couldn't run, 130 ctrl+c

examples:
  mobster test
  mobster test --sim "iPhone 17 Pro" --sim "iPhone SE (3rd generation)" --parallel 2
  mobster test --junit build/junit.xml --html build/mobster-report
  mobster test record --run 3f9c2a1b7d0e --name paywall
```


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