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 comparison is too dissimilar. The documented default threshold is 95%. To make the check useful, keep the app state and capture conditions consistent, review reference-image changes deliberately, and pair screenshots with functional assertions.
What visual regression testing checks in Maestro
Maestro flows are declarative YAML UI automation. The framework describes itself as open-source and supports mobile and web testing; its overview says it interacts with devices through the accessibility layer rather than requiring app-framework-specific integration. See Maestro’s overview.
An assertScreenshot command captures the screen at the point where it runs and compares it with a reference image. The command’s path identifies that known-good image, which can be created with a prior takeScreenshot invocation. The assertion fails if the reference is missing or the current image is too dissimilar. See the official assertScreenshot reference.
This is an image-level check of a rendered screen, not proof that the whole experience works. A screenshot can reveal a changed layout or missing visual content, but it does not establish that controls behave correctly, business rules are satisfied, or accessibility is adequate. Use functional and accessibility checks where those outcomes matter.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
- Universal unlocked. Compatible with all major U.S. carriers, including Verizon, AT&T, T-Mobile and other prepaid carriers.
- Super-bright, super-smooth 6.7" display. See your screen clearly even outdoors in sunlight, and enjoy seamless views with a fast-refreshing 120Hz display.*
- AI-powered camera system. Take stunning photos in any light with the 50MP camera**, look your best with a 32MP selfie cam*****, and capture extreme close-ups.
- Superfast 5G performance. Unleash your entertainment at 5G speed*** with the MediaTek Dimensity 6300 chipset and up to 12GB of RAM with RAM Boost****.
- Long-lasting battery + TurboPower charging. Power through day after day with a 5200mAh battery, then get hours of power in just minutes.****
Build a repeatable screenshot flow
- Reach a defined app state. Navigate through the same steps each run, and control relevant variables such as account data, app content, locale, and device configuration where your setup allows.
- Capture the baseline. Use Maestro’s
takeScreenshotcommand to create the reference, inspect the resulting image, and manage it as a deliberate test artifact. The assertion’spathmust point to that image. - Add the assertion at the matching point. Run it only after the flow has brought the app to the state represented by the baseline.
- Review baseline updates. When a design change is intentional, inspect the new screenshot and update the reference as part of the same code review. Do not automatically accept a changed image without understanding what changed.
Here is a minimal YAML example; replace the illustrative reference path with the location used by your flow:
appId: com.example.app
---
- launchApp
- assertScreenshot: ./screenshots/home.pngThe flow should establish any additional prerequisites for the home screen before the assertion. Maestro’s command reference describes the assertion and reference path, but it does not prescribe a universal baseline-storage or review process.
Set and tune the threshold
The documented default thresholdPercentage is 95: the comparison must meet the configured percentage match for the assertion to pass. You can make the threshold explicit:
- assertScreenshot:
path: ./screenshots/home.png
thresholdPercentage: 95A numeric threshold can also come from a flow variable:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Rank #2
- YOUR CONTENT, SUPER SMOOTH: The ultra-clear 6.7" FHD+ Super AMOLED display of Galaxy A17 5G helps bring your content to life, whether you're scrolling through recipes or video chatting with loved ones.¹
- LIVE FAST. CHARGE FASTER: Focus more on the moment and less on your battery percentage with Galaxy A17 5G. Super Fast Charging powers up your battery so you can get back to life sooner.²
- MEMORIES MADE PICTURE PERFECT: Capture every angle in stunning clarity, from wide family photos to close-ups of friends, with the triple-lens camera on Galaxy A17 5G.
- NEED MORE STORAGE? WE HAVE YOU COVERED: With an improved 2TB of expandable storage, Galaxy A17 5G makes it easy to keep cherished photos, videos and important files readily accessible whenever you need them.³
- BUILT TO LAST: With an improved IP54 rating, Galaxy A17 5G is even more durable than before.⁴ It’s built to resist splashes and dust and comes with a stronger yet slimmer Gorilla Glass Victus front and Glass Fiber Reinforced Polymer back.
appId: com.example.app
---
- launchApp
- assertScreenshot:
path: ./screenshots/home.png
thresholdPercentage: ${SCREENSHOT_THRESHOLD}The variable must be set to a value that resolves to a number; an unset variable does not silently revert to the default. Confirm how your environment supplies variables before relying on this pattern. The 95% default is a starting point, not a guarantee that every project should use that tolerance. Calibrate against the visual changes your team considers acceptable: a more permissive threshold may let more differences pass, while a stricter one may fail on smaller differences.
The command documentation establishes the threshold behavior, but does not specify the underlying comparison algorithm, anti-aliasing policy, color handling, or pixel-diff implementation. Avoid assuming those details when interpreting a pass or failure.
Use cropOn when only a region matters
cropOn limits the comparison to an element selected in the UI. This can help when unrelated regions of the screen vary, but the baseline must have been cropped in the same way as the later comparison. Keep the crop convention consistent between reference creation and assertions.
- assertScreenshot:
path: ./screenshots/checkout-total.png
cropOn:
id: checkout_totalThe selector syntax should match the selector supported by your flow and app. Use a full-screen check when surrounding layout is part of what you want to protect; use a crop when the selected element is the intended scope and unrelated screen content would make the comparison noisy. See the command reference for the documented option.
Rank #3
- Charger NOT Included, 6.7" Super AMOLED FHD+, 90Hz Refresh Rate, 385 ppi, 800 nits (HBM), 1080x2340px, 5000mAh Battery
- 128GB, 4GB RAM, microSDXC, Exynos 1330 (5nm), Octa-Core, Mali-G68 MP2 or Mali-G57 MC2 GPU
- Rear Camera: 50MP, f/1.8 (wide) + 5MP, f/2.2 (ultrawide) + 2MP, f/2.4 (macro), LED flash, panorama, HDR; Front Camera: 13MP, f/2.0, Android 14, up to 6 major Android upgrades, One UI 6.1
- 3G: HSDPA 850/900/1700(AWS)/1900/2100; 4G LTE: 1/2/3/4/5/7/12/13/14/20/25/26/28/29/30/38/39/40/41/48/66/71, 5G: 2/5/25/41/66/71/77/78 SA/NSA/Sub6/mmWave - Nano-SIM + eSIM
- US Model – Global Connectivity – Compatible with Most GSM Carriers like T-Mobile, AT&T, MetroPCS, etc. Will Also work with CDMA Carriers Such as Verizon, Straight Talk.
Choose coverage and execution deliberately
Full screen or cropped element
A full-screen assertion preserves the context needed to notice broader layout shifts. A cropped assertion narrows scope to an element and can isolate it from irrelevant changes. Choose based on what the test is meant to guard, and apply the same capture and crop approach to the baseline and subsequent run.
Local iteration or hosted runs
Maestro can be used with local simulator, emulator, or physical-device workflows; a dedicated physical phone is not a requirement. For repeatability, document the intended device and relevant app state rather than assuming different environments will produce interchangeable captures.
Maestro Cloud is an optional managed execution path. Its official documentation describes configurable Android API levels and iOS models, device isolation through virtual devices wiped and recreated between tests, and support for Android, iOS, React Native, Flutter, and Web. It lists 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-documented capabilities and can change; assess current coverage, control, scale, and service terms before choosing hosted execution. See Maestro Cloud.
The Cloud page says asynchronous parallel runs can reduce test execution time “by up to 90%.” That is a vendor claim, not an independently established benchmark or a guaranteed result for a particular suite. Parallel execution may be relevant for larger suites, but teams should weigh setup and service considerations against the value of faster feedback.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #4
- YOUR CONTENT, SUPER SMOOTH: The ultra-clear 6.7" FHD+ Super AMOLED display of Galaxy A17 5G helps bring your content to life, whether you're scrolling through recipes or video chatting with loved ones.¹
- LIVE FAST. CHARGE FASTER: Focus more on the moment and less on your battery percentage with Galaxy A17 5G. Super Fast Charging powers up your battery so you can get back to life sooner.²
- MEMORIES MADE PICTURE PERFECT: Capture every angle in stunning clarity, from wide family photos to close-ups of friends, with the triple-lens camera on Galaxy A17 5G.
- NEED MORE STORAGE? WE HAVE YOU COVERED: With an improved 2TB of expandable storage, Galaxy A17 5G makes it easy to keep cherished photos, videos and important files readily accessible whenever you need them.³
- BUILT TO LAST: With an improved IP54 rating, Galaxy A17 5G is even more durable than before.⁴ It’s built to resist splashes and dust and comes with a stronger yet slimmer Gorilla Glass Victus front and Glass Fiber Reinforced Polymer back.
Keep screenshot checks useful in CI
- Stabilize the state first: assertions are only comparable when the flow reaches the intended screen and the content is sufficiently consistent.
- Keep references reviewable: store and update image artifacts through a process that lets reviewers distinguish deliberate design changes from regressions.
- Use functional assertions too: verify navigation, values, and interactions with checks suited to those behaviors rather than inferring them from pixels.
- Define the target environment: device model or API level, locale, and other configured environment details can affect the screen being tested.
- Interpret failures as a signal to inspect: a mismatch indicates that the image comparison did not meet the threshold; it does not by itself explain whether the cause is an unintended defect or an expected change.
Troubleshoot common assertion failures
Reference image is missing
The command fails if the reference path does not resolve to an available image. Check the path spelling, relative-path base, and that the baseline was committed or otherwise made available to the run. Create the baseline before relying on the assertion.
The assertion fails after a design update
Inspect the current capture against the reference. If the change is intentional, review and update the baseline deliberately; if not, investigate the app state, device configuration, and UI change that caused the mismatch. Raising the threshold without inspection can hide a genuine regression.
A threshold variable is not accepted
Check that the variable is defined in the environment used for this run and resolves to a number. An unset value does not fall back to 95%, according to the command documentation. For a fixed project policy, use an explicit numeric value in the flow.
A cropped check still differs unexpectedly
Verify that the selector identifies the intended element and that the reference was cropped using the same convention. If the element’s content or surrounding state changes, reproduce the intended state before changing the crop or threshold.
Best Value
- Carrier: This phone is locked to Tracfone, which means this device can only be used on the Tracfone wireless network. Tracfone plan required, activating is easy, just 3 steps.
- DISPLAY: Immersive viewing on a 6.7-inch super-bright 120Hz display with powerful stereo speakers and Bass Boost for cinematic entertainment.
- CAMERA SYSTEM: Advanced 50MP Quad Pixel camera captures sharp, detailed photos and videos in any lighting condition
- PERFORMANCE: Lightning-fast 5G connectivity paired with a powerful processor and RAM Boost for smooth multitasking.
- BATTERY LIFE: Long-lasting 5000mAh battery with TurboPower charging technology delivers hours of power in minutes.
The screenshot passes but the feature is still broken
A visual match is not a functional assertion. Add checks for the relevant interaction, state, or business outcome, and use accessibility checks where required. The screenshot should complement those tests, not replace them.
Or skip the browser setup
Maestro is for UI automation flows; if the task is to capture a website image directly, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return an image or PDF. For example, this cURL request saves a WebP screenshot of Stripe; replace the target URL as needed. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses include X-Page-Verdict and X-Billed headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients.
The free plan includes 1,000 screenshots per month with no card required; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently asked questions
Does assertScreenshot replace Maestro’s other assertions?
No. It checks a rendered image against a reference. Use separate assertions for functional state and behavior.
Can I use Maestro for web as well as mobile?
Maestro describes its framework as supporting mobile and web. The specific Cloud targets and execution options are documented by Maestro and may change; consult its current Cloud documentation for hosted coverage.
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.
