feat(api): remove emulateMedia method (#6084)

It has been deprecated for a while. In the next breaking release let's remove it.

BREAKING CHANGE: swap to `emulateMediaType` instead.

docs/api.md

@@ -115,7 +115,6 @@
   * [page.coverage](#pagecoverage)
   * [page.deleteCookie(...cookies)](#pagedeletecookiecookies)
   * [page.emulate(options)](#pageemulateoptions)
-  * [page.emulateMedia(type)](#pageemulatemediatype)
   * [page.emulateMediaFeatures(features)](#pageemulatemediafeaturesfeatures)
   * [page.emulateMediaType(type)](#pageemulatemediatypetype)
   * [page.emulateTimezone(timezoneId)](#pageemulatetimezonetimezoneid)
@@ -1334,12 +1333,6 @@ const iPhone = puppeteer.devices['iPhone 6'];
 
 List of all available devices is available in the source code: [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts).
 
-#### page.emulateMedia(type)
-- `type` <?[string]> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation.
-- returns: <[Promise]>
-
-**Note:** This method is deprecated, and only kept around as an alias for backwards compatibility. Use [`page.emulateMediaType(type)`](#pageemulatemediatypetype) instead.
-
 #### page.emulateMediaFeatures(features)
 - `features` <?[Array]<[Object]>> Given an array of media feature objects, emulates CSS media features on the page. Each media feature object must have the following properties:
   - `name` <[string]> The CSS media feature name. Supported names are `'prefers-colors-scheme'` and `'prefers-reduced-motion'`.

src/initialize.ts

@@ -20,7 +20,6 @@
 const api = require('./api');
 
 import { helper } from './common/helper';
-import { Page } from './common/Page';
 import { Puppeteer } from './common/Puppeteer';
 
 interface InitOptions {
@@ -42,10 +41,6 @@ export const initializePuppeteer = (options: InitOptions): Puppeteer => {
       helper.installAsyncStackHooks(api[className]);
   }
 
-  // Expose alias for deprecated method.
-  // @ts-expect-error emulateMedia does not exist error
-  Page.prototype.emulateMedia = Page.prototype.emulateMediaType;
-
   let preferredRevision = packageJson.puppeteer.chromium_revision;
   const isPuppeteerCore = packageJson.name === 'puppeteer-core';
   // puppeteer-core ignores environment variables

test/emulation.spec.ts

@@ -146,55 +146,7 @@ describe('Emulation', () => {
     });
   });
 
-  describe('Page.emulateMedia [deprecated]', function () {
-    /* emulateMedia is deprecated in favour of emulateMediaType but we
-     * don't want to remove it from Puppeteer just yet. We can't check
-     * that emulateMedia === emulateMediaType because when running tests
-     * with COVERAGE=1 the methods get rewritten. So instead we
-     * duplicate the tests for emulateMediaType and ensure they pass
-     * when calling the deprecated emulateMedia method.
-     *
-     * If you update these tests, you should update emulateMediaType's
-     * tests, and vice-versa.
-     */
-    itFailsFirefox('should work', async () => {
-      const { page } = getTestState();
-
-      expect(await page.evaluate(() => matchMedia('screen').matches)).toBe(
-        true
-      );
-      expect(await page.evaluate(() => matchMedia('print').matches)).toBe(
-        false
-      );
-      // @ts-expect-error this method is deprecated so we don't declare it
-      await page.emulateMedia('print');
-      expect(await page.evaluate(() => matchMedia('screen').matches)).toBe(
-        false
-      );
-      expect(await page.evaluate(() => matchMedia('print').matches)).toBe(true);
-      // @ts-expect-error this method is deprecated so we don't declare it
-      await page.emulateMedia(null);
-      expect(await page.evaluate(() => matchMedia('screen').matches)).toBe(
-        true
-      );
-      expect(await page.evaluate(() => matchMedia('print').matches)).toBe(
-        false
-      );
-    });
-    it('should throw in case of bad argument', async () => {
-      const { page } = getTestState();
-
-      let error = null;
-      // @ts-expect-error this method is deprecated so we don't declare it
-      await page.emulateMedia('bad').catch((error_) => (error = error_));
-      expect(error.message).toBe('Unsupported media type: bad');
-    });
-  });
-
   describe('Page.emulateMediaType', function () {
-    /* NOTE! Updating these tests? Update the emulateMedia tests above
-     * too (and see the big comment for why we have these duplicated).
-     */
     itFailsFirefox('should work', async () => {
       const { page } = getTestState();
 

utils/doclint/check_public_api/index.js

@@ -172,14 +172,6 @@ function checkDuplicates(doc) {
   return errors;
 }
 
-const expectedNonExistingMethods = new Map([
-  /* Expected to be missing as the method is deprecated
-   * and we alias it to Page.prototype.emulateMediaType in index.js
-   * which is not checked by DocLint
-   */
-  ['Page', new Set(['emulateMedia'])],
-]);
-
 // All the methods from our EventEmitter that we don't document for each subclass.
 const EVENT_LISTENER_METHODS = new Set([
   'emit',
@@ -226,15 +218,6 @@ function compareDocumentations(actual, expected) {
     const methodDiff = diff(actualMethods, expectedMethods);
 
     for (const methodName of methodDiff.extra) {
-      const nonExistingMethodsForClass = expectedNonExistingMethods.get(
-        className
-      );
-      if (
-        nonExistingMethodsForClass &&
-        nonExistingMethodsForClass.has(methodName)
-      )
-        continue;
-
       errors.push(`Non-existing method found: ${className}.${methodName}()`);
     }