In a Vite project, use Playwright Test’s await expect(page).toHaveScreenshot('home.png') to compare the rendered page with a visual baseline. To save an image without testing it against a baseline, use page.screenshot({ path: 'screenshots/home.png' }). They solve different problems: one detects visual changes; the other creates an image file.
Choose between saving an image and testing for visual changes
| Goal | Playwright API | What it does |
|---|---|---|
| Save a screenshot for inspection or another workflow | page.screenshot({ path: 'screenshots/home.png' }) |
Writes an image file. It does not compare the image with an expected result. |
| Catch unintended visual changes in a test | await expect(page).toHaveScreenshot('home.png') |
Creates a baseline on the first run, then compares later captures with it and reports differences. |
See Playwright’s Page API for image capture and its visual comparisons guide for screenshot assertions.
As an Amazon Associate I earn from qualifying purchases.
Set up Playwright to start the Vite app
This example assumes @playwright/test is installed, the Vite package script is named dev, and the app can use port 5173. Change the command, host, and port if your project uses different values.
In the project root, add or update playwright.config.ts:
#1 Best Overall
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
baseURL: 'http://127.0.0.1:5173',
},
webServer: {
command: 'npm run dev -- --host 127.0.0.1 --port 5173',
url: 'http://127.0.0.1:5173',
reuseExistingServer: !process.env.CI,
},
});Playwright’s webServer setting starts the local server for a test run and uses its configured URL to determine when the server is ready. baseURL lets tests navigate with relative paths such as /. See the Playwright web server guide. Vite projects created with its standard setup commonly have dev, build, and preview scripts; check your own package.json before using the example command. See Vite’s Getting Started guide.
Write a visual screenshot test
Create tests/home.spec.ts:
import { test, expect } from '@playwright/test';
test('homepage screenshot matches', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('home.png');
});Run the test with:
npx playwright testOn the first run, Playwright reports that the expected screenshot is missing and writes a screenshot as the initial baseline. Inspect it and add the generated snapshot directory to version control. Later runs compare the page with that checked-in expectation. When the design change is intentional, run npx playwright test --update-snapshots, inspect the changed screenshots and diffs, then commit only the approved baselines. Updating snapshots without reviewing them can turn a regression into the new expectation. The visual comparisons guide explains the workflow.
Save a screenshot file without a visual assertion
Use page.screenshot() when you need an image artifact rather than a regression check. For example, add this to a Playwright test:
Free tools Windows power users keep installed
One-click scans. No signup required.
import { test } from '@playwright/test';
test('save homepage image', async ({ page }) => {
await page.goto('/');
await page.screenshot({ path: 'screenshots/home.png', fullPage: true });
});The path option saves the image, and fullPage: true captures the full scrollable page. Omit it for a viewport-sized capture. This code produces an image but does not establish or compare a visual baseline; use toHaveScreenshot() for that.
Run the test against development or built output
Use the Vite development server
The earlier configuration starts Vite with npm run dev. Choose this when the test is meant to check the app during development.
Use Vite preview for a production-build check
To test built assets instead, build first and serve the output with Vite’s preview server. Vite documents npm run build followed by npm run preview; the documented default preview port is 4173, although a project can configure another port. See Vite’s static deployment guide.
For example, configure Playwright to build and then start preview:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
baseURL: 'http://127.0.0.1:4173',
},
webServer: {
command: 'npm run build && npm run preview -- --host 127.0.0.1 --port 4173',
url: 'http://127.0.0.1:4173',
reuseExistingServer: !process.env.CI,
},
});Keep the preview URL consistent between baseURL and webServer.url. If your project changes the preview port or command, update both values. Playwright’s web server guide describes configuring the server for tests.
Make screenshot comparisons dependable
Keep the rendering environment consistent
Baseline images can vary with the host operating system, browser version, browser settings, hardware, power source, and headless mode. Generate and compare screenshots in the same environment when possible. If your Playwright configuration runs multiple browser projects, expect browser-specific screenshots and review the baseline for each. Playwright discusses these factors in its visual comparisons guide and browser documentation.
Rank #4
Wait for stable content and control genuine variability
Playwright’s PageAssertions documentation says: “This function will wait until two consecutive page screenshots yield the same result, and then compare the last screenshot with the expectation.” See the PageAssertions API. Screenshot assertions also support stylePath for a stylesheet that hides changing regions; use it only to remove known nondeterminism, not to mask real regressions. Animation handling is disabled by default for screenshot assertions.
Pair visual checks with behavior checks
A screenshot can catch an unexpected visual difference, but it does not prove that a user action, route, or interaction works correctly. Add ordinary assertions for the behavior that matters, such as the expected URL, text, or element visibility, alongside the screenshot assertion.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Troubleshoot common failures
toHaveScreenshotis undefined or unavailable: Import bothtestandexpectfrom@playwright/test, and run the test with the Playwright Test runner. Screenshot assertions are a Playwright Test feature.- The test cannot reach the Vite app: Confirm the server command starts successfully, the port and host match the configured URL, and the Vite script name is correct. When forwarding Vite flags through an npm script, use
--before the flags, as innpm run dev -- --host 127.0.0.1 --port 5173. - The test starts but checks the wrong version of the app: Use the development server for the dev app. For built output, run a build and serve it with preview, then point Playwright at the preview address.
- A screenshot assertion fails after a change: Inspect the actual image and diff. If the change is intended, update snapshots with
npx playwright test --update-snapshotsand review the resulting baseline changes before committing. - Images differ across machines or CI: Compare in a consistent operating system and browser environment where possible. Environment-related rendering differences are not automatically application defects.
- A screenshot passes while a feature is broken: Add assertions for the relevant text, URL, or visibility and test the interaction itself; an image alone is not a complete functional test.
Or skip the browser setup
If you need a screenshot of a publicly reachable page rather than a visual regression test of your local Vite app, ScreenshotNeo can return an image or PDF with one GET request. It removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. See the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpReplace the example URL with the public page you want to capture. This does not replace Playwright’s baseline comparisons for a local Vite app. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does the first Playwright screenshot test pass automatically?
No. The first run creates a baseline image and reports that the expected screenshot was missing; review the image before checking it in.
Can I use ScreenshotNeo to compare screenshots of my local Vite app?
The one-call example captures a publicly reachable URL. The local-app visual regression workflow in this guide uses Playwright Test baselines.
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 minuteQuick 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.
