diff --git a/docs/api.md b/docs/api.md index 954e31550b4d7..cdd21870f1bff 100644 --- a/docs/api.md +++ b/docs/api.md @@ -170,6 +170,8 @@ * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) * [page.waitForXPath(xpath[, options])](#pagewaitforxpathxpath-options) * [page.workers()](#pageworkers) + * [GeolocationOptions](#geolocationoptions) + * [WaitTimeoutOptions](#waittimeoutoptions) - [class: WebWorker](#class-webworker) * [webWorker.evaluate(pageFunction[, ...args])](#webworkerevaluatepagefunction-args) * [webWorker.evaluateHandle(pageFunction[, ...args])](#webworkerevaluatehandlepagefunction-args) @@ -1900,10 +1902,7 @@ The extra HTTP headers will be sent with every request the page initiates. > **NOTE** page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests. #### page.setGeolocation(options) -- `options` <[Object]> - - `latitude` <[number]> Latitude between -90 and 90. - - `longitude` <[number]> Longitude between -180 and 180. - - `accuracy` <[number]> Optional non-negative accuracy value. +- `options` <[GeolocationOptions](####GeolocationOptions)> - returns: <[Promise]> Sets the page's geolocation. @@ -2077,8 +2076,7 @@ await page.waitFor(selector => !!document.querySelector(selector), {}, selector) Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args). #### page.waitForFileChooser([options]) -- `options` <[Object]> Optional waiting parameters - - `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method. +- `options` <[WaitTimeoutOptions](####WaitTimeoutOptions)> Optional waiting parameters - returns: <[Promise]<[FileChooser]>> A promise that resolves after a page requests a file picker. > **NOTE** In non-headless Chromium, this method results in the native file picker dialog **not showing up** for the user. @@ -2263,6 +2261,15 @@ This method returns all of the dedicated [WebWorkers](https://developer.mozilla. > **NOTE** This does not contain ServiceWorkers +#### GeolocationOptions +- `latitude` <[number]> Latitude between -90 and 90. +- `longitude` <[number]> Longitude between -180 and 180. +- `accuracy` <[number]> Optional non-negative accuracy value. + +#### WaitTimeoutOptions +- `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method. + + ### class: WebWorker The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). diff --git a/new-docs/puppeteer.geolocationoptions.accuracy.md b/new-docs/puppeteer.geolocationoptions.accuracy.md new file mode 100644 index 0000000000000..ca443298b2160 --- /dev/null +++ b/new-docs/puppeteer.geolocationoptions.accuracy.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [GeolocationOptions](./puppeteer.geolocationoptions.md) > [accuracy](./puppeteer.geolocationoptions.accuracy.md) + +## GeolocationOptions.accuracy property + +Optional non-negative accuracy value. + +Signature: + +```typescript +accuracy?: number; +``` diff --git a/new-docs/puppeteer.geolocationoptions.latitude.md b/new-docs/puppeteer.geolocationoptions.latitude.md new file mode 100644 index 0000000000000..46332f808bd6e --- /dev/null +++ b/new-docs/puppeteer.geolocationoptions.latitude.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [GeolocationOptions](./puppeteer.geolocationoptions.md) > [latitude](./puppeteer.geolocationoptions.latitude.md) + +## GeolocationOptions.latitude property + +Longitude between -180 and 180. + +Signature: + +```typescript +latitude: number; +``` diff --git a/new-docs/puppeteer.geolocationoptions.longitude.md b/new-docs/puppeteer.geolocationoptions.longitude.md new file mode 100644 index 0000000000000..b64133dfbe3cd --- /dev/null +++ b/new-docs/puppeteer.geolocationoptions.longitude.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [GeolocationOptions](./puppeteer.geolocationoptions.md) > [longitude](./puppeteer.geolocationoptions.longitude.md) + +## GeolocationOptions.longitude property + +Latitude between -90 and 90. + +Signature: + +```typescript +longitude: number; +``` diff --git a/new-docs/puppeteer.geolocationoptions.md b/new-docs/puppeteer.geolocationoptions.md new file mode 100644 index 0000000000000..36664f783dfc2 --- /dev/null +++ b/new-docs/puppeteer.geolocationoptions.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [GeolocationOptions](./puppeteer.geolocationoptions.md) + +## GeolocationOptions interface + + +Signature: + +```typescript +export interface GeolocationOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [accuracy](./puppeteer.geolocationoptions.accuracy.md) | number | Optional non-negative accuracy value. | +| [latitude](./puppeteer.geolocationoptions.latitude.md) | number | Longitude between -180 and 180. | +| [longitude](./puppeteer.geolocationoptions.longitude.md) | number | Latitude between -90 and 90. | + diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 200dab24ddb8e..b89c091a8e204 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -52,6 +52,7 @@ | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | | [ClickOptions](./puppeteer.clickoptions.md) | | | [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | | +| [GeolocationOptions](./puppeteer.geolocationoptions.md) | | | [JSONObject](./puppeteer.jsonobject.md) | | | [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 Google Inc. All rights reserved.Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | | [Metrics](./puppeteer.metrics.md) | | @@ -59,7 +60,9 @@ | [RemoteAddress](./puppeteer.remoteaddress.md) | | | [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | | [SnapshotOptions](./puppeteer.snapshotoptions.md) | | +| [WaitForOptions](./puppeteer.waitforoptions.md) | | | [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | | +| [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) | | ## Variables diff --git a/new-docs/puppeteer.metrics.md b/new-docs/puppeteer.metrics.md index ae8a3970e1a28..740f32d4ee91c 100644 --- a/new-docs/puppeteer.metrics.md +++ b/new-docs/puppeteer.metrics.md @@ -4,6 +4,7 @@ ## Metrics interface + Signature: ```typescript diff --git a/new-docs/puppeteer.page._.md b/new-docs/puppeteer.page._.md index 1f444aa3d4cbe..ce3fea2d45003 100644 --- a/new-docs/puppeteer.page._.md +++ b/new-docs/puppeteer.page._.md @@ -4,6 +4,8 @@ ## Page.$() method +Runs `document.querySelector` within the page. If no element matches the selector, the return value resolves to `null`. + Signature: ```typescript @@ -14,9 +16,13 @@ $(selector: string): Promise; | Parameter | Type | Description | | --- | --- | --- | -| selector | string | | +| selector | string | A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query page for. | Returns: Promise<[ElementHandle](./puppeteer.elementhandle.md) \| null> +## Remarks + +Shortcut for [Page.mainFrame().$(selector)](./puppeteer.frame._.md). + diff --git a/new-docs/puppeteer.page.browser.md b/new-docs/puppeteer.page.browser.md index 9d6ba8690e023..400cdfee654bc 100644 --- a/new-docs/puppeteer.page.browser.md +++ b/new-docs/puppeteer.page.browser.md @@ -13,3 +13,5 @@ browser(): Browser; [Browser](./puppeteer.browser.md) +The browser this page belongs to. + diff --git a/new-docs/puppeteer.page.browsercontext.md b/new-docs/puppeteer.page.browsercontext.md index 5988e324b039a..d4c0f09824487 100644 --- a/new-docs/puppeteer.page.browsercontext.md +++ b/new-docs/puppeteer.page.browsercontext.md @@ -13,3 +13,5 @@ browserContext(): BrowserContext; [BrowserContext](./puppeteer.browsercontext.md) +The browser context that the page belongs to + diff --git a/new-docs/puppeteer.page.frames.md b/new-docs/puppeteer.page.frames.md index e1841d642d92a..1a44ccc11788e 100644 --- a/new-docs/puppeteer.page.frames.md +++ b/new-docs/puppeteer.page.frames.md @@ -13,3 +13,5 @@ frames(): Frame[]; [Frame](./puppeteer.frame.md)\[\] +An array of all frames attached to the page. + diff --git a/new-docs/puppeteer.page.goback.md b/new-docs/puppeteer.page.goback.md index 50dd929482006..169fb6a8a2039 100644 --- a/new-docs/puppeteer.page.goback.md +++ b/new-docs/puppeteer.page.goback.md @@ -14,7 +14,7 @@ goBack(options?: WaitForOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | WaitForOptions | | +| options | [WaitForOptions](./puppeteer.waitforoptions.md) | | Returns: diff --git a/new-docs/puppeteer.page.goforward.md b/new-docs/puppeteer.page.goforward.md index aea9d75c868bf..a6def6b09d274 100644 --- a/new-docs/puppeteer.page.goforward.md +++ b/new-docs/puppeteer.page.goforward.md @@ -14,7 +14,7 @@ goForward(options?: WaitForOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | WaitForOptions | | +| options | [WaitForOptions](./puppeteer.waitforoptions.md) | | Returns: diff --git a/new-docs/puppeteer.page.goto.md b/new-docs/puppeteer.page.goto.md index f43ef671511ab..1bdb92f3d25cc 100644 --- a/new-docs/puppeteer.page.goto.md +++ b/new-docs/puppeteer.page.goto.md @@ -17,7 +17,7 @@ goto(url: string, options?: WaitForOptions & { | Parameter | Type | Description | | --- | --- | --- | | url | string | | -| options | WaitForOptions & { referer?: string; } | | +| options | [WaitForOptions](./puppeteer.waitforoptions.md) & { referer?: string; } | | Returns: diff --git a/new-docs/puppeteer.page.isjavascriptenabled.md b/new-docs/puppeteer.page.isjavascriptenabled.md index 8cc5a92c7b9e9..f5ca9fb58cfd0 100644 --- a/new-docs/puppeteer.page.isjavascriptenabled.md +++ b/new-docs/puppeteer.page.isjavascriptenabled.md @@ -13,3 +13,5 @@ isJavaScriptEnabled(): boolean; boolean +`true` if the page has JavaScript enabled, `false` otherwise. + diff --git a/new-docs/puppeteer.page.mainframe.md b/new-docs/puppeteer.page.mainframe.md index e452cf7299962..19a6c8610e73a 100644 --- a/new-docs/puppeteer.page.mainframe.md +++ b/new-docs/puppeteer.page.mainframe.md @@ -13,3 +13,5 @@ mainFrame(): Frame; [Frame](./puppeteer.frame.md) +The page's main frame. + diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md index fc1c7965b277c..dcbaa017bf78c 100644 --- a/new-docs/puppeteer.page.md +++ b/new-docs/puppeteer.page.md @@ -70,7 +70,7 @@ page.off('request', logRequest); | Method | Modifiers | Description | | --- | --- | --- | -| [$(selector)](./puppeteer.page._.md) | | | +| [$(selector)](./puppeteer.page._.md) | | Runs document.querySelector within the page. If no element matches the selector, the return value resolves to null. | | [$$(selector)](./puppeteer.page.__.md) | | | | [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) | | | | [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) | | | @@ -117,7 +117,7 @@ page.off('request', logRequest); | [setDefaultNavigationTimeout(timeout)](./puppeteer.page.setdefaultnavigationtimeout.md) | | | | [setDefaultTimeout(timeout)](./puppeteer.page.setdefaulttimeout.md) | | | | [setExtraHTTPHeaders(headers)](./puppeteer.page.setextrahttpheaders.md) | | | -| [setGeolocation(options)](./puppeteer.page.setgeolocation.md) | | | +| [setGeolocation(options)](./puppeteer.page.setgeolocation.md) | | Sets the page's geolocation. | | [setJavaScriptEnabled(enabled)](./puppeteer.page.setjavascriptenabled.md) | | | | [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) | | | | [setRequestInterception(value)](./puppeteer.page.setrequestinterception.md) | | | diff --git a/new-docs/puppeteer.page.reload.md b/new-docs/puppeteer.page.reload.md index fb6a75c53927f..f4f2c681d038b 100644 --- a/new-docs/puppeteer.page.reload.md +++ b/new-docs/puppeteer.page.reload.md @@ -14,7 +14,7 @@ reload(options?: WaitForOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | WaitForOptions | | +| options | [WaitForOptions](./puppeteer.waitforoptions.md) | | Returns: diff --git a/new-docs/puppeteer.page.setcontent.md b/new-docs/puppeteer.page.setcontent.md index af10901020530..e8732650e04e9 100644 --- a/new-docs/puppeteer.page.setcontent.md +++ b/new-docs/puppeteer.page.setcontent.md @@ -15,7 +15,7 @@ setContent(html: string, options?: WaitForOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | | html | string | | -| options | WaitForOptions | | +| options | [WaitForOptions](./puppeteer.waitforoptions.md) | | Returns: diff --git a/new-docs/puppeteer.page.setdefaultnavigationtimeout.md b/new-docs/puppeteer.page.setdefaultnavigationtimeout.md index 22c4cc052d80f..2085c0363a8a9 100644 --- a/new-docs/puppeteer.page.setdefaultnavigationtimeout.md +++ b/new-docs/puppeteer.page.setdefaultnavigationtimeout.md @@ -14,7 +14,7 @@ setDefaultNavigationTimeout(timeout: number): void; | Parameter | Type | Description | | --- | --- | --- | -| timeout | number | | +| timeout | number | Maximum navigation time in milliseconds. | Returns: diff --git a/new-docs/puppeteer.page.setdefaulttimeout.md b/new-docs/puppeteer.page.setdefaulttimeout.md index b3f097584f2a2..1382d0264c800 100644 --- a/new-docs/puppeteer.page.setdefaulttimeout.md +++ b/new-docs/puppeteer.page.setdefaulttimeout.md @@ -14,7 +14,7 @@ setDefaultTimeout(timeout: number): void; | Parameter | Type | Description | | --- | --- | --- | -| timeout | number | | +| timeout | number | Maximum time in milliseconds. | Returns: diff --git a/new-docs/puppeteer.page.setgeolocation.md b/new-docs/puppeteer.page.setgeolocation.md index add5c80a86065..65ae8f2941b0e 100644 --- a/new-docs/puppeteer.page.setgeolocation.md +++ b/new-docs/puppeteer.page.setgeolocation.md @@ -4,23 +4,33 @@ ## Page.setGeolocation() method +Sets the page's geolocation. + Signature: ```typescript -setGeolocation(options: { - longitude: number; - latitude: number; - accuracy?: number; - }): Promise; +setGeolocation(options: GeolocationOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| options | { longitude: number; latitude: number; accuracy?: number; } | | +| options | [GeolocationOptions](./puppeteer.geolocationoptions.md) | | Returns: Promise<void> +## Remarks + +Consider using [BrowserContext.overridePermissions()](./puppeteer.browsercontext.overridepermissions.md) to grant permissions for the page to read its geolocation. + +## Example + + +```js +await page.setGeolocation({latitude: 59.95, longitude: 30.31667}); + +``` + diff --git a/new-docs/puppeteer.page.setofflinemode.md b/new-docs/puppeteer.page.setofflinemode.md index 979b0b6aa0ac5..a43465a56268b 100644 --- a/new-docs/puppeteer.page.setofflinemode.md +++ b/new-docs/puppeteer.page.setofflinemode.md @@ -14,7 +14,7 @@ setOfflineMode(enabled: boolean): Promise; | Parameter | Type | Description | | --- | --- | --- | -| enabled | boolean | | +| enabled | boolean | When true, enables offline mode for the page. | Returns: diff --git a/new-docs/puppeteer.page.setrequestinterception.md b/new-docs/puppeteer.page.setrequestinterception.md index bec372b30f2f1..8de3329f1b06d 100644 --- a/new-docs/puppeteer.page.setrequestinterception.md +++ b/new-docs/puppeteer.page.setrequestinterception.md @@ -14,9 +14,40 @@ setRequestInterception(value: boolean): Promise; | Parameter | Type | Description | | --- | --- | --- | -| value | boolean | | +| value | boolean | Whether to enable request interception. | Returns: Promise<void> +## Remarks + +Activating request interception enables [HTTPRequest.abort()](./puppeteer.httprequest.abort.md), [HTTPRequest.continue()](./puppeteer.httprequest.continue.md) and [HTTPRequest.respond()](./puppeteer.httprequest.respond.md) methods. This provides the capability to modify network requests that are made by a page. + +Once request interception is enabled, every request will stall unless it's continued, responded or aborted. + +\*\*NOTE\*\* Enabling request interception disables page caching. + +## Example + +An example of a naïve request interceptor that aborts all image requests: + +```js +const puppeteer = require('puppeteer'); +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.setRequestInterception(true); + page.on('request', interceptedRequest => { + if (interceptedRequest.url().endsWith('.png') || + interceptedRequest.url().endsWith('.jpg')) + interceptedRequest.abort(); + else + interceptedRequest.continue(); + }); + await page.goto('https://example.com'); + await browser.close(); +})(); + +``` + diff --git a/new-docs/puppeteer.page.target.md b/new-docs/puppeteer.page.target.md index 5525649d13acc..be1079abcfc51 100644 --- a/new-docs/puppeteer.page.target.md +++ b/new-docs/puppeteer.page.target.md @@ -13,3 +13,5 @@ target(): Target; [Target](./puppeteer.target.md) +A target this page was created from. + diff --git a/new-docs/puppeteer.page.waitforfilechooser.md b/new-docs/puppeteer.page.waitforfilechooser.md index 7dbf5dcb5908d..4a486d9983aa6 100644 --- a/new-docs/puppeteer.page.waitforfilechooser.md +++ b/new-docs/puppeteer.page.waitforfilechooser.md @@ -7,18 +7,18 @@ Signature: ```typescript -waitForFileChooser(options?: { - timeout?: number; - }): Promise; +waitForFileChooser(options?: WaitTimeoutOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| options | { timeout?: number; } | | +| options | [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) | Optional waiting parameters | Returns: Promise<[FileChooser](./puppeteer.filechooser.md)> +Resolves after a page requests a file picker. + diff --git a/new-docs/puppeteer.page.waitfornavigation.md b/new-docs/puppeteer.page.waitfornavigation.md index d1d7ca2474c4d..109f10e48b46b 100644 --- a/new-docs/puppeteer.page.waitfornavigation.md +++ b/new-docs/puppeteer.page.waitfornavigation.md @@ -14,7 +14,7 @@ waitForNavigation(options?: WaitForOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | WaitForOptions | | +| options | [WaitForOptions](./puppeteer.waitforoptions.md) | | Returns: diff --git a/new-docs/puppeteer.page.workers.md b/new-docs/puppeteer.page.workers.md index 6202c7303d43d..818d9ed7c8108 100644 --- a/new-docs/puppeteer.page.workers.md +++ b/new-docs/puppeteer.page.workers.md @@ -13,3 +13,5 @@ workers(): WebWorker[]; [WebWorker](./puppeteer.webworker.md)\[\] +all of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) associated with the page. + diff --git a/new-docs/puppeteer.waitforoptions.md b/new-docs/puppeteer.waitforoptions.md new file mode 100644 index 0000000000000..75c6b9da6d5a9 --- /dev/null +++ b/new-docs/puppeteer.waitforoptions.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [WaitForOptions](./puppeteer.waitforoptions.md) + +## WaitForOptions interface + + +Signature: + +```typescript +export interface WaitForOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [timeout](./puppeteer.waitforoptions.timeout.md) | number | Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. | +| [waitUntil](./puppeteer.waitforoptions.waituntil.md) | PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\] | | + diff --git a/new-docs/puppeteer.waitforoptions.timeout.md b/new-docs/puppeteer.waitforoptions.timeout.md new file mode 100644 index 0000000000000..b5aecfc040935 --- /dev/null +++ b/new-docs/puppeteer.waitforoptions.timeout.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [WaitForOptions](./puppeteer.waitforoptions.md) > [timeout](./puppeteer.waitforoptions.timeout.md) + +## WaitForOptions.timeout property + +Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. + +Signature: + +```typescript +timeout?: number; +``` + +## Remarks + +The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) or [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) methods. + diff --git a/new-docs/puppeteer.waitforoptions.waituntil.md b/new-docs/puppeteer.waitforoptions.waituntil.md new file mode 100644 index 0000000000000..f6f304b57682e --- /dev/null +++ b/new-docs/puppeteer.waitforoptions.waituntil.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [WaitForOptions](./puppeteer.waitforoptions.md) > [waitUntil](./puppeteer.waitforoptions.waituntil.md) + +## WaitForOptions.waitUntil property + +Signature: + +```typescript +waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[]; +``` diff --git a/new-docs/puppeteer.waittimeoutoptions.md b/new-docs/puppeteer.waittimeoutoptions.md new file mode 100644 index 0000000000000..2781ca9ac61c8 --- /dev/null +++ b/new-docs/puppeteer.waittimeoutoptions.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) + +## WaitTimeoutOptions interface + + +Signature: + +```typescript +export interface WaitTimeoutOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [timeout](./puppeteer.waittimeoutoptions.timeout.md) | number | Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. | + diff --git a/new-docs/puppeteer.waittimeoutoptions.timeout.md b/new-docs/puppeteer.waittimeoutoptions.timeout.md new file mode 100644 index 0000000000000..91968a12afb20 --- /dev/null +++ b/new-docs/puppeteer.waittimeoutoptions.timeout.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) > [timeout](./puppeteer.waittimeoutoptions.timeout.md) + +## WaitTimeoutOptions.timeout property + +Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. + +Signature: + +```typescript +timeout?: number; +``` + +## Remarks + +The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) method. + diff --git a/src/common/Page.ts b/src/common/Page.ts index 0fd724fb022f1..ad7a077dab82f 100644 --- a/src/common/Page.ts +++ b/src/common/Page.ts @@ -46,6 +46,9 @@ import { EvaluateFn, SerializableOrJSHandle } from './EvalTypes'; const writeFileAsync = promisify(fs.writeFile); +/** + * @public + */ export interface Metrics { Timestamp?: number; Documents?: number; @@ -62,11 +65,56 @@ export interface Metrics { JSHeapTotalSize?: number; } -interface WaitForOptions { +/** + * @public + */ +export interface WaitTimeoutOptions { + /** + * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to + * disable the timeout. + * + * @remarks + * The default value can be changed by using the + * {@link Page.setDefaultTimeout} method. + */ + timeout?: number; +} + +/** + * @public + */ +export interface WaitForOptions { + /** + * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to + * disable the timeout. + * + * @remarks + * The default value can be changed by using the + * {@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout} + * methods. + */ timeout?: number; waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[]; } +/** + * @public + */ +export interface GeolocationOptions { + /** + * Latitude between -90 and 90. + */ + longitude: number; + /** + * Longitude between -180 and 180. + */ + latitude: number; + /** + * Optional non-negative accuracy value. + */ + accuracy?: number; +} + interface MediaFeature { name: string; value: string; @@ -141,6 +189,8 @@ type VisionDeficiency = /** * All the events that a page instance may emit. + * + * @public */ export const enum PageEmittedEvents { /** @@ -243,7 +293,8 @@ export class Page extends EventEmitter { private _viewport: Viewport | null; private _screenshotTaskQueue: ScreenshotTaskQueue; private _workers = new Map(); - // TODO: improve this typedef - it's a function that takes a file chooser or something? + // TODO: improve this typedef - it's a function that takes a file chooser or + // something? private _fileChooserInterceptors = new Set(); private _disconnectPromise?: Promise; @@ -369,12 +420,19 @@ export class Page extends EventEmitter { for (const interceptor of interceptors) interceptor.call(null, fileChooser); } + /** + * @returns `true` if the page has JavaScript enabled, `false` otherwise. + */ public isJavaScriptEnabled(): boolean { return this._javascriptEnabled; } + /** + * @param options - Optional waiting parameters + * @returns Resolves after a page requests a file picker. + */ async waitForFileChooser( - options: { timeout?: number } = {} + options: WaitTimeoutOptions = {} ): Promise { if (!this._fileChooserInterceptors.size) await this._client.send('Page.setInterceptFileChooserDialog', { @@ -397,11 +455,19 @@ export class Page extends EventEmitter { }); } - async setGeolocation(options: { - longitude: number; - latitude: number; - accuracy?: number; - }): Promise { + /** + * Sets the page's geolocation. + * + * @remarks + * Consider using {@link BrowserContext.overridePermissions} to grant + * permissions for the page to read its geolocation. + * + * @example + * ```js + * await page.setGeolocation({latitude: 59.95, longitude: 30.31667}); + * ``` + */ + async setGeolocation(options: GeolocationOptions): Promise { const { longitude, latitude, accuracy = 0 } = options; if (longitude < -180 || longitude > 180) throw new Error( @@ -422,14 +488,23 @@ export class Page extends EventEmitter { }); } + /** + * @returns A target this page was created from. + */ target(): Target { return this._target; } + /** + * @returns The browser this page belongs to. + */ browser(): Browser { return this._target.browser(); } + /** + * @returns The browser context that the page belongs to + */ browserContext(): BrowserContext { return this._target.browserContext(); } @@ -448,6 +523,9 @@ export class Page extends EventEmitter { ); } + /** + * @returns The page's main frame. + */ mainFrame(): Frame { return this._frameManager.mainFrame(); } @@ -472,30 +550,91 @@ export class Page extends EventEmitter { return this._accessibility; } + /** + * @returns An array of all frames attached to the page. + */ frames(): Frame[] { return this._frameManager.frames(); } + /** + * @returns all of the dedicated + * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorkers} + * associated with the page. + */ workers(): WebWorker[] { return Array.from(this._workers.values()); } + /** + * @param value - Whether to enable request interception. + * + * @remarks + * Activating request interception enables {@link HTTPRequest.abort}, + * {@link HTTPRequest.continue} and {@link HTTPRequest.respond} methods. This + * provides the capability to modify network requests that are made by a page. + * + * Once request interception is enabled, every request will stall unless it's + * continued, responded or aborted. + * + * **NOTE** Enabling request interception disables page caching. + * + * @example + * An example of a naïve request interceptor that aborts all image requests: + * ```js + * const puppeteer = require('puppeteer'); + * (async () => { + * const browser = await puppeteer.launch(); + * const page = await browser.newPage(); + * await page.setRequestInterception(true); + * page.on('request', interceptedRequest => { + * if (interceptedRequest.url().endsWith('.png') || + * interceptedRequest.url().endsWith('.jpg')) + * interceptedRequest.abort(); + * else + * interceptedRequest.continue(); + * }); + * await page.goto('https://example.com'); + * await browser.close(); + * })(); + * ``` + */ async setRequestInterception(value: boolean): Promise { return this._frameManager.networkManager().setRequestInterception(value); } + /** + * @param enabled - When `true`, enables offline mode for the page. + */ setOfflineMode(enabled: boolean): Promise { return this._frameManager.networkManager().setOfflineMode(enabled); } + /** + * @param timeout - Maximum navigation time in milliseconds. + */ setDefaultNavigationTimeout(timeout: number): void { this._timeoutSettings.setDefaultNavigationTimeout(timeout); } + /** + * @param timeout - Maximum time in milliseconds. + */ setDefaultTimeout(timeout: number): void { this._timeoutSettings.setDefaultTimeout(timeout); } + /** + * Runs `document.querySelector` within the page. If no element matches the + * selector, the return value resolves to `null`. + * + * @remarks + * Shortcut for {@link Frame.$ | Page.mainFrame().$(selector) }. + * + * @param selector - A + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector} + * to query page for. + */ async $(selector: string): Promise { return this.mainFrame().$(selector); }