Skip to content

Early Adopter Offer:Get 40% off Core & Scale for your first year with code EARLYQFView pricing

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

A Maestro run branches into two reporting paths: a JUnit XML file for CI, or a Qualflare wrapper report with available steps and screenshots but no retained JUnit. Either can optionally be uploaded to a Qualflare launch.
Direct JUnit keeps flow outcomes and an XML file for CI test reports. The wrapper adds available command details and screenshots, but leaves no JUnit file. Collection requires setup; AI features and history-based signals have additional requirements. The wrapper needs Maestro 2.6+ (2.10+ for nesting) and qf 0.1.24+ for screenshot uploads. Duplicate flow names and repeated flows under --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. assertVisible retries for up to seven seconds by default; do not assume every command or tapOn variant has the same timeout. For a genuinely slow step — payment confirmations, cold app starts — reach for an explicit extendedWaitUntil: { visible: "...", timeout: 30000 } rather than inflating the whole suite’s patience.
  • Sharded runs need real connected devices, not just a flag. --shard-split distributes flows across connected devices; --shard-all repeats 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 --output and Maestro writes report.xml to 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 runsArchive and compare filesSuccessive uploads
Aggregates Espresso + XCTest + Maestro in one dashboard—Yes
Failure clusteringNot in JUnit aloneAI enabled; eligible plan/capacity
Flaky-flow scoringNot in one reportEnough matching results
Nested command stepsArtifacts vary by versionWrapper + Maestro 2.10+; attribution limits
Available screenshotsHTML/artifacts; not JUnit aloneWrapper + qf 0.1.24+; 30-day retention
Early setup errorsMay have logs but no JUnitIf wrapper captures and writes them
Local inspection without uploadYesDry-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 Free

Testing 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

All updates on the Qualflare changelog

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.