assertWithAI,
assertNoDefectsWithAI, extractTextWithAI) are experimental commands that
wrap a customer-supplied LLM.
Speed and caching
How the multi-modal cache works
A cached step stores more than one way to find the target: where it sits on screen, what it looks like, what text it contains, and the accessibility and structural attributes around it. Which of those signals matters for a given step is inferred from the natural-language description. “The red Cancel button below the Order Summary header” leans on visual and positional signals; “the Sign in button” leans on accessibility and text. When a step replays, the runner checks the stored signals against the live UI and runs the action without invoking the LLM when there’s a match.What happens on a UI change
A practical sequence that shows the difference. Take a mobile sign-in screen with anemail_input resource ID, after a passing baseline run where the cache
is warm.
Refactor: the app team renames email_input to email_field and changes
the surrounding container hierarchy.
Maestro replay:
tapOn: { id: "email_input" }retries against the device for ~5s.- The retry window elapses with no match. The step fails.
- The test stops; the CI job fails. Someone edits the YAML to use the new ID or
switches the selector to a
textmatch, opens a PR, gets it merged, and re-runs CI.
- The cached locator for the
Emailstep misses on the live UI. - The locator agent re-resolves the original natural-language description
Email. - The new locator binds, the step runs, the test passes.
- The cache entry is updated in place. A heal event is attached to the run for review. Subsequent runs hit the cache normally.
Maestro waiting
Maestro waiting
Selector commands have a default ~5s retry window with animation tolerance.
WebViews require app-side debug enablement; XHR is not tracked. Long flows
reach for
extendedWaitUntil { visible: ..., timeout: ... }.Locators and AI primitives
Technical details
Technical details
Momentic mobile step types
- Action:
act,tap,doubleTap,longPress,type,swipe,scroll,back,dismissKeyboard,launchApp,terminateApp - Assert:
assert,assertVisually,checkElement<...> - Extract:
extract(typed via JSON schema) - Control flow:
if/then, modules, parameter inputs
assertWithAI default
(source)SinceA team that wants AI assertions to fail the test must setassertWithAIis an experimental feature,optionalis set totrueby default to prevent unstable AI responses from breaking your CI/CD pipelines. If you want a failed AI assertion to stop the test, you must explicitly setoptional: false.
optional: false on
every call site because Maestro has no project-level default.Recovery, quarantine, and CI
Quarantine semantics
Quarantine semantics
- Default: quarantined tests run, results report, exit code unaffected.
--skip-quarantined: skipped entirely.--only-quarantined: only quarantined tests run; statuses affect exit code.
Authoring side-by-side
email_input is renamed or "Sign in" is localized, the YAML breaks until
someone edits it.
Agentic simplified format:
A more realistic test
The hello-world above doesn’t show the full simplified format surface. A representative onboarding regression with module reuse, parameter inputs, typed extraction, and a conditional looks like this:onboarding.test.yaml
../modules/sign-in.module.yaml