chore: make emulate media params be options (#5172)

docs/src/api/class-cdpsession.md

@@ -1,5 +1,5 @@
 # class: CDPSession
-* langs: js, python
+* langs: js,python
 * extends: [EventEmitter]
 
 The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:

docs/src/api/class-page.md

@@ -818,15 +818,17 @@ page.evaluate("matchMedia('(prefers-color-scheme: light)').matches")
 page.evaluate("matchMedia('(prefers-color-scheme: no-preference)').matches")
 ```
 
-### param: Page.emulateMedia.params
+### option: Page.emulateMedia.media
-* langs: js
+- `media` <[null]|"screen"|"print">
-- `params` <[Object]>
+
-  - `media` <[null]|"screen"|"print"> Changes the CSS media type of the page. The only allowed values are
+Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`.
-    `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing
+Passing `null` disables CSS media emulation.
-    `undefined` does not change the emulated value. Optional.
+
-  - `colorScheme` <[null]|"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature,
+### option: Page.emulateMedia.colorScheme
-    supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation.
+- `colorScheme` <[null]|"light"|"dark"|"no-preference">
-    Omitting `colorScheme` or passing `undefined` does not change the emulated value. Optional.
+
+Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing
+`null` disables color scheme emulation.
 
 ## async method: Page.evaluate
 - returns: <[Serializable]>

docs/src/api/python.md

@@ -57,22 +57,6 @@ Script to be evaluated in all pages in the browser context. Optional.
 ### param: Page.selectOption.value = %%-python-select-options-value-%%
 ### param: Page.selectOption.label = %%-python-select-options-label-%%
 
-### param: Page.emulateMedia.params
-* langs: python
-- `media` <[null]|"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.
-Optional.
-
-### param: Page.emulateMedia.params
-* langs: python
-- `colorScheme` <[null]|"light"|"dark"|"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. Optional.
-
 ### option: Page.frame.name
 * langs: python
 - `name` <[string]>

src/client/page.ts

@@ -420,11 +420,11 @@ export class Page extends ChannelOwner<channels.PageChannel, channels.PageInitia
     });
   }
 
-  async emulateMedia(params: { media?: 'screen' | 'print' | null, colorScheme?: 'dark' | 'light' | 'no-preference' | null } = {}) {
+  async emulateMedia(options: { media?: 'screen' | 'print' | null, colorScheme?: 'dark' | 'light' | 'no-preference' | null } = {}) {
     return this._wrapApiCall('page.emulateMedia', async () => {
       await this._channel.emulateMedia({
-        media: params.media === null ? 'null' : params.media,
+        media: options.media === null ? 'null' : options.media,
-        colorScheme: params.colorScheme === null ? 'null' : params.colorScheme,
+        colorScheme: options.colorScheme === null ? 'null' : options.colorScheme,
       });
     });
   }

types/types.d.ts

@@ -1607,21 +1607,20 @@ export interface Page {
    * // → false
    * ```
    * 
-   * @param params 
+   * @param options 
    */
-  emulateMedia(params: {
+  emulateMedia(options?: {
-    /**
-     * 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. Optional.
-     */
-    media?: null|"screen"|"print";
-
     /**
      * 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
+     * `null` disables color scheme emulation.
-     * value. Optional.
      */
     colorScheme?: null|"light"|"dark"|"no-preference";
+
+    /**
+     * Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null`
+     * disables CSS media emulation.
+     */
+    media?: null|"screen"|"print";
   }): Promise<void>;
 
   /**
@@ -2062,7 +2061,7 @@ export interface Page {
    * > NOTE: Generating a pdf is currently only supported in Chromium headless.
    * 
    * `page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call
-   * [page.emulateMedia(params)](https://playwright.dev/docs/api/class-page#pageemulatemediaparams) before calling
+   * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#pageemulatemediaoptions) before calling
    * `page.pdf()`:
    * 
    * > NOTE: By default, `page.pdf()` generates a pdf with modified colors for printing. Use the
@@ -6264,7 +6263,7 @@ export interface BrowserType<Browser> {
 
     /**
      * Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
-     * [page.emulateMedia(params)](https://playwright.dev/docs/api/class-page#pageemulatemediaparams) for more details.
+     * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#pageemulatemediaoptions) for more details.
      * Defaults to '`light`'.
      */
     colorScheme?: "light"|"dark"|"no-preference";
@@ -7076,7 +7075,7 @@ export interface Browser extends EventEmitter {
 
     /**
      * Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
-     * [page.emulateMedia(params)](https://playwright.dev/docs/api/class-page#pageemulatemediaparams) for more details.
+     * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#pageemulatemediaoptions) for more details.
      * Defaults to '`light`'.
      */
     colorScheme?: "light"|"dark"|"no-preference";
@@ -9096,7 +9095,7 @@ export interface BrowserContextOptions {
 
   /**
    * Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
-   * [page.emulateMedia(params)](https://playwright.dev/docs/api/class-page#pageemulatemediaparams) for more details.
+   * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#pageemulatemediaoptions) for more details.
    * Defaults to '`light`'.
    */
   colorScheme?: "light"|"dark"|"no-preference";