peach test
One test command for both runners. A YAML flow, a flow directory or a YAML workspace config runs with the Maestro interpreter; a Jest config, a test file or a directory of them runs your existing Detox suite unchanged, since Jest maps detox to the Peach driver. With no target it runs .maestro/ or maestro/ when present and otherwise lets Detox find its config and suites. Check --list-compat before running an existing Maestro suite. generate writes a flow from a plain-language goal, and start, keep and end author one from live CLI actions. compare runs the same flows on your iOS simulator and on Peach and writes an HTML diff. Add —cloud to submit a prebuilt bundle and the test files to the hosted executor. Running tests needs a signed-in account: peach login on a desktop or PEACH_API_KEY elsewhere; authoring a flow live and init need none.
Options
| flag | description |
|---|---|
--app <bundle> | bundle, dev-server target, or shell URL to run |
--env KEY=VALUE | set Maestro flow variables for ${KEY} interpolation (repeatable) |
--include-tags <tags> | run only Maestro flows with these tags |
--exclude-tags <tags> | skip Maestro flows with these tags |
--format <fmt> | junit writes an XML report of Maestro flows |
--output <path> | JUnit report path for flows, or the flow path on test end |
--record | record a webm while each flow runs |
--profile | capture performance stats while a flow runs |
--out <dir> | write recordings and screenshots to this directory |
--test-output-dir <dir> | save flow artifacts and result JSON here; result JSON defaults to —out or /tmp/peach-recordings |
--preview | record events and video, upload, and print /preview/<id> |
--preview-open | open the uploaded preview link after a successful run |
--slow <ms> | delay between flow steps for natural pacing |
--new | force a fresh sim for this run |
--headed | watch the run in a fresh visible window |
--validate | re-run a live-authored flow before clearing its draft |
--config <path> | a Maestro workspace config (YAML) or a Jest config |
-t <pattern> | run Detox tests whose names match, as Jest —testNamePattern |
--watch | Jest watch mode for a Detox suite |
--no-launch | skip the running-shell check for a Detox suite |
--detox | with init, scaffold a Detox config and sample test instead of a flow |
--list-compat | print supported and unsupported Maestro verbs |
--cloud | submit the bundle and suite to the hosted executor |
--origin <url> | use a specific Peach API origin |
--poll-interval <ms> | set the hosted result polling interval |
--timeout <ms> | bound the hosted result wait; a prebuilt-bundle job keeps running after it |
--cancel <job-id> | cancel a hosted job; a queued job is never billed |
Examples
One Test Command
peach test owns every test: Maestro YAML flows, existing Detox suites, generated flows and live-authored drafts. It picks the runner from what you give it. Check --list-compat for the supported Maestro verbs before running an existing Maestro project:
Supports: tapOn, longPressOn, assertVisible, inputText, scrollUntilVisible, launchApp with JSON arguments, stopApp, killApp, setLocation, travel, inputRandom*, clearState, copyTextFrom, evalScript, openLink, when:/optional:, onFlowStart/onFlowComplete, repeat, runFlow, env var interpolation. Launch arguments are installed before guest app entry and replace or clear on each later launch. setAirplaneMode logs that iOS simulators have no airplane mode and continues, as Maestro does.
Directory discovery selects root YAML flows by default, as Maestro does.
For nested suites, pass their folder, such as .maestro/flows, or add
config.yaml with flows: ["flows/**"]. Keep shared subflows outside those
globs; runFlow can still load them.
The CLI prints the result directory after writing preview or run receipts.
For live authoring, only the last successful write action becomes the pending
candidate; test keep commits it to the draft. test end --validate
re-runs from a clean run before clearing the draft, and preserves the draft if
validation fails.
Existing flow files still support frontmatter like:
That lets a flow file encode which target it opens and whether the desktop companion is the preferred runtime for that flow.
When you want frame timing for a full scripted path, run the same file with
--profile. Playback, recording, and profiling stay on the same bridge-backed sim/action surface as the rest of the CLI.
Drop-in Detox
A Jest config, a test file or a directory of them runs your existing Detox suite against peach with no code changes. With a peach shell running (peach open <app-port>), it sets up the Jest module mapping (^detox$ → peachsim/detox), and runs your tests. Jest runs from your project, so add its dev dependencies once:
Users can also add preset: 'peachsim/detox' to their own Jest config to run tests via plain npx jest.
Accounts
Running tests needs a signed-in Peach account on every machine: peach login on a desktop, or PEACH_API_KEY in CI and other shells. Every account, the free Seed plan included, can create a key with peach auth key create or in Billing → API Keys. The CLI verifies the key online and keeps the answer, so runs keep working offline for a while between checks. A GitHub App repository authenticates with its installation token and needs no key.