Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Maestro performs visual regression checks with assertScreenshot: at a chosen point in a UI flow, it compares the current screen with a known-good reference image and fails if the reference is missing or the match falls below the configured threshold. The documented default is 95%. Use this as a rendered-image check alongside functional assertions—not as proof that an entire app experience works.
What Maestro checks—and what it does not
Maestro flows are declarative YAML UI automation. The framework describes itself as open-source and capable of automating mobile and web interfaces. Its screenshot assertion compares an image of the current screen with a reference image at the point where the command runs.
That makes assertScreenshot useful for checking whether a screen still looks sufficiently like an approved baseline. It does not, by itself, establish that buttons work, the right data was saved, business rules are correct, or the interface is accessible. Keep interaction and state checks in the flow as needed, and treat the screenshot as one complementary check of the rendered result.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteThe command reference identifies a path to the reference screenshot, which may have been created earlier with takeScreenshot. The assertion fails if that reference is absent or if the current image is too dissimilar under the configured threshold. The documentation does not establish the image algorithm, pixel-diff behavior, anti-aliasing policy, or color handling, so do not infer those details from the pass/fail result.
Build a visual regression flow
- Set up the state. Launch the app, navigate to the screen, and arrange the data and UI state the test is intended to cover. A baseline only has value if later runs reach a comparable state.
- Capture and review the baseline. Use Maestro’s screenshot command to capture the screen at the target point. Review the image deliberately, then manage it as a test artifact—for example, by committing it with the flow where your team stores test assets.
- Add the assertion. Point
assertScreenshotat the reference image. Start with the documented default or specify a numeric threshold explicitly. - Run the flow in the intended environment. Check the actual target device or simulator configuration and app state, not just whether the YAML parses.
- Review failures before changing the baseline. Determine whether the image exposes an unintended regression or a deliberate design change. If the design change is approved, update the reference and review that image change as part of the same code review.
Minimal assertion
- assertScreenshot: splash.pngThis compact form uses the reference path. The documented default thresholdPercentage is 95, meaning the assertion requires the specified percentage match to pass. The threshold is not a universal quality score; it is a setting to calibrate for the screen and the kinds of changes your team considers acceptable.
Explicit threshold
- assertScreenshot:
path: ./screenshot.png
thresholdPercentage: 95Set a numeric value explicitly when you want the flow itself to show the intended tolerance. A flow can also resolve the value from a variable, which can help vary the threshold by environment or device. The variable must resolve to a number: an unset variable does not silently fall back to the default.
Choose full-screen or cropped coverage
Use a full-screen comparison when surrounding layout is part of what you want to protect: navigation, spacing, content placement, and the screen as a whole. If unrelated screen regions make a check noisy, Maestro documents cropOn with an element selector to limit the comparison area.
Cropping has a baseline requirement: the reference screenshot must have been cropped in the same way as the current comparison. If baseline creation and later test execution use different crop conventions, you are not comparing equivalent images. Keep the selector and capture convention stable, and update the reference deliberately if the intended element or its bounds change.
A crop narrows the visual question rather than making it more comprehensive. A check of one control will not catch a regression in a header or layout outside the crop. Choose the region according to the risk you want to catch, and retain other checks for areas and behaviors the image does not cover.
Make comparisons reproducible
A screenshot comparison is useful only when ordinary run-to-run variation does not overwhelm the change you care about. The flow should reach the same relevant app state and run under a defined target environment. In practice, consider these inputs when establishing a baseline and interpreting a failure:
- Device and viewport: compare on the intended device or simulator configuration. A different screen size or device can change layout, so treat it as a different target when appropriate.
- Locale and environment: text length and other environment-dependent content can alter the rendered screen. Make the test environment intentional and keep it consistent with the coverage you want.
- App state: use known data and navigation state, and place the assertion after the UI has reached the screen you mean to validate.
- Reference provenance: keep the reference associated with the flow and review it when intentionally updated. Do not accept a changed image automatically merely to silence a failure.
- Threshold: choose a numeric tolerance based on acceptable UI variation and the consequence of missed differences. A looser threshold can allow more image difference; a stricter threshold can make small changes fail. Calibrate rather than assuming 95% is right for every screen.
Maestro Cloud is an optional hosted execution path. Its documentation describes isolated virtual devices that are wiped and recreated between tests, configurable Android API levels or iOS models, and supported Android, iOS, React Native, Flutter, and Web targets. It also documents native CI integrations for GitHub Actions, Bitrise, Bitbucket, and CircleCI, plus GitHub pull-request integration that can block a merge on test failure. These are vendor-described capabilities; confirm that the current service, target, and terms fit your requirements before adopting it.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Maestro’s Cloud page says teams can reduce test execution time “by up to 90% through asynchronous parallel runs.” This is a vendor claim, not an independently established benchmark or a guaranteed result. Parallel hosted execution may suit large suites or teams that value managed environments; local CLI execution may suit teams that prefer to control their execution setup. Decide based on required device coverage, operational control, suite scale, CI workflow, and service terms.
Visual checks, functional checks, and test coverage
A passing screenshot assertion says that the current image met the command’s configured comparison requirement against its reference. It does not say that every user path has been tested, that every element is interactive, or that assistive technology presents the interface correctly.
Rank #4
Pair the screenshot with functional assertions where behavior matters: for example, verify the expected screen or state through the flow, then check its appearance at a meaningful point. Keep tests focused on a user-visible outcome rather than attempting to make one screenshot stand in for a complete end-to-end test. For a screen with several materially different states, create checks for those states rather than assuming one baseline covers them all.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common failures
The reference image is missing
assertScreenshot fails if its reference is absent. Check the path, filename, relative location, and whether the reference artifact is present in the environment where the flow runs. If the baseline is generated in a separate step, ensure that step actually produced the image at the path the assertion uses.
The assertion fails after a visual change
Inspect the current screen and baseline before deciding what to do. If the change is unintended, fix the UI or test setup. If it is deliberate and approved, capture and review a new baseline, then include it in the change review. Raising the threshold solely to make the test pass can conceal changes the test was meant to catch.
Best Value
A variable threshold does not work
Confirm that the variable is defined in the environment running the flow and resolves to a number. The command documentation does not describe an unset variable as falling back to 95%; provide a valid value or use an explicit numeric threshold.
A cropped comparison still fails unexpectedly
Verify that the reference image was cropped in the same way as the current capture and that the element selector identifies the intended element. If you changed the selector or the target region, regenerate and review the matching baseline rather than mixing crop conventions.
The screenshot check passes but a behavior is broken
Add or repair a functional assertion for that behavior. A visual match is an image-level result, not a substitute for checking navigation, interactions, saved state, or other application logic.
Or skip the browser setup
Maestro is the relevant choice for screenshot checks inside an app flow. For a separate use case—capturing a web page from a URL without setting up browser automation—ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP, or PDF. For example, this cURL request saves a WebP screenshot of a page:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for setup and parameters. Its consent-banner, newsletter-popup, and chat-widget removal options run before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. This captures web pages and does not replace Maestro’s in-app visual regression assertions. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Can I use a variable for thresholdPercentage?
Yes. The variable must resolve to a number; an unset variable does not restore the documented 95% default.
Does ScreenshotNeo replace Maestro for mobile app screenshot tests?
No. ScreenshotNeo captures web pages from URLs; Maestro’s assertScreenshot checks a screen within a UI flow.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
