Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC 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 & 11Vitest visual regression testing captures a rendered page or element in Browser Mode and compares it with an approved reference image using toMatchScreenshot(). It is useful for catching unintended appearance changes, but it does not verify that controls work or explain why a page looks the way it does. Use it alongside behavioral assertions.
What Vitest visual testing checks
Vitest introduced built-in screenshot comparison in Vitest 4. The matcher captures what is rendered in a browser context and checks it against a stored screenshot. This makes it a regression check for appearance: a changed layout, color, font, or other visible detail can produce a comparison failure.
The screenshot does not tell you whether a button submits correctly, whether a menu opens, or what caused a visual difference. The Vitest visual regression guide explicitly cautions that toMatchScreenshot is not a substitute for proper assertions. Test behavior separately.
Set up Browser Mode and choose a provider
Browser Mode requires a provider. Vitest’s Browser Mode guide names Preview, Playwright, and WebdriverIO. The guide presents Preview as a way to try the experience and says CI requires Playwright or WebdriverIO; it recommends Playwright if you do not already use a provider. Follow the setup instructions for the Vitest version installed in your project.
- From the project root, run
vitest init browserand follow the initializer prompts, or install and configure a provider manually using the official Browser Mode guide. - Choose a provider appropriate to your use: Preview for trying the feature, or Playwright or WebdriverIO for CI.
- Configure the provider and Browser Mode project, then run the project using your normal Vitest command. For CI, use a supported automation provider and keep its browser environment consistent with the one used to create references.
Configuration details can vary by Vitest version and provider, so use the documentation matching your installed version rather than copying configuration for a different release.
How do I use toMatchScreenshot?
Render the UI into the test’s browser context before taking a screenshot. Import expect and page from vitest/browser, then call the matcher on the page or a selected element. For example:
import { expect, page } from 'vitest/browser'
// Render or navigate to the UI under test before this assertion.
await expect(page.getByRole('button', { name: 'Continue' }))
.toMatchScreenshot('primary-button')The example checks an element rather than the entire page. The matcher accepts a name and options; consult the current visual regression documentation for supported options and configuration in your installed version. Vitest’s snapshot guide covers file snapshots; screenshot comparison is a visual assertion, not a text snapshot.
Create and maintain screenshot references
The first run creates a reference image and fails with a prompt to review it. That failure is part of baseline setup, not evidence that the test is broken. Treat approval as a human review: inspect the image and accept it only if it represents the intended design. Keep approved references with the test suite so later runs can compare against them.
Recommended Free Tools
- Run the visual test for the first time. Vitest writes a reference and reports that it needs review.
- Open the reference image and check that the page or element is fully rendered, correctly sized, and visually intended.
- Keep the approved reference alongside the project’s tests and commit it so teammates and CI use the same expected appearance.
- On later runs, inspect the reference, actual capture, and diff when a comparison fails. Decide whether the difference is a regression or an intended UI change.
- For an intentional change, update the reference only after reviewing the new rendering. The guide shows the update command
vitest --project vrt --update; use the project name and command appropriate to your configuration.
Visual changes are often expected during UI work. Keeping visual tests in a distinct project or otherwise separable from behavior suites can make it easier to interpret failures and update references deliberately.
Make captures stable and useful
Vitest retries captures to determine stability: it captures repeatedly until two consecutive screenshots match or the timeout is reached, then compares the stable capture with the reference. This helps with transient loading and rendering variation, but it cannot make continuously changing content deterministic.
Rank #4
- Standardize the rendering environment. Use the same browser and version, operating system, fonts, viewport, graphics conditions, headless mode, and display settings for reference generation and comparison. Apparently similar environments can still render differently.
- Wait for the page to settle. Ensure images, fonts, and layout have finished loading before capture. Content that arrives late can shift the screenshot.
- Disable or control animation. An endless animation can prevent two captures from matching. Turn off animations or otherwise make the tested content settle.
- Choose page or element scope intentionally. A page-level capture covers broad layout changes; an element-level capture narrows the check to a component. The element must exist and be rendered in the browser context.
- Set comparison tolerance carefully. A tighter threshold can flag small rendering differences; a looser threshold tolerates more variation but can miss genuine changes. No threshold removes every false positive or guarantees that important changes will be caught.
Diff images are diagnostic evidence, not an automatic verdict. Vitest can provide the reference, actual capture, and a diff when dimensions permit. Its guide describes red changed pixels and yellow anti-alias differences when anti-aliasing is not ignored. If image dimensions differ, a diff may not be available; inspect the captures themselves.
Why is my Vitest screenshot test flaky?
- The capture never becomes stable: ongoing animation or changing content can prevent consecutive captures from matching. Disable animation or freeze the relevant content.
- The screenshot differs only in CI: check browser version, OS, fonts, viewport, headless mode, display settings, and graphics conditions. Standardize the environment used for baselines and CI comparisons.
- Images, fonts, or layout are inconsistent: capture may be happening before resources finish loading or layout settles. Ensure the test reaches a predictable rendered state before the assertion.
- The first run fails: inspect and approve the generated reference if it shows the intended design; the initial reference-creation run is expected to request review.
- A diff is missing: the guide says diffs are available when screenshot dimensions match. Compare the actual and reference images directly when their dimensions differ.
- A changed screenshot may be mistaken for a broken control: screenshot matching reports appearance changes, not interaction correctness. Add behavior assertions for the control’s expected action.
Or skip the browser setup
For a standalone screenshot rather than an in-test regression assertion, ScreenshotNeo offers a one-request screenshot API. It is not a replacement for Vitest assertions or a committed visual baseline.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
Install an HTTP client if needed, set your API key, and run this Python example to save a screenshot:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)See the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Does Vitest visual regression testing work with Vitest 3?
The built-in screenshot comparison capability was introduced in Vitest 4; use the documentation for your installed version.
Can a screenshot test prove that a button works?
No. It checks rendered appearance; use a behavioral assertion to verify the button’s action.
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.
