Visual Regression Testing Across Locales with Percy and WonderProxy

Catch layout bugs introduced by language or region-based differences.

Expanding to multiple regions brings opportunities, but 'fully translated' doesn't guarantee 'fully functional.' Buttons shift, text wraps in weird places, and certain assets don’t even load. Those small details can quietly break your user experience.

Visual regression testing across locales helps you spot those differences before users do. When you combine Percy for automated visual diffs with WonderProxy for true location-based testing, you can see exactly what your site looks like in any part of the world. With this combo, there are no surprises or guessing.

Why localized visual testing matters

Visual regression testing aims to catch unintended UI changes. Percy makes this simple: it takes snapshots of your app, compares them against a baseline, and highlights any visual differences.

But when you’re running a site in multiple languages and regions, the visuals themselves change. Fonts, currency formats, and even layout direction can change depending on where your users reside. For instance, a long string in Finnish might push a button off-screen, while a currency symbol in Thailand might not render at all. These subtle shifts can disrupt your layout if you’re not looking for them.

Simply mocking those conditions locally often falls short. That’s why routing your tests through real regional servers - like with Wonderproxy - is so powerful.

How Percy and WonderProxy fit together

Before testing with Percy, it helps to automate browser behavior using a tool like Playwright. It opens your site and interacts with it just like a real user, making testing pages reliable.

Here’s the workflow in simple terms:

1. Playwright opens your site in a browser.
2. WonderProxy routes the browser through a real country-specific server.
3. Percy captures a snapshot of that page.
4. Percy compares it against your baseline and flags any differences.

That’s the core of the process. You’re now testing your design under real-world conditions, from real places, in a fully automated way.

Setting up Percy with Playwright

If you’re already using Playwright for testing, adding Percy is straightforward.

Install the packages:

npm install --save-dev @percy/cli @percy/playwright

Note: Run your tests with Percy:
npx percy exec -- npx playwright test
If you have a playwright.config.js, Percy will use it automatically.

Then update your test script:

import { test, expect } from '@playwright/test';
import percySnapshot from '@percy/playwright';

test('homepage visual snapshot', async ({ page }) => {
  await page.goto('https://example.com');
  await percySnapshot(page, 'Homepage');
});

Run it like this:

npx percy exec -- npx playwright test

That’s the basic Percy workflow. It takes a screenshot, sends it to Percy’s servers, and compares it to your baseline.

Adding WonderProxy to the mix

Now, let’s run the same test through different locales.

WonderProxy routes your HTTP traffic through servers worldwide, using real, geolocated IPs instead of VPNs or header tricks. This way, sites load as they would for a local user.

You’ll need your WonderProxy credentials (username and password or an API key). Then, configure Playwright to use a proxy:

import { test, expect, chromium } from '@playwright/test';
import percySnapshot from '@percy/playwright';

const locales = [
  { code: 'de', location: 'Germany', subdomain: 'berlin' },
  { code: 'jp', location: 'Japan', subdomain: 'tokyo' },
  { code: 'br', location: 'Brazil', subdomain: 'saopaulo' }
];

for (const locale of locales) {
  test(`Visual check from ${locale.location}`, async () => {
    const browser = await chromium.launch({
      proxy: {
        server: `http://${locale.subdomain}.wonderproxy.com:11000`,
        username: process.env.WONDERPROXY_USER,
        password: process.env.WONDERPROXY_PASS
      }
    });

    const page = await browser.newPage();
    await page.goto('https://example.com');
    await percySnapshot(page, `Homepage - ${locale.location}`);
    await browser.close();
  });
}

Each test connects through a different WonderProxy server and takes a Percy snapshot. This means you’ll end up with localized visual diffs. For example, Homepage - Japan might have slightly different line breaks or fonts compared to Homepage - Germany.

Note: Some tools require embedding credentials in the proxy URL (http://user:pass@proxy), but Playwright handles authentication cleanly with separate fields, as shown here.

Running tests in CI

In CI, the setup works the same way. Store your WonderProxy credentials as environment variables, and Percy will automatically capture snapshots per locale.
You can run tests in parallel to speed up the process.

However, be mindful of your account’s connection limits and fair-use policies if you’re accessing multiple proxy locations simultaneously.

Best practices for multi-locale visual testing

Testing every locale can feel overwhelming, so having a clear plan helps you identify the most critical issues faster. Here are a few tips to consider:

• Pick your locales strategically: You don’t need to test all 200 locales. Focus on those with large user bases or layout quirks (e.g., long words, right-to-left (RTL) text, or unique fonts).
• Name snapshots clearly: Include the locale or country in the name so it’s easy to find in Percy’s dashboard.
• Control dynamic content: Disable ads, A/B tests, or live feeds that could create unnecessary visual changes.
• Keep baselines separate: Each locale may require its own baseline, especially if regional content varies.
• Be mindful of latency: Depending on server location, pages may load at different speeds. Add small waits if assets don’t finish loading before the snapshot.

You may also want to test critical flows in parallel across locales. It’s a quick way to catch timing-related layout bugs caused by slow assets or regional CDNs. This helps you spot not just the visual issues, but when they occur.

Wrapping up

When you combine Percy’s visual testing with WonderProxy’s global routing, you cover a critical gap in most test setups: what users actually see in different parts of the world.

You’ll catch translation overflows, alignment issues, and missing assets before your customers do. It’s essential for building a more reliable, polished product.

If you haven’t tried it yet, use WonderProxy with Percy to take snapshots across locales. You may discover unexpected differences in how your site appears globally.