feat: add fromSurface option

docs/api.md

@@ -2210,6 +2210,7 @@ Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)]
   - `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
   - `encoding` <[string]> The encoding of the image, can be either `base64` or `binary`. Defaults to `binary`.
   - `captureBeyondViewport` <[boolean]> When true, captures screenshot [beyond the viewport](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot). When false, falls back to old behaviour, and cuts the screenshot by the viewport size. Defaults to `true`.
+  - `fromSurface` <[boolean]> When true, captures screenshot [from the surface rather than the view](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot). When false, works only in headful mode and ignores page viewport (but not browser window's bounds). Defaults to `true`.
 - returns: <[Promise]<[string]|[Buffer]>> Promise which resolves to buffer or a base64 string (depending on the value of `encoding`) with captured screenshot.
 
 > **NOTE** Screenshots take at least 1/6 second on OS X. See https://crbug.com/741689 for discussion.

src/common/Page.ts

@@ -197,10 +197,15 @@ export interface ScreenshotOptions {
    */
   encoding?: 'base64' | 'binary';
   /**
-   * If you need a screenshot bigger than the Viewport
+   * Capture the screenshot beyond the viewport.
    * @defaultValue true
    */
   captureBeyondViewport?: boolean;
+  /**
+   * Capture the screenshot from the surface, rather than the view.
+   * @defaultValue true
+   */
+  fromSurface?: boolean;
 }
 
 /**
@@ -2756,7 +2761,7 @@ export class Page extends EventEmitter {
    *   applicable to `png` images.
    *
    * - `fullPage` : When true, takes a screenshot of the full
-   *   scrollable page. Defaults to `false`
+   *   scrollable page. Defaults to `false`.
    *
    * - `clip` : An object which specifies clipping region of the page.
    *   Should have the following fields:<br/>
@@ -2766,11 +2771,21 @@ export class Page extends EventEmitter {
    *  - `height` : height of clipping area.
    *
    * - `omitBackground` : Hides default white background and allows
-   *   capturing screenshots with transparency. Defaults to `false`
+   *   capturing screenshots with transparency. Defaults to `false`.
    *
    * - `encoding` : The encoding of the image, can be either base64 or
    *   binary. Defaults to `binary`.
    *
+   * - `captureBeyondViewport` : When true, captures screenshot
+   *   {@link https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot
+   *   | beyond the viewport}. When false, falls back to old behaviour,
+   *   and cuts the screenshot by the viewport size. Defaults to `true`.
+   *
+   * - `fromSurface` : When true, captures screenshot
+   *   {@link https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot
+   *   | from the surface rather than the view}. When false, works only in
+   *   headful mode and ignores page viewport (but not browser window's
+   *   bounds). Defaults to `true`.
    *
    * NOTE: Screenshots take at least 1/6 second on OS X. See
    * {@link https://crbug.com/741689} for discussion.
@@ -2882,9 +2897,14 @@ export class Page extends EventEmitter {
       targetId: this.#target._targetId,
     });
     let clip = options.clip ? processClip(options.clip) : undefined;
-    let {captureBeyondViewport = true} = options;
-    captureBeyondViewport =
-      typeof captureBeyondViewport === 'boolean' ? captureBeyondViewport : true;
+    const captureBeyondViewport =
+      typeof options.captureBeyondViewport === 'boolean'
+        ? options.captureBeyondViewport
+        : true;
+    const fromSurface =
+      typeof options.fromSurface === 'boolean'
+        ? options.fromSurface
+        : undefined;
 
     if (options.fullPage) {
       const metrics = await this.#client.send('Page.getLayoutMetrics');
@@ -2924,6 +2944,7 @@ export class Page extends EventEmitter {
       quality: options.quality,
       clip,
       captureBeyondViewport,
+      fromSurface,
     });
     if (shouldSetDefaultBackground) {
       await this.#resetDefaultBackgroundColor();

test/src/mocha-utils.ts

@@ -185,6 +185,17 @@ export const itHeadlessOnly = (
   }
 };
 
+export const itHeadfulOnly = (
+  description: string,
+  body: Mocha.Func
+): Mocha.Test => {
+  if (isChrome && isHeadless === false) {
+    return it(description, body);
+  } else {
+    return xit(description, body);
+  }
+};
+
 export const itFirefoxOnly = (
   description: string,
   body: Mocha.Func

test/src/screenshot.spec.ts

@@ -20,6 +20,7 @@ import {
   setupTestBrowserHooks,
   setupTestPageAndContextHooks,
   itFailsFirefox,
+  itHeadfulOnly,
 } from './mocha-utils.js';
 
 describe('Screenshots', function () {
@@ -188,6 +189,16 @@ describe('Screenshots', function () {
         'screenshot-sanity.png'
       );
     });
+    itHeadfulOnly('should work in "fromSurface: false" mode', async () => {
+      const {page, server} = getTestState();
+
+      await page.setViewport({width: 500, height: 500});
+      await page.goto(server.PREFIX + '/grid.html');
+      const screenshot = await page.screenshot({
+        fromSurface: false,
+      });
+      expect(screenshot).toBeGolden('screenshot-fromsurface-false.png');
+    });
   });
 
   describe('ElementHandle.screenshot', function () {