Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

chore(screenshot): warn about visibility of masked elements (#34881)

Simon Knott48fb536e1245
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index e3968f622d..9a87db7f6a 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -1229,6 +1229,7 @@ Specify screenshot type, defaults to `png`.
Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with
a pink box `#FF00FF` (customized by [`option: maskColor`]) that completely covers its bounding box.
+The mask is also applied to invisible elements, see [Matching only visible elements](../locators.md#matching-only-visible-elements) to disable that.
## screenshot-option-mask-color
* since: v1.35
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 7d0806bb69..ff2ef43aa1 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -11751,7 +11751,8 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-elementhandle#element-handle-screenshot-option-mask-color))
- * that completely covers its bounding box.
+ * that completely covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
@@ -22048,7 +22049,8 @@ export interface LocatorScreenshotOptions {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-locator#locator-screenshot-option-mask-color)) that completely
- * covers its bounding box.
+ * covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
@@ -22772,7 +22774,8 @@ export interface PageScreenshotOptions {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-page#page-screenshot-option-mask-color)) that completely covers
- * its bounding box.
+ * its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 7d0806bb69..ff2ef43aa1 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -11751,7 +11751,8 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-elementhandle#element-handle-screenshot-option-mask-color))
- * that completely covers its bounding box.
+ * that completely covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
@@ -22048,7 +22049,8 @@ export interface LocatorScreenshotOptions {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-locator#locator-screenshot-option-mask-color)) that completely
- * covers its bounding box.
+ * covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
@@ -22772,7 +22774,8 @@ export interface PageScreenshotOptions {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-page#page-screenshot-option-mask-color)) that completely covers
- * its bounding box.
+ * its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index a13ec126c4..4c2766232d 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -8514,7 +8514,8 @@ interface LocatorAssertions {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-mask-color))
- * that completely covers its bounding box.
+ * that completely covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
@@ -8606,7 +8607,8 @@ interface LocatorAssertions {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-mask-color))
- * that completely covers its bounding box.
+ * that completely covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;
@@ -9768,7 +9770,8 @@ export interface PageAssertionsToHaveScreenshotOptions {
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1-option-mask-color))
- * that completely covers its bounding box.
+ * that completely covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
mask?: Array<Locator>;