[Feature]: Enhanced Masking with Ignored Elements in Snapshot Comparison

[aaravbinit]

🚀 Feature Request

Overview

Currently, the mask option in Playwright allows users to overlay elements with a solid color during snapshot comparison. However, snapshot comparisons still include the masked elements, leading to test failures if those elements change.

This feature request proposes an enhancement to allow users to both mask and ignore elements during snapshot comparison. The goal is to:

1. Mask elements with an overlay color so users can see what’s behind them.
2. Ignore changes in masked elements to prevent test failures due to dynamic content.

Current Implementation Limitation
Consider the following example:

const maskElements = [landingPagePo.elm1(), landingPagePo.elm2(), landingPagePo.elm3()];
await expect(page).toHaveScreenshot("snapshot1.png", { 
  fullPage: true, 
  mask: maskElements, 
  maskColor: maskOverlay 
});

Here, maskOverlay is defined in the fixtures file as:

maskOverlay: async ({}, use) => {
  await use("rgb(118, 232, 255)");
},

By default, the mask color is 100% pink, making it impossible to see what’s behind the masked elements. Setting a custom maskOverlay resolves this issue, but masked elements are still compared in the snapshot, causing test failures if they change.

Proposed Enhancement

To fully support both use cases, Playwright should introduce a new option that allows:

1. Masking elements with an overlay color (similar to the current mask option).
2. Ignoring those elements in snapshot comparison to prevent test failures.

One potential approach is to introduce a concept similar to Applitools' ignored elements with padding (reference), which would:

1. Allow users to mask/ignore elements while still displaying an overlay.
2. Prevent snapshot comparisons from failing due to changes in ignored elements.

Suggested Implementation

• Keep the mask option unchanged for users who only want visual masking.
• Introduce a new ignore option that:
  • Hides selected elements from comparison.
  • Allows setting custom padding (instead of a fixed default).
  • Supports an overlay color (or an alternative visualization method).

This enhancement would provide better control over masked elements and improve snapshot testing reliability for dynamic UI components.

Example

User select one or more element to be ignored with extra padding. Something like this when feature is introduce,

const ignoredElements = [landingPagePo.elm1(), landingPagePo.elm2(), landingPagePo.elm3()];
await expect(page).toHaveScreenshot("snapshot1.png", { 
  fullPage: true, 
  ignore: ignoredElements, // this is the feature requesting
  padding = { top: 5, bottom: 5, left: 20, right: 20 } // default 0 if not added and can be configured via config or fixtures
  maskColor: maskOverlay // can be used in both mask and ignored 
});

Motivation

This enhancement would provide better control over masked elements and improve snapshot testing reliability for dynamic UI components. It ensures that snapshots retain full clarity, even for ignored or masked elements, allowing users to see what’s behind them while preventing unnecessary test failures due to expected UI changes.

By introducing an "ignore" option with padding support, users can selectively exclude elements from snapshot comparisons while still applying an overlay color for visibility. This would reduce noise in test failures caused by dynamic elements and improve the accuracy of visual regression testing.

[mxschmitt]

For that we provide the stylePath option, see here to learn more about it: https://playwright.dev/docs/test-snapshots#stylepath

This should allow you to entirely hide elements from your page. You can e.g. annotate them before with custom DOM attributes or just put their selectors inside.

Would that work for you?

[aaravbinit]

Thank you for the response! However, the stylePath option does not achieve the intended goal.

The requirement is not to completely hide elements but to exclude them from snapshot comparison while keeping them visible.

For example, in the attached image (similar to Applitools behavior), the ignored elements are still visible but do not trigger test failures if their content changes.

This is crucial for:

• Ensuring that ignored elements still render correctly.
• Avoiding false test failures caused by dynamic content.
• Providing full visibility into what was displayed in the ignored elements.

Current Issue with maskOverlay:
Using maskOverlay, I can apply a color overlay with lower opacity:

maskOverlay: async ({}, use) => {
  await use("rgb(118, 232, 255)");
}

However, if the text inside the masked elements changes, the test still fails. See this image for example. On the left side I have 100% pink color masked elements. Now whan i changed the mask color with lower opacity, it failed (on the right side)

Why This Feature is Needed:

• Current Playwright behavior: Elements are either masked (but still compared if mask color is set with lower opacity) or completely hidden (stylePath).

Proposed enhancement:

• Elements should remain visible but ignored in the snapshot comparison, similar to Applitools' implementation.

Would it be possible to introduce an ignore option that preserves visibility while excluding elements from comparison? This would provide more flexibility and reduce noise in visual testing.

Thanks for considering this request! Let me know if more details are needed.

[aaravbinit]

Hello @mxschmitt
I noticed that the feature request I submitted was initially tagged for an upcoming release, but has since been moved out of the latest version. I see that it hasn’t been closed, which is encouraging.

Do we know if this feature is expected to be included in an upcoming release or if it's been scheduled for a specific future version?

Also, please let me know if any further clarification is needed from my side to help move it forward.

Thanks again for your time and support!