api: make clear the use of null in page.emulateMedia (#3078)

We can pass null to disable emulating particular feature.
This change updates the docs and rpc protocol accordingly.

docs/api.md

@@ -1138,8 +1138,8 @@ await page.dispatchEvent('#source', 'dragstart', { dataTransfer });
 
 #### page.emulateMedia(options)
 - `options` <[Object]>
-  - `media` <"screen"|"print"> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation.
+  - `media` <?"screen"|"print"> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value.
-  - `colorScheme` <"dark"|"light"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`.
+  - `colorScheme` <?"dark"|"light"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value.
 - returns: <[Promise]>
 
 ```js

src/firefox/ffPage.ts

@@ -293,7 +293,8 @@ export class FFPage implements PageDelegate {
   async updateEmulateMedia(): Promise<void> {
     const colorScheme = this._page._state.colorScheme || this._browserContext._options.colorScheme || 'light';
     await this._session.send('Page.setEmulatedMedia', {
-      type: this._page._state.mediaType === null ? undefined : this._page._state.mediaType,
+      // Empty string means reset.
+      type: this._page._state.mediaType === null ? '' : this._page._state.mediaType,
       colorScheme
     });
   }

src/page.ts

@@ -385,9 +385,11 @@ export class Page extends EventEmitter {
     return waitPromise;
   }
 
-  async emulateMedia(options: { media?: types.MediaType, colorScheme?: types.ColorScheme }) {
+  async emulateMedia(options: { media?: types.MediaType | null, colorScheme?: types.ColorScheme | null }) {
-    assert(!options.media || types.mediaTypes.has(options.media), 'media: expected one of (screen|print)');
+    if (options.media !== undefined)
-    assert(!options.colorScheme || types.colorSchemes.has(options.colorScheme), 'colorScheme: expected one of (dark|light|no-preference)');
+      assert(options.media === null || types.mediaTypes.has(options.media), 'media: expected one of (screen|print)');
+    if (options.colorScheme !== undefined)
+      assert(options.colorScheme === null || types.colorSchemes.has(options.colorScheme), 'colorScheme: expected one of (dark|light|no-preference)');
     if (options.media !== undefined)
       this._state.mediaType = options.media;
     if (options.colorScheme !== undefined)

src/rpc/channels.ts

@@ -618,8 +618,8 @@ export type PageCloseParams = {
 };
 export type PageCloseResult = void;
 export type PageEmulateMediaParams = {
-  media?: 'screen' | 'print',
+  media?: 'screen' | 'print' | 'reset',
-  colorScheme?: 'dark' | 'light' | 'no-preference',
+  colorScheme?: 'dark' | 'light' | 'no-preference' | 'reset',
 };
 export type PageEmulateMediaResult = void;
 export type PageExposeBindingParams = {

src/rpc/client/page.ts

@@ -357,9 +357,12 @@ export class Page extends ChannelOwner<PageChannel, PageInitializer> {
     });
   }
 
-  async emulateMedia(options: { media?: types.MediaType, colorScheme?: types.ColorScheme }) {
+  async emulateMedia(options: { media?: types.MediaType | null, colorScheme?: types.ColorScheme | null }) {
     return this._wrapApiCall('page.emulateMedia', async () => {
-      await this._channel.emulateMedia(options);
+      await this._channel.emulateMedia({
+        media: options.media === null ? 'reset' : options.media,
+        colorScheme: options.colorScheme === null ? 'reset' : options.colorScheme,
+      });
     });
   }
 

src/rpc/protocol.pdl

@@ -527,10 +527,14 @@ interface Page
       media?: enum
         screen
         print
+        # Reset emulated value to the system default.
+        reset
       colorScheme?: enum
         dark
         light
         no-preference
+        # Reset emulated value to the system default.
+        reset
 
   command exposeBinding
     parameters

src/rpc/server/pageDispatcher.ts

@@ -20,7 +20,7 @@ import { Frame } from '../../frames';
 import { Request } from '../../network';
 import { Page, Worker } from '../../page';
 import * as types from '../../types';
-import { BindingCallChannel, BindingCallInitializer, ElementHandleChannel, PageChannel, PageInitializer, ResponseChannel, WorkerInitializer, WorkerChannel, JSHandleChannel, Binary, SerializedArgument, PagePdfParams, SerializedError, PageAccessibilitySnapshotResult, SerializedValue } from '../channels';
+import { BindingCallChannel, BindingCallInitializer, ElementHandleChannel, PageChannel, PageInitializer, ResponseChannel, WorkerInitializer, WorkerChannel, JSHandleChannel, Binary, SerializedArgument, PagePdfParams, SerializedError, PageAccessibilitySnapshotResult, SerializedValue, PageEmulateMediaParams } from '../channels';
 import { Dispatcher, DispatcherScope, lookupDispatcher, lookupNullableDispatcher } from './dispatcher';
 import { parseError, serializeError, headersArrayToObject, axNodeToProtocol } from '../serializers';
 import { ConsoleMessageDispatcher } from './consoleMessageDispatcher';
@@ -106,8 +106,11 @@ export class PageDispatcher extends Dispatcher<Page, PageInitializer> implements
     return { response: lookupNullableDispatcher<ResponseDispatcher>(await this._page.goForward(params)) };
   }
 
-  async emulateMedia(params: { media?: 'screen' | 'print', colorScheme?: 'dark' | 'light' | 'no-preference' }): Promise<void> {
+  async emulateMedia(params: PageEmulateMediaParams): Promise<void> {
-    await this._page.emulateMedia(params);
+    await this._page.emulateMedia({
+      media: params.media === 'reset' ? null : params.media,
+      colorScheme: params.colorScheme === 'reset' ? null : params.colorScheme,
+    });
   }
 
   async setViewportSize(params: { viewportSize: types.Size }): Promise<void> {

test/emulation.jest.js

@@ -241,7 +241,7 @@ describe('Page.emulateMedia type', function() {
     await page.emulateMedia({});
     expect(await page.evaluate(() => matchMedia('screen').matches)).toBe(false);
     expect(await page.evaluate(() => matchMedia('print').matches)).toBe(true);
-    await page.emulateMedia({ media: '' });
+    await page.emulateMedia({ media: null });
     expect(await page.evaluate(() => matchMedia('screen').matches)).toBe(true);
     expect(await page.evaluate(() => matchMedia('print').matches)).toBe(false);
   });