feat(screenshot): rename "size" option to "scale" (#13254)

Drive-by: fix `caret` handling in `toHaveScreenshot`.

docs/src/api/params.md

@@ -954,8 +954,8 @@ When true, takes a screenshot of the full scrollable page, instead of the curren
 
 An object which specifies clipping of the resulting image. Should have the following fields:
 
-## screenshot-option-size
-- `size` <[ScreenshotSize]<"css"|"device">>
+## screenshot-option-scale
+- `scale` <[ScreenshotScale]<"css"|"device">>
 
 When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of high-dpi devices will be twice as large or even larger. Defaults to `"device"`.
 
@@ -974,7 +974,7 @@ When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`,
 - %%-screenshot-option-omit-background-%%
 - %%-screenshot-option-quality-%%
 - %%-screenshot-option-path-%%
-- %%-screenshot-option-size-%%
+- %%-screenshot-option-scale-%%
 - %%-screenshot-option-fonts-%%
 - %%-screenshot-option-caret-%%
 - %%-screenshot-option-type-%%

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

@@ -1519,7 +1519,7 @@ export type PageExpectScreenshotParams = {
     omitBackground?: boolean,
     caret?: 'hide' | 'initial',
     animations?: 'disabled' | 'allow',
-    size?: 'css' | 'device',
+    scale?: 'css' | 'device',
     fonts?: 'ready' | 'nowait',
     mask?: {
       frame: FrameChannel,
@@ -1545,7 +1545,7 @@ export type PageExpectScreenshotOptions = {
     omitBackground?: boolean,
     caret?: 'hide' | 'initial',
     animations?: 'disabled' | 'allow',
-    size?: 'css' | 'device',
+    scale?: 'css' | 'device',
     fonts?: 'ready' | 'nowait',
     mask?: {
       frame: FrameChannel,
@@ -1569,7 +1569,7 @@ export type PageScreenshotParams = {
   omitBackground?: boolean,
   caret?: 'hide' | 'initial',
   animations?: 'disabled' | 'allow',
-  size?: 'css' | 'device',
+  scale?: 'css' | 'device',
   fonts?: 'ready' | 'nowait',
   mask?: {
     frame: FrameChannel,
@@ -1585,7 +1585,7 @@ export type PageScreenshotOptions = {
   omitBackground?: boolean,
   caret?: 'hide' | 'initial',
   animations?: 'disabled' | 'allow',
-  size?: 'css' | 'device',
+  scale?: 'css' | 'device',
   fonts?: 'ready' | 'nowait',
   mask?: {
     frame: FrameChannel,
@@ -2905,7 +2905,7 @@ export type ElementHandleScreenshotParams = {
   omitBackground?: boolean,
   caret?: 'hide' | 'initial',
   animations?: 'disabled' | 'allow',
-  size?: 'css' | 'device',
+  scale?: 'css' | 'device',
   fonts?: 'ready' | 'nowait',
   mask?: {
     frame: FrameChannel,
@@ -2919,7 +2919,7 @@ export type ElementHandleScreenshotOptions = {
   omitBackground?: boolean,
   caret?: 'hide' | 'initial',
   animations?: 'disabled' | 'allow',
-  size?: 'css' | 'device',
+  scale?: 'css' | 'device',
   fonts?: 'ready' | 'nowait',
   mask?: {
     frame: FrameChannel,

packages/playwright-core/src/protocol/protocol.yml

@@ -323,7 +323,7 @@ CommonScreenshotOptions:
       literals:
       - disabled
       - allow
-    size:
+    scale:
       type: enum?
       literals:
       - css

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

@@ -563,7 +563,7 @@ export function createScheme(tChannel: (name: string) => Validator): Scheme {
       omitBackground: tOptional(tBoolean),
       caret: tOptional(tEnum(['hide', 'initial'])),
       animations: tOptional(tEnum(['disabled', 'allow'])),
-      size: tOptional(tEnum(['css', 'device'])),
+      scale: tOptional(tEnum(['css', 'device'])),
       fonts: tOptional(tEnum(['ready', 'nowait'])),
       mask: tOptional(tArray(tObject({
         frame: tChannel('Frame'),
@@ -580,7 +580,7 @@ export function createScheme(tChannel: (name: string) => Validator): Scheme {
     omitBackground: tOptional(tBoolean),
     caret: tOptional(tEnum(['hide', 'initial'])),
     animations: tOptional(tEnum(['disabled', 'allow'])),
-    size: tOptional(tEnum(['css', 'device'])),
+    scale: tOptional(tEnum(['css', 'device'])),
     fonts: tOptional(tEnum(['ready', 'nowait'])),
     mask: tOptional(tArray(tObject({
       frame: tChannel('Frame'),
@@ -1085,7 +1085,7 @@ export function createScheme(tChannel: (name: string) => Validator): Scheme {
     omitBackground: tOptional(tBoolean),
     caret: tOptional(tEnum(['hide', 'initial'])),
     animations: tOptional(tEnum(['disabled', 'allow'])),
-    size: tOptional(tEnum(['css', 'device'])),
+    scale: tOptional(tEnum(['css', 'device'])),
     fonts: tOptional(tEnum(['ready', 'nowait'])),
     mask: tOptional(tArray(tObject({
       frame: tChannel('Frame'),

packages/playwright-core/src/server/chromium/crPage.ts

@@ -252,7 +252,7 @@ export class CRPage implements PageDelegate {
     await this._mainFrameSession._client.send('Emulation.setDefaultBackgroundColorOverride', { color });
   }
 
-  async takeScreenshot(progress: Progress, format: 'png' | 'jpeg', documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, size: 'css' | 'device'): Promise<Buffer> {
+  async takeScreenshot(progress: Progress, format: 'png' | 'jpeg', documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, scale: 'css' | 'device'): Promise<Buffer> {
     const { visualViewport } = await this._mainFrameSession._client.send('Page.getLayoutMetrics');
     if (!documentRect) {
       documentRect = {
@@ -267,7 +267,7 @@ export class CRPage implements PageDelegate {
     // When taking screenshots with documentRect (based on the page content, not viewport),
     // ignore current page scale.
     const clip = { ...documentRect, scale: viewportRect ? visualViewport.scale : 1 };
-    if (size === 'css') {
+    if (scale === 'css') {
       const deviceScaleFactor = this._browserContext._options.deviceScaleFactor || 1;
       clip.scale /= deviceScaleFactor;
     }

packages/playwright-core/src/server/firefox/ffPage.ts

@@ -412,7 +412,7 @@ export class FFPage implements PageDelegate {
       throw new Error('Not implemented');
   }
 
-  async takeScreenshot(progress: Progress, format: 'png' | 'jpeg', documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, size: 'css' | 'device'): Promise<Buffer> {
+  async takeScreenshot(progress: Progress, format: 'png' | 'jpeg', documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, scale: 'css' | 'device'): Promise<Buffer> {
     if (!documentRect) {
       const scrollOffset = await this._page.mainFrame().waitForFunctionValueInUtility(progress, () => ({ x: window.scrollX, y: window.scrollY }));
       documentRect = {
@@ -428,7 +428,7 @@ export class FFPage implements PageDelegate {
     const { data } = await this._session.send('Page.screenshot', {
       mimeType: ('image/' + format) as ('image/png' | 'image/jpeg'),
       clip: documentRect,
-      omitDeviceScaleFactor: size === 'css',
+      omitDeviceScaleFactor: scale === 'css',
     });
     return Buffer.from(data, 'base64');
   }

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

@@ -62,7 +62,7 @@ export interface PageDelegate {
   bringToFront(): Promise<void>;
 
   setBackgroundColor(color?: { r: number; g: number; b: number; a: number; }): Promise<void>;
-  takeScreenshot(progress: Progress, format: string, documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, size: 'css' | 'device'): Promise<Buffer>;
+  takeScreenshot(progress: Progress, format: string, documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, scale: 'css' | 'device'): Promise<Buffer>;
 
   isElementHandle(remoteObject: any): boolean;
   adoptElementHandle<T extends Node>(handle: dom.ElementHandle<T>, to: dom.FrameExecutionContext): Promise<dom.ElementHandle<T>>;

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

@@ -40,7 +40,7 @@ export type ScreenshotOptions = {
   mask?: { frame: Frame, selector: string}[],
   fullPage?: boolean,
   clip?: Rect,
-  size?: 'css' | 'device',
+  scale?: 'css' | 'device',
   fonts?: 'ready' | 'nowait',
   caret?: 'hide' | 'initial',
 };
@@ -278,7 +278,7 @@ export class Screenshotter {
     const cleanupHighlight = await this._maskElements(progress, options);
     progress.throwIfAborted(); // Avoid extra work.
 
-    const buffer = await this._page._delegate.takeScreenshot(progress, format, documentRect, viewportRect, options.quality, fitsViewport, options.size || 'device');
+    const buffer = await this._page._delegate.takeScreenshot(progress, format, documentRect, viewportRect, options.quality, fitsViewport, options.scale || 'device');
     progress.throwIfAborted(); // Avoid restoring after failure - should be done by cleanup.
 
     await cleanupHighlight();

packages/playwright-core/src/server/webkit/wkPage.ts

@@ -821,9 +821,9 @@ export class WKPage implements PageDelegate {
     this._recordingVideoFile = null;
   }
 
-  async takeScreenshot(progress: Progress, format: string, documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, size: 'css' | 'device'): Promise<Buffer> {
+  async takeScreenshot(progress: Progress, format: string, documentRect: types.Rect | undefined, viewportRect: types.Rect | undefined, quality: number | undefined, fitsViewport: boolean, scale: 'css' | 'device'): Promise<Buffer> {
     const rect = (documentRect || viewportRect)!;
-    const result = await this._session.send('Page.snapshotRect', { ...rect, coordinateSystem: documentRect ? 'Page' : 'Viewport', omitDeviceScaleFactor: size === 'css' });
+    const result = await this._session.send('Page.snapshotRect', { ...rect, coordinateSystem: documentRect ? 'Page' : 'Viewport', omitDeviceScaleFactor: scale === 'css' });
     const prefix = 'data:image/png;base64,';
     let buffer = Buffer.from(result.dataURL.substr(prefix.length), 'base64');
     if (format === 'jpeg')

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

@@ -8188,7 +8188,7 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
      * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of
      * high-dpi devices will be twice as large or even larger. Defaults to `"device"`.
      */
-    size?: "css"|"device";
+    scale?: "css"|"device";
 
     /**
      * Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
@@ -15770,7 +15770,7 @@ export interface LocatorScreenshotOptions {
    * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of
    * high-dpi devices will be twice as large or even larger. Defaults to `"device"`.
    */
-  size?: "css"|"device";
+  scale?: "css"|"device";
 
   /**
    * Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
@@ -15960,7 +15960,7 @@ export interface PageScreenshotOptions {
    * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of
    * high-dpi devices will be twice as large or even larger. Defaults to `"device"`.
    */
-  size?: "css"|"device";
+  scale?: "css"|"device";
 
   /**
    * Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by

packages/playwright-test/src/matchers/toMatchSnapshot.ts

@@ -311,7 +311,8 @@ export async function toHaveScreenshot(
   const screenshotOptions = {
     animations: config?.animations ?? 'disabled',
     fonts: config?.fonts ?? 'ready',
-    size: config?.size ?? 'css',
+    scale: config?.scale ?? 'css',
+    caret: config?.caret ?? 'hide',
     ...helper.allOptions,
     mask: (helper.allOptions.mask || []) as LocatorEx[],
     name: undefined,

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

@@ -75,12 +75,12 @@ type ExpectSettings = {
      * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of
      * high-dpi devices will be twice as large or even larger. Defaults to `"css"`.
      */
-    size?: 'css'|'device',
+    scale?: 'css'|'device',
     /**
      * When set to `"hide"`, screenshot will hide text caret.
      * When set to `"initial"`, text caret behavior will not be changed. Defaults to `"hide"`.
      */
-    caret?: 'hide'|'initia',
+    caret?: 'hide'|'initial',
   }
   toMatchSnapshot?: {
     /** An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between pixels in compared images, between zero (strict) and one (lax). Defaults to `0.2`.

tests/library/screenshot.spec.ts

@@ -90,20 +90,20 @@ browserTest.describe('page screenshot', () => {
     await context.close();
   });
 
-  browserTest('should work with device scale factor and size:css', async ({ browser, server }) => {
+  browserTest('should work with device scale factor and scale:css', async ({ browser, server }) => {
     const context = await browser.newContext({ viewport: { width: 320, height: 480 }, deviceScaleFactor: 2 });
     const page = await context.newPage();
     await page.goto(server.PREFIX + '/grid.html');
-    const screenshot = await page.screenshot({ size: 'css' });
+    const screenshot = await page.screenshot({ scale: 'css' });
     expect(screenshot).toMatchSnapshot('screenshot-device-scale-factor-css-size.png');
     await context.close();
   });
 
-  browserTest('should work with device scale factor, clip and size:css', async ({ browser, server }) => {
+  browserTest('should work with device scale factor, clip and scale:css', async ({ browser, server }) => {
     const context = await browser.newContext({ viewport: { width: 500, height: 500 }, deviceScaleFactor: 3 });
     const page = await context.newPage();
     await page.goto(server.PREFIX + '/grid.html');
-    const screenshot = await page.screenshot({ clip: { x: 50, y: 100, width: 150, height: 100 }, size: 'css' });
+    const screenshot = await page.screenshot({ clip: { x: 50, y: 100, width: 150, height: 100 }, scale: 'css' });
     expect(screenshot).toMatchSnapshot('screenshot-device-scale-factor-clip-css-size.png');
     await context.close();
   });
@@ -396,7 +396,7 @@ browserTest.describe('element screenshot', () => {
     await context.close();
   });
 
-  browserTest('should capture full element when larger than viewport with device scale factor and size:css', async ({ browser }) => {
+  browserTest('should capture full element when larger than viewport with device scale factor and scale:css', async ({ browser }) => {
     const context = await browser.newContext({ viewport: { width: 501, height: 501 }, deviceScaleFactor: 2.5 });
     const page = await context.newPage();
     await page.setContent(`
@@ -416,7 +416,7 @@ browserTest.describe('element screenshot', () => {
       </style>
       <div class="to-screenshot"></div>
     `);
-    const screenshot = await page.locator('div.to-screenshot').screenshot({ size: 'css' });
+    const screenshot = await page.locator('div.to-screenshot').screenshot({ scale: 'css' });
     expect(screenshot).toMatchSnapshot('element-larger-than-viewport-dsf-css-size.png');
     await context.close();
   });

tests/playwright-test/to-have-screenshot.spec.ts

@@ -73,7 +73,7 @@ test('should disable animations by default', async ({ runInlineTest }, testInfo)
   expect(result.exitCode).toBe(0);
 });
 
-test('should have size as css by default', async ({ runInlineTest }, testInfo) => {
+test('should have scale:css by default', async ({ runInlineTest }, testInfo) => {
   const result = await runInlineTest({
     ...playwrightConfig({ screenshotsDir: '__screenshots__' }),
     'a.spec.js': `
@@ -339,6 +339,24 @@ test('should generate default name', async ({ runInlineTest }, testInfo) => {
 
 test('should compile with different option combinations', async ({ runTSC }) => {
   const result = await runTSC({
+    'playwright.config.ts': `
+      import type { PlaywrightTestConfig } from '@playwright/test';
+      const config: PlaywrightTestConfig = {
+        expect: {
+          timeout: 10000,
+          toHaveScreenshot: {
+            threshold: 0.2,
+            maxDiffPixels: 10,
+            maxDiffPixelRatio: 0.2,
+            animations: "allow",
+            fonts: "ready",
+            caret: "hide",
+            scale: "css",
+          },
+        },
+      };
+      export default config;
+    `,
     'a.spec.ts': `
       const { test } = pwt;
       test('is a test', async ({ page }) => {
@@ -351,6 +369,9 @@ test('should compile with different option combinations', async ({ runTSC }) =>
           maxDiffPixelRatio: 0.2,
           animations: "disabled",
           omitBackground: true,
+          fonts: "nowait",
+          caret: "initial",
+          scale: "device",
           timeout: 1000,
         });
       });

utils/generate_types/overrides-test.d.ts

@@ -74,12 +74,12 @@ type ExpectSettings = {
      * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of
      * high-dpi devices will be twice as large or even larger. Defaults to `"css"`.
      */
-    size?: 'css'|'device',
+    scale?: 'css'|'device',
     /**
      * When set to `"hide"`, screenshot will hide text caret.
      * When set to `"initial"`, text caret behavior will not be changed. Defaults to `"hide"`.
      */
-    caret?: 'hide'|'initia',
+    caret?: 'hide'|'initial',
   }
   toMatchSnapshot?: {
     /** An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between pixels in compared images, between zero (strict) and one (lax). Defaults to `0.2`.