Maestro test reporting
Maestro can produce JUnit XML for CI test reports and HTML reports and artifacts for local debugging. To keep results across runs in Qualflare, choose between collecting that XML and using a native Maestro reporter that builds a report from available steps and screenshots. Both paths support hosted, historical reporting; the evidence they retain differs. This guide covers the choice, local inspection, CI collection, and the history and AI requirements that come after an upload.
Worth saying up front: Qualflare doesn’t run your Maestro flows, and neither does the reporter own your
devices — it wraps the maestro test command you already
run, wherever it already runs. Qualflare is a results and observability layer, not a device-execution
cloud.
How Maestro flows and JUnit reporting work
--shard-all lose step/screenshot attribution, not their outcomes.
Maestro is an open-source, YAML-based UI testing framework for Android, iOS, and web apps, built by
mobile.dev. A “flow” is a plain YAML file — launchApp,
tapOn, inputText,
assertVisible. Flows can reuse steps across platforms
when app identifiers, selectors and behavior match. Maestro supports Android devices/emulators and
iOS simulators; physical iOS devices are not supported. Here is a simple flow:
# .maestro/login.yaml — a Maestro flow: readable YAML, not code
appId: com.example.app
---
- launchApp
- tapOn: "Log In"
- inputText: "[email protected]"
- tapOn: "Password"
- inputText: "hunter2"
- tapOn: "Submit"
- assertVisible: "Welcome back" Maestro writes JUnit XML natively, without a converter. With Maestro installed, your app installed and a device connected, this terminal example gives the run a fresh output directory and records its exit code. A failed flow may still produce a useful report:
# Run in your terminal; keep this shell open for the next commands
run_dir=$(mktemp -d "${TMPDIR:-/tmp}/maestro-report.XXXXXX")
maestro_status=0
maestro test --format junit --output "$run_dir/results.xml" .maestro/ || maestro_status=$?
printf 'Maestro exit code: %s\n' "$maestro_status"
Per Maestro’s own docs,
“JUnit is the standard for CI/CD integration and for test reporting.” Point the command at a directory
to report flow outcomes. JUnit is useful for CI test tabs and downstream collection; HTML and
html-detailed support local inspection, with visual
evidence depending on the format and artifacts the run produced. Use
--test-output-dir for test artifacts and
--debug-output for debug logs; the JUnit
--output path is separate. Check the
Maestro repository
and current docs for the version you run.
When to keep local reports and when to collect history
The JUnit-XML file maestro test writes is excellent
at describing one run — which flows passed, which failed, and why. Its limits show up the same
way any single-run report’s do: nothing connects today’s report.xml to
yesterday’s automatically. Archive successive reports if you need to compare them. HTML and local
artifacts may be all you need to investigate one failure; hosted collection becomes useful when you
want shared access, accumulated history and results from multiple frameworks in one project.
Qualflare accepts results generated locally as well as in CI. It does not replace your runner or native artifacts. Start with the output that fits your workflow, inspect it locally, and collect it if you want a hosted launch. History and flaky-case scoring need successive matching results.
Before collecting results
Create a Qualflare account, workspace and project, install qf, and save a project access
token. In these examples myapp is your saved local CLI identifier; the token selects
the project. Login saves credentials but does not verify server access. Keep tokens in your terminal
or CI secret store. See the setup guide.
brew install qualflare/tap/qf
# Or: npm install -g @qualflare/cli
qf version
qf login myapp # paste the token at the hidden prompt CI patterns: GitHub Actions, GitLab CI, and Maestro Cloud
GitHub Actions. Run the flows against whatever emulator or
simulator the job already has connected, with the
native reporter wrapping the command, then
collect any fresh report even when tests fail. These are steps excerpts,
not complete workflow files: your job must already check out the code, install Maestro/qf/the wrapper,
install and launch the app/device, and configure the myapp login from a CI secret.
Allocation uses a unique directory; the test step keeps its failure status:
# Excerpt from steps: in an already configured GitHub Actions job
- name: Allocate fresh output
id: report
shell: bash
run: |
report_dir=$(mktemp -d "$RUNNER_TEMP/maestro.XXXXXX")
echo "dir=$report_dir" >> "$GITHUB_OUTPUT"
- name: Run Maestro flows
shell: bash
env:
REPORT_DIR: ${{ steps.report.outputs.dir }}
run: qualflare-maestro -output-dir "$REPORT_DIR/report" -- maestro test .maestro/
- name: Collect available results, including failed tests
if: always() && steps.report.outcome == 'success'
shell: bash
env:
REPORT_DIR: ${{ steps.report.outputs.dir }}
run: |
test -d "$REPORT_DIR/report"
qf myapp collect "$REPORT_DIR/report"
Without the reporter the shape is the same, with Maestro writing JUnit-XML and
--format maestro on the upload:
# Alternative steps: excerpt for a job using native JUnit
- name: Allocate fresh output
id: report
shell: bash
run: |
report_dir=$(mktemp -d "$RUNNER_TEMP/maestro.XXXXXX")
echo "dir=$report_dir" >> "$GITHUB_OUTPUT"
- name: Run Maestro flows
shell: bash
env:
REPORT_DIR: ${{ steps.report.outputs.dir }}
run: maestro test --format junit --output "$REPORT_DIR/results.xml" .maestro/
- name: Collect available results, including failed tests
if: always() && steps.report.outcome == 'success'
shell: bash
env:
REPORT_DIR: ${{ steps.report.outputs.dir }}
run: |
test -s "$REPORT_DIR/results.xml"
qf myapp collect "$REPORT_DIR/results.xml" --format maestro
If the run writes no report, the output check fails rather than collecting a previous run. Validate
parsed test names and counts while setting up the job, using --dry-run --output json.
Do not mark the test step successful merely to let collection run. Cancellation or forced termination
can still prevent report creation or upload.
GitLab CI. GitLab renders JUnit XML natively in the pipeline’s
Tests tab, and that is a real reason to keep the XML path: the reporter owns
--output and clears the file away once it has read it,
so a single run cannot produce both its report and a JUnit file for GitLab to render. Pick per job — the
Tests tab, or the fuller report:
# Job excerpt: runner, tools, app and device already configured
maestro-e2e:
script:
- mkdir "maestro-$CI_JOB_ID"
- maestro test --format junit --output "maestro-$CI_JOB_ID/results.xml" .maestro/
artifacts:
when: always
reports:
junit: "maestro-$CI_JOB_ID/results.xml" Maestro Cloud. mobile.dev’s own paid product is a different
execution service with its own reports and dashboard links. If you execute flows on Maestro Cloud instead of (or
alongside) self-hosted emulators, the XML path is the one to use — the reporter works by wrapping the
maestro test command, which you don’t run when the
flows execute on managed devices. Point qf collect at
whatever JUnit-XML file that run produced. Qualflare cares about the results file, not where the flow
executed — check Maestro Cloud’s own CI integration docs for exactly how it exposes that file as a
build output or artifact.
Common Maestro reporting problems (and fixes)
The Bitrise Mobile Insights Report 2025 found changes in flakiness within its observed customer/build data. That is context, not a measurement of Maestro users or proof of the causes below. For a missing or misleading report, check these concrete boundaries first.
- Separate parsing errors from selector failures. Invalid YAML or setup errors can stop execution before a JUnit file exists. A syntactically valid selector that matches nothing is a different failure: inspect the actual UI and the command error. Use Maestro’s test-output directory for available screenshots/command artifacts and its debug-output directory for logs. Neither flag guarantees that every step has a screenshot or hierarchy dump.
- Element-matching timing on slower CI emulators.
assertVisibleretries for up to seven seconds by default; do not assume every command ortapOnvariant has the same timeout. For a genuinely slow step — payment confirmations, cold app starts — reach for an explicitextendedWaitUntil: { visible: "...", timeout: 30000 }rather than inflating the whole suite’s patience. - Sharded runs need real connected devices, not just a flag.
--shard-splitdistributes flows across connected devices;--shard-allrepeats flows on each device. Neither provisions devices. Check the connected-device count before raising the shard count. With the Qualflare wrapper, repeated flow names under shard-all prevent step/screenshot attribution. - The results file location becomes a collision risk. Omit
--outputand Maestro writesreport.xmlto the current working directory by default. Collisions occur when concurrent processes share that filesystem, or artifacts are merged into the same path. Separate GitHub-hosted jobs have separate VMs; identical filenames alone do not make them overwrite one another. Use distinct per-run output paths and archive names, especially on shared self-hosted storage. - The upload step never runs on a failing build. The same
ordering mistake as any framework: if the upload step doesn’t run with
if: always()(or the equivalent “run even on failure” setting on your CI platform), the failing run — the one you most need visibility into — never reaches Qualflare at all.
Send Maestro results to Qualflare
The Qualflare wrapper runs maestro test, sets the
output flags it needs, reads the artifacts Maestro leaves behind, and writes a report directory.
It supports local and CI test runs, not maestro cloud, maestro record or
continuous mode. Install it once, after setting up Maestro and qf:
brew install qualflare/tap/qualflare-maestro
# or: go install github.com/Qualflare/qualflare-maestro/cmd/qualflare-maestro@latest
Put qualflare-maestro -- in front of the command you
already run, with reporter options before --. When Maestro runs, its exit code passes
through; usage/startup/report-writing errors can return the wrapper’s own error code. The reporter
makes no network calls. In your terminal, keep this shell
open while you inspect the new directory:
# Run in your terminal; use a fresh directory for this run
run_dir=$(mktemp -d "${TMPDIR:-/tmp}/maestro-report.XXXXXX")
maestro_status=0
qualflare-maestro -output-dir "$run_dir/report" -- maestro test .maestro/ || maestro_status=$?
printf 'Maestro/reporter exit code: %s\n' "$maestro_status"
# Parse locally even if tests failed; missing output is an error
qf myapp collect "$run_dir/report" --dry-run --output json
Check that parsing found tests and that their names, counts and pass/fail outcomes match this run.
Stop on missing, invalid or empty output. The recorded maestro_status remains the run’s
status even if parsing succeeds; dry-run is not an upload. If you want to collect this inspected
report, run the following once:
# Run separately after checking the dry-run output
qf myapp collect "$run_dir/report" qualflare-maestro .maestro/ is shorthand for the same
thing. The wrapper owns --format, --output, --debug-output and
--flatten-debug-output; passing them yourself is a usage error. Other Maestro flags can
follow the explicit -- maestro test form. It needs
Maestro 2.6.0 or newer, and screenshots upload with
qf 0.1.24 or newer. Nested runFlow,
repeat and retry steps need Maestro 2.10+. In CI it replaces the
maestro test step, as in the
GitHub Actions example above.
Evidence has boundaries. Duplicate flow names, including
a flow repeated on several devices with --shard-all, keep outcomes but lose steps and
screenshots because the artifacts cannot be attributed safely. Early errors such as invalid YAML
or no device can appear in the report if the wrapper captures the error/log and finishes writing;
forced termination can prevent this. On Maestro 2.6.x’s flat layout, specify
-platform android for Android. See the
documented reporter limitations.
Inspect what you share. The wrapper replaces known
--env and MAESTRO_* values of at least four characters in report text,
excluding Maestro settings and boolean values. Values from flow env: blocks, scripts,
files or argument files are not covered. Screenshots and filenames are not comprehensively redacted;
unattributed error log tails may include local paths and device IDs. This is useful filtering,
not a guarantee that every artifact is free of sensitive data.
Without the reporter: uploading JUnit-XML
If you would rather not add a binary to the job, Qualflare still reads the JUnit-XML Maestro writes — you get flow outcomes rather than the wrapper’s command-level evidence. Keep this path when another tool needs the XML file, such as GitLab’s Tests tab. Generate a fresh file in your terminal:
# Run in your terminal; keep this shell open for the next commands
run_dir=$(mktemp -d "${TMPDIR:-/tmp}/maestro-report.XXXXXX")
maestro_status=0
maestro test --format junit --output "$run_dir/results.xml" .maestro/ || maestro_status=$?
printf 'Maestro exit code: %s\n' "$maestro_status"
Parse it first and check that it contains this run’s tests and outcomes. Then, as a separate action,
upload it with --format maestro so the launch is
labeled correctly. Keep the same shell so run_dir still points to that run:
# Parse locally first; stop if output is missing, invalid or empty
test -s "$run_dir/results.xml" &&
qf myapp collect "$run_dir/results.xml" --format maestro --dry-run --output json Only after a successful parse with matching, nonzero test counts, collect the file once:
# Run separately, only after checking names, counts and outcomes
qf myapp collect "$run_dir/results.xml" --format maestro
Worth being precise about what that flag does: it routes through the exact same JUnit-XML-compatible
ingestion path used for other compatible XML reports. A Maestro JUnit-XML file has the same
<testsuite>/<testcase>
structure. The flag labels the launch as Maestro in the dashboard, rather than unlocking
different parsing behavior; include it to retain that label. The CLI identifies a results file by
what is inside it, and a Maestro report’s root element is an ordinary
<testsuite>, so naming the file
maestro-results.xml changes nothing: without
--format maestro the launch is labeled plain JUnit.
The wrapper’s report already identifies its framework. For CI authentication and setup, see the
CLI docs.
What you get on top of Maestro’s own output
- Command evidence where available. The wrapper can attach the steps and screenshots Maestro produced, helping you investigate a failed flow. Its version and attribution limits still apply.
- Failure clustering. On eligible projects, similar failure results can be grouped for investigation. A suggested root cause is a starting point to verify, not proof that all grouped failures share one cause.
- Flaky-flow scoring from history. By default, a case needs at least 10 results in its last 25 launches, with a minority pass/fail outcome of at least 30%. Project Quality settings can change these thresholds; a single JUnit file does not establish a flaky pattern.
- Cross-framework review. Upload Maestro, Espresso and converted XCTest results into the same project to review them together. Separate uploads create separate launches; use supported run/shard grouping deliberately rather than assuming uploads merge automatically.
- Launch analysis when eligible. An uploaded launch can receive a summary, failing areas and recommendations. Its risk level is computed from the pass rate of tests that ran; it is not a ship/don’t-ship verdict.
- History & trends. Successive matching results build pass-rate and flaky-case history. Consistent case identity and useful branch/platform metadata make those comparisons easier to interpret.
- Incidental reach into React Native and Flutter results. Maestro drives the UI regardless of the underlying app framework, so if your team also uses it to test a React Native or Flutter app, those flow results land in the same dashboard too, through the same JUnit-XML pipeline. Flutter’s own widget and integration tests now report directly as well, with no Maestro in between — see Flutter test reporting.
AI Launch Analysis requires project AI enabled, an active subscription and available analysis allowance. Starter includes 250 report uploads and 25 launch analyses per month as separate allowances. Exhausted analysis allowance does not remove already uploaded results, but new failing runs are not clustered until it resets. Failure clustering also depends on plan/capacity: Starter holds up to five clusters workspace-wide, Open Source excludes clustering, and a cluster is named once it contains five failures. See flaky-case scoring for the separate history-based signal.
Uploaded screenshots, videos and traces are deleted after 30 days. Keep independent copies of artifacts you need longer; see the collection and retention documentation.
Native local output and optional hosted collection
| Native files | Collected in Qualflare | |
|---|---|---|
| History across local or CI runs | Archive and compare files | Successive uploads |
| Aggregates Espresso + XCTest + Maestro in one dashboard | — | Yes |
| Failure clustering | Not in JUnit alone | AI enabled; eligible plan/capacity |
| Flaky-flow scoring | Not in one report | Enough matching results |
| Nested command steps | Artifacts vary by version | Wrapper + Maestro 2.10+; attribution limits |
| Available screenshots | HTML/artifacts; not JUnit alone | Wrapper + qf 0.1.24+; 30-day retention |
| Early setup errors | May have logs but no JUnit | If wrapper captures and writes them |
| Local inspection without upload | Yes | Dry-run locally; hosted use needs upload |
Keep Maestro’s HTML report and test artifacts for local debugging; collect results when shared access and history are useful. Command/screenshot collection needs qualflare-maestro and the stated version/attribution conditions. JUnit collection can also build history; AI and flaky-case features retain their separate eligibility and history requirements.
Inspect your first hosted Maestro report
Start free, choose an output path, check a fresh report locally, then upload it once. Open the new launch and confirm its test names and outcomes. History builds over later runs; AI analysis depends on the settings and allowances above.
Get Started FreeTesting the native layers too? See Espresso test reporting for Android and XCTest test reporting for iOS, and how to get all three into one dashboard. Want the detail on what the JUnit file does and does not carry? See what Maestro’s JUnit XML leaves out, measured against real 2.6.1 and 2.10.0 output. Chasing intermittent flows? Read fixing flaky mobile tests or the mobile testing complete guide. Qualflare supports Maestro alongside other test frameworks — see the full list, or browse all framework reporting guides. Weighing tools? See how it compares to other test management platforms.
Frequently asked questions
Does Maestro produce JUnit-XML natively, or do I need a converter?
Natively — no converter needed. Running maestro test --format junit --output <file> <flowFiles> writes a standard JUnit-XML report directly, the same as Espresso and unlike XCTest’s .xcresult bundles, which need a separate conversion step. Maestro’s own docs describe JUnit as “the standard for CI/CD integration and for test reporting.”
Does Qualflare run my Maestro flows on real devices or emulators?
Qualflare hosts results; it does not provision devices or execute your flows. Run Maestro locally or in your CI environment, then upload its JUnit XML or the Qualflare wrapper’s report directory. The wrapper launches maestro test using your existing device setup; it does not wrap maestro cloud. For Maestro Cloud, export the run’s JUnit XML for collection.
Does this replace Maestro Cloud?
No. Maestro Cloud runs flows on managed devices and has its own reports and dashboard links. Qualflare is an optional destination for exported JUnit XML when you want to collect results alongside other frameworks. History depends on successive uploads; flaky scoring needs enough results, and AI features depend on settings and plan allowances.
Can Qualflare aggregate Maestro results alongside Espresso and XCTest?
Yes. Collect each framework’s supported output into the same Qualflare project: Maestro JUnit XML, Espresso XML and converted XCTest JUnit XML. Use a saved CLI identifier whose token selects that project, and the appropriate format label for each framework. Results can then be reviewed in the same project; separate uploads create separate launches rather than automatically becoming one combined run.
How do I send Maestro results to Qualflare?
Install qf and save a project token with qf login myapp; myapp is a local identifier, and the token chooses the project. Either run Maestro with --format junit and an explicit fresh --output path, then collect that file with --format maestro, or run qualflare-maestro -- maestro test and collect its fresh report directory. Parse with --dry-run --output json first, check nonzero test counts and matching outcomes, then upload once. Keep collection separate from test success so failed tests can be reported. The wrapper makes no network calls; qf performs the upload.
What does the native Maestro reporter add over Maestro’s JUnit-XML?
It builds a report directory from Maestro’s available command artifacts, screenshots, flow tags and qualflare.* metadata. It requires Maestro 2.6+; nesting under runFlow, repeat and retry requires 2.10+, and screenshot upload requires qf 0.1.24+. Duplicate flow names or a flow repeated across devices with --shard-all keep outcomes but lose step/screenshot attribution. Early errors can be reported if the wrapper captures them and writes its report; forced termination can prevent this. It leaves no JUnit file. Text redaction covers known --env and MAESTRO_* values of at least four characters, with settings/boolean exclusions; flow env blocks, scripts, argument files, screenshots and filenames are not comprehensively protected.
Does Qualflare detect flaky Maestro flows?
Yes, once enough matching case results have accumulated. By default, a case needs at least 10 results in its last 25 launches, with the less common outcome, pass or fail, reaching 30%. Maestro’s JUnit XML does not provide a per-attempt flaky flag, so this is a history-based signal rather than a conclusion from one uploaded run. Project Quality settings can change the thresholds.
Recent updates
Setup reflects the Qualflare CLI (docs.qualflare.com) and Maestro’s CLI docs as reviewed in November 2026, including the qualflare-maestro reporter’s documented limits. Published 14 August 2026. Last updated November 2026. Written by İbrahim Süren, founder of Qualflare.