diff --git a/docs/api.md b/docs/api.md index 954e31550b4..cdd21870f1b 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 00000000000..ca443298b21 --- /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 00000000000..46332f808bd --- /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 00000000000..b64133dfbe3 --- /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 00000000000..36664f783df --- /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 98969e96f72..5efbc184623 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 ae8a3970e1a..740f32d4ee9 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 1f444aa3d4c..ce3fea2d450 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 9d6ba8690e0..400cdfee654 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 5988e324b03..d4c0f098244 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 e1841d642d9..1a44ccc1178 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 50dd9294820..169fb6a8a20 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 aea9d75c868..a6def6b09d2 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 f43ef671511..1bdb92f3d25 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 8cc5a92c7b9..f5ca9fb58cf 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 e452cf72999..19a6c8610e7 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 fc1c7965b27..dcbaa017bf7 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 fb6a75c5392..f4f2c681d03 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 af109010205..e8732650e04 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 22c4cc052d8..2085c0363a8 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 b3f097584f2..1382d0264c8 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 add5c80a860..65ae8f2941b 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 979b0b6aa0a..a43465a5626 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 bec372b30f2..8de3329f1b0 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 5525649d13a..be1079abcfc 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 7dbf5dcb590..4a486d9983a 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 d1d7ca2474c..109f10e48b4 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 6202c7303d4..818d9ed7c81 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 00000000000..75c6b9da6d5 --- /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 00000000000..b5aecfc0409 --- /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 00000000000..f6f304b5768 --- /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 00000000000..2781ca9ac61 --- /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 00000000000..91968a12afb --- /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 0fd724fb022..ad7a077dab8 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); }