How to Use Targeted Regions for UI Visual Testing

Targeted regions make visual tests more focused: compare the component whose appearance matters, or exclude a known-changing area from a broader screenshot check. In Playwright with Applitools Eyes, pass a locator as region to check one component, or pass a locator in ignoreRegions to omit its pixels from a full-page comparison. Ignore a region only when changes inside it are outside the test’s goal; for important but variable content, use a less strict region match or validate its data separately.

1. Choose what the visual assertion should prove

Start by stating the risk in plain terms. A navigation check might need to catch spacing, color, and typography changes. A timestamp may be irrelevant to that layout check. A price, legal disclosure, or service status can change frequently and still be important to users.

Goal	Approach	What the assertion can miss
Check one component’s appearance	Target the component with region.	Changes outside the component.
Check a whole page except known noise	Use a narrowly scoped ignored region.	All visual changes inside the ignored region.
Check a changing area with less sensitivity	Use a region-specific match level such as Layout, where supported.	Fine-grained visual differences that the comparison mode de-emphasizes.
Check a value that matters	Stabilize test data or assert the value separately, alongside an appropriate visual check.	Nothing by itself; the separate assertion must be implemented.

Target definition varies by tool: element locator, CSS selector, XPath, or fixed coordinates may be available. Element-based targeting can follow the element when layout changes; coordinate boundaries describe a position and size, so layout shifts can make them refer to the wrong content.

2. Stabilize the page before adding masks

1. Use deterministic test data for content the test is meant to compare.
2. Keep viewport and device scale consistent across baseline and test runs.
3. Control time, animation, and asynchronous loading where the test setup allows it.
4. Wait for the target component to be ready before capturing.
5. Only then mark genuinely irrelevant dynamic content as ignored.

Stabilization reduces noise without hiding real regressions. A broad mask can make a test pass while an important component silently changes. Revisit masks when the page or product purpose changes.

3. Check a single component with Applitools Eyes and Playwright

The Applitools Playwright integration documents a locator passed as region to eyes.check(). The following is the core call inside an Applitools Playwright test using its fixture:

import { test } from '@applitools/eyes-playwright/fixture';

test('navigation looks correct', async ({ page, eyes }) => {
  await page.goto('http://localhost:3000');
  const navbar = page.locator('[data-testid="navbar"]');
  await navbar.waitFor({ state: 'visible' });

  await eyes.check('Home navigation', {
    region: navbar,
  });
});

Use a stable selector such as a test ID when available. Give each checkpoint a meaningful name so it is easy to find in the visual testing dashboard. The exact fixture setup, package version, and authentication configuration depend on the Applitools project setup; follow its current integration documentation.

4. Compare a full page while ignoring known dynamic content

For a full-page checkpoint with an irrelevant dynamic area, Applitools’ Playwright example uses fully: true, a strict global match level, and ignoreRegions:

import { test } from '@applitools/eyes-playwright/fixture';

test('product page layout is stable', async ({ page, eyes }) => {
  await page.goto('http://localhost:3000/products/example');
  const dynamicContent = page.locator('[data-testid="live-clock"]');
  await dynamicContent.waitFor({ state: 'visible' });

  await eyes.check('Product page', {
    fully: true,
    matchLevel: 'Strict',
    ignoreRegions: [dynamicContent],
  });
});

An ignored region is excluded from that comparison. If the clock’s dimensions, position, or surrounding layout matter, do not assume this mask will check them; add a separate assertion or choose a comparison behavior that retains the structural check.

5. Ignore, reduce sensitivity, or assert separately?

Ignoring is an all-or-nothing choice for the region’s visual contents. Applitools also documents region-specific match levels: for example, a page can remain Strict while an ad region uses Layout matching. Its documentation notes that a specific region match level can be set only when the global match level is not Layout. This keeps a check on the area while reducing sensitivity to some pixel-level variation.

Use separate semantic assertions for dynamic values whose correctness matters. A visual comparison can show that a price looks misplaced; a direct assertion can verify that the expected price is present. These checks answer different questions and can complement each other.

