Friday evening, you merge a header redesign. Monday morning, a colleague tells you the login button has slipped a few pixels on the pricing page: a page you did not even touch. No test sounded the alarm, because no test was looking at appearance. That is exactly the gap visual testing fills.
Microsoft's Playwright has included a native visual testing feature since version 1.22: the toHaveScreenshot() method. It captures screenshots and compares them automatically with reference images, with no external plugin. It is an entirely free solution: for other free visual testing tools, see our comparison.
It is one of the strongest options for teams that want to add visual tests to their existing suite. To understand the basics of visual regression, see our complete guide. This guide covers installation, configuration, best practices, and CI/CD integration, then what Delta-QA's Vision SDK changes in those same tests.
The essentials on one page: what a no-code tool really automates and how it compares: No-code test automation.
Does toHaveScreenshot() still force you to write and maintain code? Delta-QA captures and compares your pages without writing a single line of code, no credit card. Try Delta-QA for free →
Installation and First Test
Setup is quick if you already have a Node.js project:
npm install -D @playwright/test
npx playwright install
Then create your first visual test in tests/visual.spec.ts:
import { test, expect } from '@playwright/test';
test('homepage visual test', async ({ page }) => {
await page.goto('https://your-site.com');
await expect(page).toHaveScreenshot('homepage.png');
});
The first run generates the baseline (the reference image). Later runs compare the current capture with that baseline and report the differences.
# First time: generate the baselines
npx playwright test --update-snapshots
# Then: compare
npx playwright test
It really is that simple to get started. The complexity comes with real-world cases.
Configuring Tolerance
By default, Playwright reports the slightest one-pixel difference. In practice, you need to configure tolerance thresholds to avoid false positives.
In playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
maxDiffPixelRatio: 0.01, // 1% of different pixels tolerated
animations: 'disabled', // disables CSS animations
scale: 'device', // accounts for Retina screens
},
},
});
You can also adjust it test by test:
// Static page: strict threshold
await expect(page).toHaveScreenshot('landing.png', {
maxDiffPixelRatio: 0.001
});
// Dashboard with charts: looser threshold
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixelRatio: 0.05,
mask: [page.locator('.chart')]
});
The threshold is a trade-off: too low, and the slightest rendering variation fails the test; too high, and a margin going from 16px to 12px slips under the bar unseen.
Handling Dynamic Content
Dynamic content (dates, ads, avatars, counters) is the nightmare of visual tests. Playwright offers three solutions:
Mask the dynamic areas, the most common method:
await expect(page).toHaveScreenshot({
mask: [
page.locator('.ad-banner'),
page.locator('.timestamp'),
page.locator('.user-avatar')
]
});
Replace the content to freeze the values:
await page.evaluate(() => {
document.querySelector('.date').textContent = '01/01/2026';
});
await expect(page).toHaveScreenshot();
Hide with CSS the elements that must not appear at all:
await page.addStyleTag({
content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();
Each of these solutions is maintained by hand: a new dynamic block on the page means one more selector to add.
Stabilizing Tests
A visual test that passes one day and fails the next for no reason is unusable. Here is how to guarantee stability:
test('stable visual test', async ({ page }) => {
await page.goto('https://your-site.com');
// Wait for the network to be quiet
await page.waitForLoadState('networkidle');
// Wait for fonts to load
await page.evaluate(() => document.fonts.ready);
// Wait for a critical element
await page.waitForSelector('.hero-image', { state: 'visible' });
await expect(page).toHaveScreenshot();
});
And to disable animations by hand when the global option is not enough:
await page.addStyleTag({
content: `
*, *::before, *::after {
animation-duration: 0s !important;
transition-duration: 0s !important;
}
`
});
Testing Multiple Resolutions
Playwright makes multi-resolution testing easy through projects:
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'Desktop',
use: { viewport: { width: 1920, height: 1080 } },
},
{
name: 'Tablet',
use: { viewport: { width: 768, height: 1024 } },
},
{
name: 'Mobile',
use: { ...devices['iPhone 13'] },
},
],
});
Each project generates its own baselines. A test therefore runs three times, in three resolutions, with three sets of captures to keep up to date.
CI/CD Integration
Integration into GitHub Actions is straightforward. For a complete setup, see our guide to regression testing in GitHub Actions or, on the GitLab side, the one on visual testing in GitLab CI.
name: Visual Tests
on: [push, pull_request]
jobs:
visual-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- uses: actions/upload-artifact@v4
if: failure()
with:
name: playwright-report
path: playwright-report/
When a test fails, Playwright produces three images: the baseline (expected), the current capture, and a diff with the differences in red. The HTML report (npx playwright show-report) displays them side by side.
One thing to watch: font rendering varies from one system to another. Baselines generated on a Mac will not match captures taken on the CI's Linux runner. Generate them in the CI, or in Playwright's official Docker image.
Does toHaveScreenshot() still ask you to write code? Delta-QA captures and compares your pages with no-code, no credit card. Try Delta-QA for free →
The Limits of the Playwright Approach
Playwright is excellent for teams that write their tests, but toHaveScreenshot() has limits you need to know:
Required skills: you need to master TypeScript/JavaScript, selectors, and project configuration. QAs who do not write code can neither create nor maintain these tests.
No review interface: there is no shared space to judge differences. Baseline management happens through the terminal and the file system. In a team, it quickly gets complex.
A pixel comparison: the diff shows a red zone, not what changed. Anti-aliasing differences between browsers, font rendering variations between operating systems: all of this generates noise that you have to manage by hand with masks and thresholds.
Maintenance: every intended interface change forces you to regenerate the baselines (--update-snapshots). On a project with 200 visual tests and 3 browsers, that makes 600 baselines to manage, versioned in the repository. Our guide on baseline management details strategies to maintain them.
Keep Playwright, Change the Comparison: The Vision SDK
If your Playwright tests already exist, you do not have to leave them to remove some of these limits. Delta-QA's Vision SDK (@delta-qa/vision) adds a Delta-QA check where the test needs to look at the page:
import { test } from "@delta-qa/vision/fixture";
test("Checkout", async ({ page, vision }) => {
const checkout = await vision.open(page, { id: "checkout", name: "Checkout" });
await page.goto("https://shop.example.com/checkout");
await checkout.check("Payment");
}); // closed by the fixture: an unreviewed difference fails the test
The SDK reads the API key from the DELTAQA_API_KEY variable. Without the fixture, open(page, { … }) from @delta-qa/vision opens the same test, and close() closes it in an afterEach.
What changes compared with toHaveScreenshot():
- The report names the element that changed. Not a red zone to interpret: the report says which element changed, for example the "Pay" button, which went from blue to green.
- References no longer live in the repository. On the first run, each check becomes the reference. After that, an unreviewed difference fails the test, and the CI log gives the link to the report. There you judge each difference: "Intended" or "Bug".
- One reference per branch. The test gives its branch and its base branch (
branch,baseBranch): a new branch is compared with its base branch from its first run, and "Intended" applies only to the branches you tick. - The rest of the test does not change. The projects in
playwright.config.tskeep applying: each screen size has its own reference. One condition: a screen density of 1 (deviceScaleFactor: 1).
The SDK covers Playwright in TypeScript and JavaScript, on Chromium. It is first offered in early access: access is requested from its page.
And for Those Who Do Not Write Tests
Playwright tests remain code. For QAs, product owners, or designers to verify the application's appearance too, no-code solutions like Delta-QA offer another path: you record a journey in the browser, Delta-QA replays it on every version and compares each step with its reference. These scenarios and the Vision SDK checks are judged in the same Delta-QA space, with the same report.
Want to test without a line of TypeScript or a single baseline to regenerate? Compare your pages with Delta-QA right now, free and with no credit card. Try Delta-QA for free →
FAQ
Is Playwright free for visual testing?
Yes, entirely. toHaveScreenshot() is built natively into Playwright, which is open source and maintained by Microsoft. No license, no screenshot limit.
How long does it take to set up Playwright visual tests?
If you already master Playwright, allow a few hours to configure and write your first tests. If you start from scratch (installation, learning TypeScript, CI configuration), allow 2 to 3 days.
Playwright or Cypress for visual testing?
Playwright has the advantage of building visual testing in natively (toHaveScreenshot()), while Cypress requires an external plugin. Playwright also supports three browser engines (Chromium, Firefox, WebKit), whereas Cypress supports Chromium-based browsers and Firefox, with WebKit remaining experimental. For the details, see our Playwright vs Cypress comparison, or Playwright vs Selenium if you are torn between those two frameworks.
Can you use Playwright and Delta-QA together?
Yes, and in the same test. With the Vision SDK, you add vision.check() at the steps where the page must be verified: Playwright drives the browser and your functional assertions, Delta-QA compares the page with its reference. Journeys recorded without code by the QA team are judged in the same space.
Do I need to remove my toHaveScreenshot() calls to use the Vision SDK?
No. The two can coexist in the same suite: you can add vision.check() on a few pages, compare the results, then decide page by page what you keep.
Playwright offers a solid foundation for automated visual tests. For teams that write their tests in TypeScript, toHaveScreenshot() is probably the best open source option available in 2026, provided you tune the thresholds well and stabilize the tests from the start. When the pixel diff and the repository baselines become the main burden, the Vision SDK keeps your tests and changes the comparison. To place Playwright against the other tools, see our comparison of regression testing tools.
