feat(screenshot): Add customizable color option for masked elements (#23185)

I added a new option to the screenshot method to customize the color of
the box when we want to mask some elements for the screenshot.

The default color is pink `#FF00FF`, but with this new option you can
specify the color you like the most, like a nice green `#00FF00`:

```js
await page.screenshot({
  mask: [page.locator('div').nth(5)],
  maskColor: "#00FF00",
})
```


![ss](https://github.com/microsoft/playwright/assets/23271049/05f754de-0ba6-47a3-ae3e-769720d3da3b)

---------

Signed-off-by: Jasiel Guillén <darkensses@gmail.com>

docs/src/api/class-elementhandle.md

@@ -741,6 +741,9 @@ Returns the buffer with the captured screenshot.
 ### option: ElementHandle.screenshot.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
+### option: ElementHandle.screenshot.maskColor = %%-screenshot-option-mask-color-%%
+* since: v1.34
+
 ## async method: ElementHandle.scrollIntoViewIfNeeded
 * since: v1.8
 

docs/src/api/class-locator.md

@@ -1768,6 +1768,9 @@ Returns the buffer with the captured screenshot.
 ### option: Locator.screenshot.timeout = %%-input-timeout-js-%%
 * since: v1.14
 
+### option: Locator.screenshot.maskColor = %%-screenshot-option-mask-color-%%
+* since: v1.34
+
 ## async method: Locator.scrollIntoViewIfNeeded
 * since: v1.14
 

docs/src/api/class-page.md

@@ -3381,6 +3381,9 @@ Returns the buffer with the captured screenshot.
 ### option: Page.screenshot.clip = %%-screenshot-option-clip-%%
 * since: v1.8
 
+### option: Page.screenshot.maskColor = %%-screenshot-option-mask-color-%%
+* since: v1.34
+
 ## async method: Page.selectOption
 * since: v1.8
 * discouraged: Use locator-based [`method: Locator.selectOption`] instead. Read more about [locators](../locators.md).

docs/src/api/params.md

@@ -1092,6 +1092,12 @@ 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` that completely covers its bounding box.
 
+## screenshot-option-mask-color
+* since: v1.34
+- `maskColor` <[string]>
+
+Specify the color of the overlay box for masked elements, in [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
+
 ## screenshot-option-full-page
 - `fullPage` <[boolean]>
 

packages/playwright-core/src/protocol/validator.ts

@@ -1046,6 +1046,7 @@ scheme.PageExpectScreenshotParams = tObject({
       frame: tChannel(['Frame']),
       selector: tString,
     }))),
+    maskColor: tOptional(tString),
   })),
 });
 scheme.PageExpectScreenshotResult = tObject({
@@ -1069,6 +1070,7 @@ scheme.PageScreenshotParams = tObject({
     frame: tChannel(['Frame']),
     selector: tString,
   }))),
+  maskColor: tOptional(tString),
 });
 scheme.PageScreenshotResult = tObject({
   binary: tBinary,
@@ -1876,6 +1878,7 @@ scheme.ElementHandleScreenshotParams = tObject({
     frame: tChannel(['Frame']),
     selector: tString,
   }))),
+  maskColor: tOptional(tString),
 });
 scheme.ElementHandleScreenshotResult = tObject({
   binary: tBinary,

packages/playwright-core/src/server/frames.ts

@@ -857,12 +857,12 @@ export class Frame extends SdkObject {
     return result;
   }
 
-  async maskSelectors(selectors: ParsedSelector[]): Promise<void> {
+  async maskSelectors(selectors: ParsedSelector[], color?: string): Promise<void> {
     const context = await this._utilityContext();
     const injectedScript = await context.injectedScript();
-    await injectedScript.evaluate((injected, { parsed }) => {
-      injected.maskSelectors(parsed);
-    }, { parsed: selectors });
+    await injectedScript.evaluate((injected, { parsed, color }) => {
+      injected.maskSelectors(parsed, color);
+    }, { parsed: selectors, color: color });
   }
 
   async querySelectorAll(selector: string): Promise<dom.ElementHandle<Element>[]> {

packages/playwright-core/src/server/injected/highlight.ts

@@ -154,8 +154,8 @@ export class Highlight {
     this._innerUpdateHighlight(elements, { color, tooltipText: selector ? asLocator(this._language, selector) : '' });
   }
 
-  maskElements(elements: Element[]) {
-    this._innerUpdateHighlight(elements, { color: '#F0F' });
+  maskElements(elements: Element[], color?: string) {
+    this._innerUpdateHighlight(elements, { color: color ? color : '#F0F' });
   }
 
   private _innerUpdateHighlight(elements: Element[], options: { color: string, tooltipText?: string }) {

packages/playwright-core/src/server/injected/injectedScript.ts

@@ -1093,7 +1093,7 @@ export class InjectedScript {
     return error;
   }
 
-  maskSelectors(selectors: ParsedSelector[]) {
+  maskSelectors(selectors: ParsedSelector[], color?: string) {
     if (this._highlight)
       this.hideHighlight();
     this._highlight = new Highlight(this);
@@ -1101,7 +1101,7 @@ export class InjectedScript {
     const elements = [];
     for (const selector of selectors)
       elements.push(this.querySelectorAll(selector, this.document.documentElement));
-    this._highlight.maskElements(elements.flat());
+    this._highlight.maskElements(elements.flat(), color);
   }
 
   highlight(selector: ParsedSelector) {

packages/playwright-core/src/server/screenshotter.ts

@@ -38,6 +38,7 @@ export type ScreenshotOptions = {
   omitBackground?: boolean,
   animations?: 'disabled' | 'allow',
   mask?: { frame: Frame, selector: string}[],
+  maskColor?: string,
   fullPage?: boolean,
   clip?: Rect,
   scale?: 'css' | 'device',
@@ -268,7 +269,7 @@ export class Screenshotter {
     progress.throwIfAborted(); // Avoid extra work.
 
     await Promise.all([...framesToParsedSelectors.keys()].map(async frame => {
-      await frame.maskSelectors(framesToParsedSelectors.get(frame));
+      await frame.maskSelectors(framesToParsedSelectors.get(frame), options.maskColor);
     }));
     progress.cleanupWhenAborted(cleanup);
     return cleanup;

packages/playwright-core/types/types.d.ts

@@ -9828,6 +9828,12 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
      */
     mask?: Array<Locator>;
 
+    /**
+     * Specify the color of the overlay box for masked elements, in
+     * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
+     */
+    maskColor?: string;
+
     /**
      * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
      * Defaults to `false`.
@@ -19639,6 +19645,12 @@ export interface LocatorScreenshotOptions {
    */
   mask?: Array<Locator>;
 
+  /**
+   * Specify the color of the overlay box for masked elements, in
+   * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
+   */
+  maskColor?: string;
+
   /**
    * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
    * Defaults to `false`.
@@ -19826,6 +19838,12 @@ export interface PageScreenshotOptions {
    */
   mask?: Array<Locator>;
 
+  /**
+   * Specify the color of the overlay box for masked elements, in
+   * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
+   */
+  maskColor?: string;
+
   /**
    * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
    * Defaults to `false`.

packages/protocol/src/channels.ts

@@ -1910,6 +1910,7 @@ export type PageExpectScreenshotParams = {
       frame: FrameChannel,
       selector: string,
     }[],
+    maskColor?: string,
   },
 };
 export type PageExpectScreenshotOptions = {
@@ -1936,6 +1937,7 @@ export type PageExpectScreenshotOptions = {
       frame: FrameChannel,
       selector: string,
     }[],
+    maskColor?: string,
   },
 };
 export type PageExpectScreenshotResult = {
@@ -1959,6 +1961,7 @@ export type PageScreenshotParams = {
     frame: FrameChannel,
     selector: string,
   }[],
+  maskColor?: string,
 };
 export type PageScreenshotOptions = {
   timeout?: number,
@@ -1974,6 +1977,7 @@ export type PageScreenshotOptions = {
     frame: FrameChannel,
     selector: string,
   }[],
+  maskColor?: string,
 };
 export type PageScreenshotResult = {
   binary: Binary,
@@ -3327,6 +3331,7 @@ export type ElementHandleScreenshotParams = {
     frame: FrameChannel,
     selector: string,
   }[],
+  maskColor?: string,
 };
 export type ElementHandleScreenshotOptions = {
   timeout?: number,
@@ -3340,6 +3345,7 @@ export type ElementHandleScreenshotOptions = {
     frame: FrameChannel,
     selector: string,
   }[],
+  maskColor?: string,
 };
 export type ElementHandleScreenshotResult = {
   binary: Binary,

packages/protocol/src/protocol.yml

@@ -376,6 +376,7 @@ CommonScreenshotOptions:
         properties:
           frame: Frame
           selector: string
+    maskColor: string?
 
 LaunchOptions:
   type: mixin

tests/page/page-screenshot.spec.ts

@@ -534,6 +534,15 @@ it.describe('page screenshot', () => {
       });
       await page.screenshot({ mask: [page.locator('non-existent')] });
     });
+
+    it('should work when mask color is not pink #F0F', async ({ page, server }) => {
+      await page.setViewportSize({ width: 500, height: 500 });
+      await page.goto(server.PREFIX + '/grid.html');
+      expect(await page.screenshot({
+        mask: [page.locator('div').nth(5)],
+        maskColor: '#00FF00',
+      })).toMatchSnapshot('mask-color-should-work.png');
+    });
   });
 });