Use Playwright Test’s built-in screenshot assertions to capture selected WordPress pages or components, compare later runs with approved baseline images, and review any differences before updating those baselines. The most important reliability rule is to capture the baseline and run comparisons in a consistent browser and operating-system environment with stable test content.
Choose a repeatable WordPress test environment
Visual comparisons are meaningful only when the page and the environment producing its pixels are controlled. Use a local, staging, or temporary WordPress instance with a known theme, plugin set, content fixtures, and user state. Staging is useful when the production-like theme and plugins matter, but keep test content predictable and avoid relying on live editorial changes.
WordPress Playground CLI is another option for running end-to-end tests without Docker, a database, or manual setup, as described in the WordPress Developer Resources handbook. It does not automatically reproduce every production configuration; verify that its WordPress, theme, plugin, and fixture setup matches what you intend to test.
If your project already uses WordPress’s Playwright end-to-end tooling, integrate visual assertions into that suite rather than creating an unrelated runner. The WordPress Developer Blog’s May 4, 2026 example uses @playwright/test and @wordpress/e2e-test-utils-playwright; treat its package versions as examples from that article and check current compatibility before copying them.
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 & 11#1 Best Overall
Pick pages and states that matter
Start with a small route set that represents the layouts and interactions most likely to break. For example:
- The home page.
- A representative post and a category or archive page.
- A key landing page or custom template.
- A logged-in editor, checkout, or other critical flow if it is part of the site’s user experience.
Capture desktop and mobile viewports as separately named snapshots when both matter. Full-page captures are useful for overall layout changes; locator screenshots are often better for a component whose appearance can be tested without unrelated page content. A screenshot assertion checks appearance, not behavior or accessibility, so retain functional assertions and accessibility checks for those concerns.
Add Playwright screenshot assertions
Install Playwright Test in the project if it is not already present, then add a test such as this to a test file. Replace the URL or environment variable with the base URL for your test WordPress instance.
import { test, expect } from '@playwright/test';
test('homepage visual baseline', async ({ page }) => {
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.WP_BASE_URL ?? 'http://localhost:8888');
await expect(page).toHaveScreenshot('homepage-desktop.png', {
fullPage: true,
});
});The example assumes the site is available at the given local URL unless WP_BASE_URL is set. Configure the test runner’s web server, authentication, WordPress fixtures, and project settings to suit your site; those details vary by project. The example is a starting pattern, not a claim that a particular WordPress configuration has been executed.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Capture a component instead of the whole page
When the page contains unrelated content that makes a full-page image noisy, assert against a locator:
test('header visual baseline', async ({ page }) => {
await page.goto(process.env.WP_BASE_URL ?? 'http://localhost:8888');
const header = page.locator('header.site-header');
await expect(header).toHaveScreenshot('site-header.png');
});Use a selector that uniquely identifies the intended region. If the selector matches nothing or more than one element, fix the locator rather than masking or weakening the assertion.
Create and update baselines deliberately
On the initial run, Playwright creates reference screenshots for assertions that do not yet have baselines. Review the images, then commit approved snapshots with the tests. Later runs compare the new output with those committed references.
- Run the relevant test to generate the initial snapshot.
- Open and inspect the generated image to confirm it represents the intended page and state.
- Commit the test and approved reference image together.
- When a UI change is intentional, run
npx playwright test --update-snapshots, inspect the changed snapshots, and commit only the approved updates.
Do not routinely update snapshots just to clear a failing test. A changed reference image accepts the new appearance; it does not establish that the change was correct. WordPress’s own testing guidance likewise recommends updating snapshots for intended changes.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Make screenshot comparisons less flaky
Rendering can differ across operating systems, browser versions, settings, hardware, power state, and headless mode, as Playwright explains in its visual comparison documentation. Keep the environment that creates baselines as close as possible to the one that checks them.
Stabilize the rendering inputs
- Use a consistent operating-system and browser image in CI, and keep browser versions aligned with the baseline workflow.
- Set the same viewport and device scale factor for baseline creation and comparison. Give desktop and mobile captures distinct names.
- Use fixed fixtures and predictable user state. Avoid changing posts, rotating promotions, or live data during a visual test.
- Wait for meaningful application readiness, such as a known page element or loaded content, instead of adding a long arbitrary sleep.
- Ensure fonts and relevant images have loaded before capturing if their late arrival changes layout.
Handle animation and unavoidable dynamic content
Playwright’s screenshot assertion waits for two consecutive screenshots to match before comparing. Its screenshot assertion animation handling is configured and defaults to disabled; consult the PageAssertions API when you need to change animation behavior.
For genuinely volatile material—such as third-party ads, rotating promotions, or timestamps—prefer to make the test data deterministic or exclude only the specific unstable region. Playwright supports a stylePath stylesheet for filtering content during screenshots. A narrowly scoped style might hide a known rotating widget:
/* tests/visual.css */
.rotating-promotion {
visibility: hidden !important;
}Then pass the stylesheet to the screenshot assertion:
await expect(page).toHaveScreenshot('homepage-desktop.png', {
fullPage: true,
stylePath: 'tests/visual.css',
});Confirm that your installed Playwright version supports the option as used in your project. Do not hide the component under test or broad parts of the page: filtering should remove unavoidable noise, not make real regressions invisible.
Choose full-page or focused coverage
A full-page screenshot gives broad layout coverage but also includes more unrelated and potentially changing content. A locator screenshot focuses the signal and can make failures easier to interpret. Use the smallest capture that still covers the behavior or visual contract you need to protect.
Review failures and decide whether a change is real
When a test fails, compare the expected, actual, and diff images before changing a baseline. Determine whether the difference comes from a real UI change, an unstable fixture, a missing readiness condition, or a rendering-environment change.
Playwright’s UI mode and Inspector help reproduce and inspect test runs. Trace Viewer provides an action timeline and can show expected, actual, and diff images; see the Trace Viewer documentation. In CI, retain failure screenshots and traces so a reviewer can inspect the failed state. Approve a baseline update only after deciding that the visual change is intended.
Troubleshoot common problems
| Symptom | Likely cause | What to do |
|---|---|---|
| Every screenshot changes in CI, even when the page looks unchanged. | The baseline and CI run use different operating systems, browser versions, rendering settings, or viewport/device scale factor. | Align the capture and comparison environment, then regenerate baselines only if the new environment is the one the project intends to standardize on. |
| Only ads, timestamps, or promotional areas fail. | Uncontrolled third-party or time-varying content is present in the capture. | Use stable fixtures or narrowly filter the unavoidable region with a screenshot stylesheet. Keep the page under test visible. |
| The image captures an incomplete layout or missing assets. | The page was captured before the relevant content, font, or image loaded. | Wait for a meaningful readiness signal and ensure the needed assets have loaded before asserting the screenshot. |
| A locator screenshot fails because the target cannot be found. | The selector is wrong for this theme, the page state differs, or the element has not appeared yet. | Verify the page and state, use a unique locator, and wait for the relevant element rather than broadening the capture. |
| Snapshot updates remove a useful regression warning. | The update command was run to silence a failure without reviewing the diff. | Restore the prior reference if needed, inspect expected/actual/diff, and update only when the changed appearance is approved. |
When built-in snapshots are enough—and when to consider hosted review
For a modest site and a team comfortable reviewing image diffs in its repository and CI workflow, Playwright’s local snapshots may be sufficient. A hosted service can be worth evaluating when the team needs hosted visual review, broader browser or platform coverage, or a review flow integrated with changes on each commit.
Percy by BrowserStack documents Playwright integration, including a way to pass existing toHaveScreenshot assertions through the service. It is a separate hosted service requiring setup and project credentials; its Playwright integration documentation and integration options describe the available workflow choices. Evaluate browser coverage, review process, CI fit, and total cost for your project; a price comparison is not established here.
Or skip the browser setup
If you need a screenshot as an output rather than a Playwright visual-regression assertion, ScreenshotNeo provides 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 the target URL; create an API key and replace the placeholder. See the ScreenshotNeo API documentation for request options.
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 or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses include X-Page-Verdict and X-Billed headers. Its MCP server gives AI agents tools named take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can a screenshot assertion prove that a WordPress page works correctly?
No. It detects visual differences; use separate functional and accessibility checks for behavior and accessibility.
Should I update snapshots whenever CI reports a visual difference?
No. Inspect the images and update references only after approving the visual change.
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.
Recommended Free Tools
