A practical introduction to Playwright for testing real user flows, browser behavior, authentication, debugging, CI, and screenshot workflows.
If your screenshot API keeps returning a 'Checking your browser' page instead of the site, the target is behind bot protection. Here's how to capture it with stealth mode.
TutorialSet up an automated check that screenshots a competitor's pricing page on a schedule and emails you only when it actually changes. Point-and-click setup, about five minutes.
Developers, marketers, and founders use Allscreenshots to automate website captures. No credit card required to get started.
Visual regression testing is the safety net for changes your unit tests cannot see. A route can pass every assertion and still ship with a broken hero, an invisible button, a clipped checkout form, or a mobile layout that only fails at one breakpoint.
The practical version is simple: capture screenshots for important pages, compare them against approved baselines, and review the differences before a release goes live. The hard part is making those screenshots stable enough that developers trust the signal.
This guide shows how to design that workflow with screenshot APIs, CI previews, and reviewable baselines.
Visual tests are not a replacement for functional tests. They are a different layer.
Use them to catch:
Skip them for flows where the expected output changes on every run unless you can control the data. A stock ticker, live feed, random testimonial carousel, or personalized dashboard will produce noise until you freeze or hide dynamic regions.
The fastest way to fail with visual regression testing is to screenshot everything on day one. Start with pages that are expensive to check manually and damaging when they break.
| Page type | Why it belongs in the first pass |
|---|---|
| Homepage | High traffic, broad brand impact |
| Pricing | Revenue-critical and often edited |
| Signup or login | First-product impression |
| Checkout or upgrade | Direct conversion impact |
| Docs landing page | Navigation and trust signals |
| Core app dashboard | Dense UI with many layout states |
For each page, choose a small viewport set:
| Viewport | Size | Purpose |
|---|---|---|
| Mobile | 390 x 844 | Modern phone layout |
| Tablet | 768 x 1024 | Navigation and two-column transitions |
| Desktop | 1440 x 900 | Primary working viewport |
| Wide | 1920 x 1080 | Large-monitor layout issues |
You can expand later. A focused suite that runs on every pull request is more useful than a massive suite nobody wants to maintain.
Good visual regression testing starts before the screenshot comparison. If the capture is inconsistent, the diff will be inconsistent too.
Use predictable data in preview environments. Seed test accounts, lock feature flags, and avoid production APIs where content changes independently of the code being reviewed.
Animations and videos create false positives. Add a test stylesheet or query parameter that disables transitions:
*, *::before, *::after {
animation-duration: 0s !important;
animation-delay: 0s !important;
transition-duration: 0s !important;
scroll-behavior: auto !important;
}Timestamps, user avatars, ads, live chat widgets, and A/B test slots should not decide whether a pull request passes.
{
"url": "https://preview.example.com/pr-214",
"fullPage": true,
"hideSelectors": [
"[data-testid='current-time']",
".intercom-lightweight-app",
".ab-test-banner"
],
"waitForSelector": "main"
}Prefer hiding a small volatile element over increasing the diff threshold for the whole image. Broad thresholds can hide real regressions.
You can run Playwright or Puppeteer yourself, but CI browser infrastructure becomes another system to maintain. A screenshot API keeps the test runner focused on orchestration while the rendering service handles browser setup, full-page scrolling, ad blocking, and device settings.
Here is a minimal Node.js capture script:
const fs = require('node:fs/promises');
const pages = [
{ name: 'home', url: process.env.PREVIEW_URL },
{ name: 'pricing', url: `${process.env.PREVIEW_URL}/pricing` },
{ name: 'signup', url: `${process.env.PREVIEW_URL}/signup` }
];
const viewports = [
{ name: 'mobile', width: 390, height: 844 },
{ name: 'desktop', width: 1440, height: 900 }
];
async function capture(page, viewport) {
const response = await fetch('https://api.allscreenshots.com/v1/screenshot', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SCREENSHOT_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: page.url,
fullPage: true,
viewport: {
width: viewport.width,
height: viewport.height
},
format: 'png',
waitForSelector: 'main'
})
});
if (!response.ok) {
throw new Error(`Capture failed for ${page.name}: ${response.status}`);
}
const buffer = Buffer.from(await response.arrayBuffer());
await fs.mkdir('screenshots/current', { recursive: true });
await fs.writeFile(`screenshots/current/${page.name}-${viewport.name}.png`, buffer);
}
async function main() {
for (const page of pages) {
for (const viewport of viewports) {
await capture(page, viewport);
}
}
}
main().catch((error) => {
console.error(error);
process.exit(1);
});For larger suites, use asynchronous screenshot jobs or bulk workflows so CI does not hold open one HTTP request per page.
Once screenshots are captured, compare them with a deterministic image diff library. Teams often use Pixelmatch, Resemble.js, Looks Same, or a hosted visual review service.
The directory layout can stay simple:
screenshots/
baselines/
home-mobile.png
home-desktop.png
pricing-mobile.png
pricing-desktop.png
current/
home-mobile.png
home-desktop.png
diffs/
home-mobile.pngYour comparison step should produce three outputs:
Avoid making developers download a giant artifact just to learn which page moved.
A pull request workflow usually has four stages:
name: Visual regression
on:
pull_request:
jobs:
visual:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
- name: Capture screenshots
env:
SCREENSHOT_API_KEY: ${{ secrets.SCREENSHOT_API_KEY }}
PREVIEW_URL: ${{ secrets.PREVIEW_URL }}
run: node scripts/capture-visuals.js
- name: Compare screenshots
run: node scripts/compare-visuals.js
- uses: actions/upload-artifact@v4
if: failure()
with:
name: visual-regression-results
path: screenshots/If you already run browser tests with Playwright, keep those tests focused on behavior and use screenshots for the visual layer. The combination is stronger than either tool alone.
Baseline updates need a review process. If anyone can overwrite the approved images automatically, the test loses value.
Use one of these patterns:
| Pattern | Best for | Tradeoff |
|---|---|---|
| Manual baseline PR | Small teams and critical pages | Slower, but very clear |
| Main-branch refresh | Fast-moving product UI | Requires discipline in PR review |
| Release baseline | Marketing sites and docs | Fewer updates, larger diffs |
A good rule: a baseline update should be reviewed by someone who understands the intended UI change, not just the person who changed the code.
Most visual testing failures come from environmental noise, not actual bugs. Tighten the capture before you loosen the comparison.
AllScreenshots full-page capture is useful when the whole page matters, while default ad and cookie blocking keeps review artifacts cleaner by default.
Visual regression testing is part of CI, so monitor it like CI:
| Metric | What it tells you |
|---|---|
| Failure rate | Whether the suite is noisy |
| Average capture time | Whether the matrix is getting too large |
| Baseline churn | Whether pages are too unstable |
| Reviewed diffs | Whether failures lead to useful decisions |
| Ignored failures | Whether the signal is losing trust |
If developers routinely rerun the job until it passes, fix the capture setup before adding more pages.
AllScreenshots visual regression testing gives teams the screenshot capture layer without managing headless browsers in CI. It is especially useful when you need:
For broader automation patterns, see screenshot automation, CI/CD workflows, and screenshot API performance tips.
Automated visual regression testing works best when it is narrow, stable, and tied to real review decisions. Start with a handful of critical pages, capture them consistently, compare against approved baselines, and make visual diffs easy to inspect in pull requests.
The goal is not to block every pixel change. The goal is to catch the visual changes nobody intended to ship.