Maestro suites
peach test runs existing Maestro YAML flows against Peach’s in-browser engine.
Replace maestro test with peach test to run your .maestro/ directory.
No Xcode, no .app, no simulator.
Run your existing flows
Start your app’s dev server, open it in Peach, then point the runner at a flow or a directory:
Without .maestro/config.yaml, a directory run selects only YAML flows directly
inside .maestro/, matching Maestro. For suites under .maestro/flows/, create
.maestro/config.yaml before running the directory:
Then run peach test .maestro/ locally or in CI. Alternatively, run
peach test .maestro/flows/ directly. Keep shared subflows outside the
selected globs; runFlow can still load them.
Directory runs mirror Maestro’s workspace behavior: config.yaml discovery,
flows: inclusion globs, includeTags / excludeTags against each
flow’s frontmatter tags, and executionOrder: flows named in flowsOrder run
first in that order, and continueOnFailure: false skips the rest of that
sequence after a failure. A multi-flow run prints a per-flow pass/fail summary
and exits nonzero when any flow fails, so CI can gate on the exit code.
Start from scratch
Tests need a free Peach account. Run peach login, or set PEACH_API_KEY from
peach auth key create or Billing → API Keys.
scaffolds .maestro/login.yaml with a runnable starter flow (launch, tap,
type, assert).
What’s supported
The compat matrix is built in:
Supported verbs include tapOn, longPressOn, inputText, assertVisible,
assertNotVisible, waitFor, extendedWaitUntil, scroll,
scrollUntilVisible, swipe, takeScreenshot, repeat, runFlow,
runScript (Maestro JS with http, output, env vars), evalScript,
copyTextFrom, openLink, setLocation, travel, inputRandom*,
when: conditions, and ${...} JS-expression interpolation at step time.
setAirplaneMode logs that iOS simulators have no airplane mode and
continues, as Maestro does.
Env interpolation seeds from your full shell environment, and a bare
${NAME} that is undefined fails the step instead of typing the string
undefined into your app:
When a step fails
The runner captures a per-failure bundle next to your run, named by the failing step: a screenshot, the rendered tree, the accessibility tree, console output, and the error. That is usually enough to fix a selector without re-running anything.
Each run gets its own directory under the system temporary directory’s
peach-flow/ folder. The CLI prints the exact failure bundle path. With
--out or --screenshots, bundles go under that directory with unique names,
so concurrent failures cannot overwrite one another. A test’s simulator lock
releases when its connection closes, including on failure or interruption.
The common failures and their fastest fixes:
| symptom | fix |
|---|---|
| selector not found | read the tree in the failure bundle, or peach describe against the live sim; match on testID over display text where you can |
| “could not connect” / no sim | start the dev server, then peach open <port>; peach list should show a connected sim before you run flows |
| a verb errors as unsupported | peach test --list-compat for the matrix; faker and startRecording are not supported; use --record for video |
step typed the string undefined | it did not: an undefined ${NAME} fails the step; pass it with --env NAME=value |
| assertion runs before the UI settles | prefer waitFor / extendedWaitUntil on the condition over fixed sleeps |
Recordings
Add --preview and the run records itself and uploads a recording to a preview
link:
The command prints a /preview/<id> link where anyone on your team can watch
the recording and scrub through every step. Runs that uploaded a recording (and
every run in CI) are also registered in your
dashboard with pass/fail, duration, and a
per-step trace.