feat(api): add page.emulateVisionDeficiency(type) (#5901)

Design doc: https://goo.gle/devtools-cvd

docs/api.md

@@ -119,6 +119,7 @@
   * [page.emulateMediaFeatures(features)](#pageemulatemediafeaturesfeatures)
   * [page.emulateMediaType(type)](#pageemulatemediatypetype)
   * [page.emulateTimezone(timezoneId)](#pageemulatetimezonetimezoneid)
+  * [page.emulateVisionDeficiency(type)](#pageemulatevisiondeficiencytype)
   * [page.evaluate(pageFunction[, ...args])](#pageevaluatepagefunction-args)
   * [page.evaluateHandle(pageFunction[, ...args])](#pageevaluatehandlepagefunction-args)
   * [page.evaluateOnNewDocument(pageFunction[, ...args])](#pageevaluateonnewdocumentpagefunction-args)
@@ -1393,6 +1394,31 @@ await page.evaluate(() => matchMedia('print').matches);
 - `timezoneId` <?[string]> Changes the timezone of the page. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. Passing `null` disables timezone emulation.
 - returns: <[Promise]>
 
+#### page.emulateVisionDeficiency(type)
+- `type` <?[string]> Simulates the given vision deficiency on the page. Supported vision deficiency types are `'achromatopsia'`, `'deuteranopia'`, `'protanopia'`, `'tritanopia'`, `'blurredVision'`, and `'none'`.
+- returns: <[Promise]>
+
+```js
+const puppeteer = require('puppeteer');
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.goto('https://v8.dev/blog/10-years');
+
+  await page.emulateVisionDeficiency('achromatopsia');
+  await page.screenshot({ path: 'achromatopsia.png' });
+
+  await page.emulateVisionDeficiency('deuteranopia');
+  await page.screenshot({ path: 'deuteranopia.png' });
+
+  await page.emulateVisionDeficiency('blurredVision');
+  await page.screenshot({ path: 'blurred-vision.png' });
+
+  await browser.close();
+})();
+```
+
 #### page.evaluate(pageFunction[, ...args])
 - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`

src/Page.ts

@@ -128,6 +128,15 @@ const paperFormats: Record<string, PaperFormat> = {
   a6: { width: 4.13, height: 5.83 },
 } as const;
 
+enum VisionDeficiency {
+  none = 'none',
+  achromatopsia = 'achromatopsia',
+  blurredVision = 'blurredVision',
+  deuteranopia = 'deuteranopia',
+  protanopia = 'protanopia',
+  tritanopia = 'tritanopia',
+}
+
 class ScreenshotTaskQueue {
   _chain: Promise<Buffer | string | void>;
 
@@ -920,6 +929,21 @@ export class Page extends EventEmitter {
     }
   }
 
+  async emulateVisionDeficiency(type?: VisionDeficiency): Promise<void> {
+    const visionDeficiencies = new Set(Object.keys(VisionDeficiency));
+    try {
+      assert(
+        !type || visionDeficiencies.has(type),
+        `Unsupported vision deficiency: ${type}`
+      );
+      await this._client.send('Emulation.setEmulatedVisionDeficiency', {
+        type: type || 'none',
+      });
+    } catch (error) {
+      throw error;
+    }
+  }
+
   async setViewport(viewport: Viewport): Promise<void> {
     const needsReload = await this._emulationManager.emulateViewport(viewport);
     this._viewport = viewport;

test/emulation.spec.js

@@ -351,4 +351,65 @@ describe('Emulation', () => {
       expect(error.message).toBe('Invalid timezone ID: Baz/Qux');
     });
   });
+
+  describeFailsFirefox('Page.emulateVisionDeficiency', function () {
+    it('should work', async () => {
+      const { page, server } = getTestState();
+
+      await page.setViewport({ width: 500, height: 500 });
+      await page.goto(server.PREFIX + '/grid.html');
+
+      {
+        await page.emulateVisionDeficiency('none');
+        const screenshot = await page.screenshot();
+        expect(screenshot).toBeGolden('screenshot-sanity.png');
+      }
+
+      {
+        await page.emulateVisionDeficiency('achromatopsia');
+        const screenshot = await page.screenshot();
+        expect(screenshot).toBeGolden('vision-deficiency-achromatopsia.png');
+      }
+
+      {
+        await page.emulateVisionDeficiency('blurredVision');
+        const screenshot = await page.screenshot();
+        expect(screenshot).toBeGolden('vision-deficiency-blurredVision.png');
+      }
+
+      {
+        await page.emulateVisionDeficiency('deuteranopia');
+        const screenshot = await page.screenshot();
+        expect(screenshot).toBeGolden('vision-deficiency-deuteranopia.png');
+      }
+
+      {
+        await page.emulateVisionDeficiency('protanopia');
+        const screenshot = await page.screenshot();
+        expect(screenshot).toBeGolden('vision-deficiency-protanopia.png');
+      }
+
+      {
+        await page.emulateVisionDeficiency('tritanopia');
+        const screenshot = await page.screenshot();
+        expect(screenshot).toBeGolden('vision-deficiency-tritanopia.png');
+      }
+
+      {
+        await page.emulateVisionDeficiency('none');
+        const screenshot = await page.screenshot();
+        expect(screenshot).toBeGolden('screenshot-sanity.png');
+      }
+    });
+
+    it('should throw for invalid vision deficiencies', async () => {
+      const { page } = getTestState();
+
+      let error = null;
+      await page
+        .emulateVisionDeficiency('invalid')
+        .catch((error_) => (error = error_));
+      expect(error.message).toBe('Unsupported vision deficiency: invalid');
+    });
+  });
 });

utils/doclint/check_public_api/index.js

@@ -604,6 +604,13 @@ function compareDocumentations(actual, expected) {
           expectedName: '...CookieParam',
         },
       ],
+      [
+        'Method Page.emulateVisionDeficiency() type',
+        {
+          actualName: 'string',
+          expectedName: 'VisionDeficiency',
+        },
+      ],
     ]);
 
     const expectedForSource = expectedNamingMismatches.get(source);