From bbff323edf9e054a2c0a47c785d7febe04f137c4 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Mon, 27 Nov 2023 11:38:42 +0100 Subject: [PATCH] docs: clarify the viewport() behavior (#11442) --- docs/api/puppeteer.browserconnectoptions.md | 14 +++++++------- docs/api/puppeteer.page.md | 2 +- docs/api/puppeteer.page.viewport.md | 4 +++- packages/puppeteer-core/src/api/Page.ts | 7 ++++++- .../puppeteer-core/src/common/ConnectOptions.ts | 2 ++ 5 files changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/api/puppeteer.browserconnectoptions.md b/docs/api/puppeteer.browserconnectoptions.md index 3e1a65b028a..c4a4bcb4536 100644 --- a/docs/api/puppeteer.browserconnectoptions.md +++ b/docs/api/puppeteer.browserconnectoptions.md @@ -14,10 +14,10 @@ export interface BrowserConnectOptions ## Properties -| Property | Modifiers | Type | Description | Default | -| ----------------- | --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------- | -| defaultViewport | optional | [Viewport](./puppeteer.viewport.md) \| null | Sets the viewport for each page. | | -| ignoreHTTPSErrors | optional | boolean | Whether to ignore HTTPS errors during navigation. | false | -| protocolTimeout | optional | number | Timeout setting for individual protocol (CDP) calls. | 180_000 | -| slowMo | optional | number | Slows down Puppeteer operations by the specified amount of milliseconds to aid debugging. | | -| targetFilter | optional | [TargetFilterCallback](./puppeteer.targetfiltercallback.md) | Callback to decide if Puppeteer should connect to a given target or not. | | +| Property | Modifiers | Type | Description | Default | +| ----------------- | --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------- | +| defaultViewport | optional | [Viewport](./puppeteer.viewport.md) \| null | Sets the viewport for each page. | '{width: 800, height: 600}' | +| ignoreHTTPSErrors | optional | boolean | Whether to ignore HTTPS errors during navigation. | false | +| protocolTimeout | optional | number | Timeout setting for individual protocol (CDP) calls. | 180_000 | +| slowMo | optional | number | Slows down Puppeteer operations by the specified amount of milliseconds to aid debugging. | | +| targetFilter | optional | [TargetFilterCallback](./puppeteer.targetfiltercallback.md) | Callback to decide if Puppeteer should connect to a given target or not. | | diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md index dadd9752340..16d9037f39d 100644 --- a/docs/api/puppeteer.page.md +++ b/docs/api/puppeteer.page.md @@ -151,7 +151,7 @@ page.off('request', logRequest); | [title()](./puppeteer.page.title.md) | | The page's title | | [type(selector, text, options)](./puppeteer.page.type.md) | |

Sends a keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use [Keyboard.press()](./puppeteer.keyboard.press.md).

| | [url()](./puppeteer.page.url.md) | | The page's URL. | -| [viewport()](./puppeteer.page.viewport.md) | | Current page viewport settings. | +| [viewport()](./puppeteer.page.viewport.md) | |

Returns the current page viewport settings without checking the actual page viewport.

This is either the viewport set with the previous [Page.setViewport()](./puppeteer.page.setviewport.md) call or the default viewport set via [BrowserConnectOptions.defaultViewport](./puppeteer.browserconnectoptions.defaultviewport.md).

| | [waitForDevicePrompt(options)](./puppeteer.page.waitfordeviceprompt.md) | |

This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.

:::caution

This must be called before the device request is made. It will not return a currently active device prompt.

:::

| | [waitForFileChooser(options)](./puppeteer.page.waitforfilechooser.md) | |

This method is typically coupled with an action that triggers file choosing.

:::caution

This must be called before the file chooser is launched. It will not return a currently active file chooser.

:::

| | [waitForFrame(urlOrPredicate, options)](./puppeteer.page.waitforframe.md) | | Waits for a frame matching the given conditions to appear. | diff --git a/docs/api/puppeteer.page.viewport.md b/docs/api/puppeteer.page.viewport.md index e199324a7fb..87c2180c906 100644 --- a/docs/api/puppeteer.page.viewport.md +++ b/docs/api/puppeteer.page.viewport.md @@ -4,7 +4,9 @@ sidebar_label: Page.viewport # Page.viewport() method -Current page viewport settings. +Returns the current page viewport settings without checking the actual page viewport. + +This is either the viewport set with the previous [Page.setViewport()](./puppeteer.page.setviewport.md) call or the default viewport set via [BrowserConnectOptions.defaultViewport](./puppeteer.browserconnectoptions.defaultviewport.md). #### Signature: diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts index 80597989c42..8684bae7a9b 100644 --- a/packages/puppeteer-core/src/api/Page.ts +++ b/packages/puppeteer-core/src/api/Page.ts @@ -2292,7 +2292,12 @@ export abstract class Page extends EventEmitter { abstract setViewport(viewport: Viewport): Promise; /** - * Current page viewport settings. + * Returns the current page viewport settings without checking the actual page + * viewport. + * + * This is either the viewport set with the previous {@link Page.setViewport} + * call or the default viewport set via + * {@link BrowserConnectOptions.defaultViewport}. */ abstract viewport(): Viewport | null; diff --git a/packages/puppeteer-core/src/common/ConnectOptions.ts b/packages/puppeteer-core/src/common/ConnectOptions.ts index 674df2ba33a..83c5873919a 100644 --- a/packages/puppeteer-core/src/common/ConnectOptions.ts +++ b/packages/puppeteer-core/src/common/ConnectOptions.ts @@ -40,6 +40,8 @@ export interface BrowserConnectOptions { ignoreHTTPSErrors?: boolean; /** * Sets the viewport for each page. + * + * @defaultValue '\{width: 800, height: 600\}' */ defaultViewport?: Viewport | null; /**