6. Percy Playwright region options

Percy’s Playwright client documentation describes ignored regions configured by selectors, XPath, or custom coordinates. It also documents per-region algorithms. The available option names include:

Option	Use
ignoreRegionSelectors	Ignore elements selected by CSS selectors.
ignoreRegionXpaths	Ignore regions identified with XPath.
customIgnoreRegions	Supply custom coordinate boundaries or bounding boxes, as supported by the client.
Per-region algorithms	Apply a configured comparison algorithm to a specific region where supported.

Percy’s coordinate boundary form is top, right, bottom, and left; region bounding boxes use x, y, width, and height. Check the installed client’s documentation for the exact configuration shape and version-specific behavior. Prefer selectors when the target has a reliable DOM identity; fixed geometry can become stale after responsive layout or content changes.

7. Review diffs and maintain baselines

1. Inspect the visual diff at the named checkpoint.
2. Decide whether the difference is an intentional design change or an unexpected regression.
3. Accept the checkpoint only when the new appearance is intended; accepting updates the baseline.
4. Reject or investigate differences that are unexplained.
5. Review ignored regions periodically and narrow or remove masks when they no longer match the test’s purpose.

Applitools’ enhanced report supports reviewing diffs and accepting or rejecting changes. A baseline is an expected result that requires human judgment when it changes; automatically accepting every change erases the signal the test is meant to provide.

8. Troubleshooting

Symptom	Likely cause	Fix
Targeted component is missing or empty	The locator matched nothing, or capture happened before it rendered.	Confirm the selector against the rendered page and wait for the locator to become visible before the checkpoint.
Test still fails because content changes	The dynamic element was not included in the ignored region, or the change affects pixels outside it.	Inspect the diff, target the smallest correct element, and stabilize adjacent content if it belongs to the test.
A real regression is no longer detected	The ignored region is too broad or now covers important content.	Narrow the region and add a visual or semantic assertion for the content that matters.
Mask lands over the wrong area	Fixed coordinates no longer align after a layout shift.	Use a DOM-based selector or locator where supported, or update and validate the coordinates at each relevant viewport.
Small rendering differences cause noisy failures	The comparison is stricter than the intended risk, or the page is not stable.	Control test state first; if the area is important but variable, consider a supported reduced-sensitivity region match.
Unexpected diff was accepted into the baseline	The checkpoint was approved without determining whether the change was intended.	Review the current design, restore or create the correct baseline, and add a targeted assertion for the missed behavior.

9. Performance, reliability, and cost

A region check can focus review on a smaller component, but capture and comparison still depend on the tool, page, and integration. Do not assume a targeted region makes browser startup or page loading free. For reliability, keep selectors stable, wait for meaningful readiness conditions, use consistent viewport settings, and avoid masking content that can shift neighboring elements.

For vendor pricing and execution costs, consult the current plans for the visual testing service you use; the source material here does not establish prices, quotas, or performance benchmarks for Applitools or Percy. Budget for baseline review and maintenance as well as test execution. The value of a mask depends on retaining coverage of the visual risks that matter.

10. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. It can capture a page directly, but it does not replace a region assertion inside your visual test framework; use your test tool when you need baseline comparison and pass/fail diffs.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options. Python and Node.js callers can use the same endpoint and URL parameters:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, and failed loads are never billed, and response headers identify the page verdict and billing status. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Every feature is available on every plan. Create a free account at ScreenshotNeo sign-up.

11. FAQ

Can one visual test check several components?

Yes. Use named checkpoints or multiple targeted checks for the components whose appearance matters, according to your tool’s integration.

Is an ignored region the same as a floating region?

No. An ignored region omits its contents from comparison. Applitools lists floating regions as a separate option; consult its documentation for the behavior and constraints of that option.

Should I mask advertisements?

Only if their visual content is outside the test’s purpose. If their placement or dimensions matter, retain a suitable structural comparison or assert those properties separately.