| name | maestro-qa |
| description | Use when a React Native or Expo app needs local mobile QA with Maestro plus targeted fixes. Starts with a report-only Maestro pass, isolates one verified failure at a time, maps it back to app or flow code, applies the smallest fix, and reruns the narrowest failing flow before broadening back out. |
| metadata | {"tags":"maestro,mobile,qa","groups":"mobile-qa","invocation":"model"} |
Maestro QA
Overview
Use Maestro to verify mobile behavior, fix verified issues, and rerun the smallest useful surface.
This skill extends maestro-qa-report. Start with the report-only pass to prove failures and collect artifacts. Then move through a strict fix loop: one verified issue, one scoped change, one targeted rerun.
Default workflow
1. Start with a report-only run
Before changing code, run the report-only workflow:
skills/maestro-qa/scripts/run-maestro-qa.sh \
--repo /path/to/app \
--flow-path .maestro \
--output-dir build/maestro-results \
--report-format html-detailed \
--report-file build/maestro-report.html
This delegates to the report helper and preserves the same artifact layout.
2. Choose one verified failure
Pick one issue using this order:
- blocker on a critical flow
- major issue with a release-significant path
- minor issue that is isolated and easy to confirm
Do not batch unrelated fixes. If multiple flows fail, choose one and ignore the rest until the first fix is verified.
3. Map the failure to the right owner
Classify the failure before editing:
- app bug
- broken or stale Maestro flow
- environment or seed-data problem
- backend dependency or flaky service
Only fix what is actually broken. Do not patch app code to compensate for a bad flow. Do not patch a flow to hide a real product bug.
4. Apply the smallest fix
Prefer:
- stable selectors or accessibility labels over text-only selectors
- the smallest code change that restores the intended user path
- targeted test data or environment fixes when the app code is not at fault
Keep notes on:
- the failing flow and step
- the file you changed
- why the change matches the verified failure
5. Rerun the narrowest surface
After each fix:
- rerun the single failing flow or tagged subset
- if that passes, rerun the local smoke set
- only then broaden back to the larger suite if needed
Do not rerun the entire suite after every edit unless the scope is already tiny.
6. End with a QA summary
Report:
- issues fixed
- issues still failing
- flows rerun
- artifact and report paths
- remaining risk before release or handoff
Fix loop rules
| Rule | Why |
|---|
| prove the failure first | avoids speculative fixes |
| fix one issue at a time | keeps causality clear |
| rerun the smallest surface first | reduces feedback time |
| preserve report artifacts | keeps evidence for later review |
| separate app bugs from flow bugs | prevents false confidence |
Helper usage
Use the bundled helper to keep the run shape consistent:
skills/maestro-qa/scripts/run-maestro-qa.sh \
--repo /path/to/app \
--flow-path .maestro/login.yaml \
--include-tags smoke
For a non-executing preview:
skills/maestro-qa/scripts/run-maestro-qa.sh \
--repo /path/to/app \
--flow-path .maestro \
--dry-run
Common mistakes
- editing code before proving the Maestro failure
- fixing multiple failures in one pass
- widening the rerun scope too early
- changing flows to hide a real product regression
- stopping after one flow passes without checking the adjacent smoke surface
Example
If the user asks:
run maestro qa, fix the broken onboarding flow, and verify it
do this:
- run the report-only pass and capture artifacts
- isolate the onboarding failure to one step and one likely owner
- make the smallest fix
- rerun the onboarding flow
- rerun the nearby smoke flows
- report what was fixed, what still fails, and where the artifacts live
