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:

terminal
peach open 8081
peach test .maestro/login.yaml
peach test .maestro/ # top-level flows or configured workspace

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:

flows:
- 'flows/**'

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.

terminal
peach test init

scaffolds .maestro/login.yaml with a runnable starter flow (launch, tap, type, assert).

What’s supported

The compat matrix is built in:

terminal
peach test --list-compat

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:

terminal
peach test .maestro/login.yaml --env USERNAME=alice

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:

symptomfix
selector not foundread 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 simstart the dev server, then peach open <port>; peach list should show a connected sim before you run flows
a verb errors as unsupportedpeach test --list-compat for the matrix; faker and startRecording are not supported; use --record for video
step typed the string undefinedit did not: an undefined ${NAME} fails the step; pass it with --env NAME=value
assertion runs before the UI settlesprefer waitFor / extendedWaitUntil on the condition over fixed sleeps

Recordings

Add --preview and the run records itself and uploads a recording to a preview link:

terminal
peach test .maestro/checkout.yaml --preview

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.

Next