Visual regression testing for WordPress: catch broken pages before your clients do

Most WordPress problems after an update are not white screens of death. They are smaller than that: a button that moved below the fold, a menu that no longer opens on mobile, a product grid that suddenly shows one column instead of three. The site still loads, so uptime monitoring says everything is fine. But the page is broken for the people who use it.

Visual regression testing is designed to catch exactly these problems.

What is visual regression testing?

Visual regression testing means taking screenshots of a page before a change and after a change, and comparing them pixel by pixel. If the difference is larger than you expect, something probably changed that should not have.

For WordPress sites, the change is usually an update: a plugin, a theme or WordPress core.

What it catches

• Layout changes caused by a page builder or theme update
• Missing or broken images and icons
• Menus, sliders or forms that no longer render
• Error notices printed on the page
• Differences that only appear on mobile

What it does not replace is testing actual behaviour, such as whether a form really sends an email. It is a fast, reliable way to see whether pages still look the way they should.

Desktop and mobile

Always compare both. Many themes and page builders use different layouts for small screens, and an update can break one without affecting the other. A page that looks perfect on a laptop can be unusable on a phone.

Which pages to check

You do not need to screenshot every page of every site. Focus on the pages that matter:

• the homepage
• the pages in the main menu
• shop, product and checkout pages for WooCommerce sites
• the login page
• a handful of extra pages that are important to this specific client

Setting a threshold

Some differences are normal. Dates change, sliders rotate, and a cookie banner can appear on one screenshot and not the other. That is why visual comparisons use a threshold: a percentage of the page that is allowed to change before the result counts as a problem.

A threshold of around 2% works well for most sites. For pages with a lot of moving content, it helps to mask the parts that always change, such as a news ticker or a live chat widget, so they do not trigger false alarms.

Where it fits in your update routine

Visual regression testing is most useful when you combine it with a staging copy:

1. Take screenshots of the key pages.
2. Run the updates on a copy of the site.
3. Take the same screenshots on the copy and compare.
4. Only update the live site when the differences stay under the threshold.

This way a broken layout is found on the copy, not by your client on the live site.

Doing it by hand versus automating it

You can do this manually with a browser and some patience, and there are general-purpose tools for developers. For an agency with many client sites, the real challenge is doing it every time, for every site, without it eating your week.