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.

terminal
peach test [flow-or-suite] [--app <bundle|port|url>] [options]
peach test <flow-or-suite> --app <bundle> --cloud
peach test --cancel <job-id>
peach test generate "<goal>"
peach test start|keep|end
peach test validate <flow>
peach test compare <flow-or-dir> [--udid <id>]
peach test init [--detox]
peach test --list-compat

Options

flagdescription
--app <bundle>bundle, dev-server target, or shell URL to run
--env KEY=VALUEset 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
--recordrecord a webm while each flow runs
--profilecapture 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
--previewrecord events and video, upload, and print /preview/<id>
--preview-openopen the uploaded preview link after a successful run
--slow <ms>delay between flow steps for natural pacing
--newforce a fresh sim for this run
--headedwatch the run in a fresh visible window
--validatere-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
--watchJest watch mode for a Detox suite
--no-launchskip the running-shell check for a Detox suite
--detoxwith init, scaffold a Detox config and sample test instead of a flow
--list-compatprint supported and unsupported Maestro verbs
--cloudsubmit 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

terminal
peach test .maestro/login.yaml --app http://localhost:8081
peach test .maestro/ --env USERNAME=alice
peach test e2e/ --app 8081
peach test e2e/login.test.ts --app http://localhost:8081 -t "login"
peach test generate "log in and verify the welcome screen"
peach test start
peach test end --output .maestro/login.yaml --validate
peach test compare .maestro/ --udid <simulator-udid>
peach test init
peach test .maestro/login.yaml --app ./dist/main.js --cloud

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:

terminal
peach test # run .maestro/ or maestro/, else your Detox suite
peach test .maestro/login.yaml --app 8081 # one flow
peach test generate "log in and verify the welcome screen"
peach test start # begin a live-authored draft
peach do tap loginButton
peach test keep
peach test end --output .maestro/login.yaml --validate
peach test init # scaffold .maestro/login.yaml
peach test --list-compat # verb support matrix

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:

---
app: 8081
electron: true
---

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:

terminal
npm i -D peachsim jest
terminal
peach test e2e/ --app 8081 # run the suite in e2e/ against the app on :8081
peach test init --detox # scaffold config + sample test
peach test e2e/ --watch # jest watch mode
peach test e2e/ -t "login" # filter by name

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.