diff --git a/docs/api.md b/docs/api.md index 954e3155..cdd21870 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 00000000..ca443298 --- /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 00000000..46332f80 --- /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 00000000..b64133df --- /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 00000000..36664f78 --- /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 98969e96..5efbc184 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 ae8a3970..740f32d4 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 1f444aa3..ce3fea2d 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 9d6ba869..400cdfee 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 5988e324..d4c0f098 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 e1841d64..1a44ccc1 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 50dd9294..169fb6a8 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 aea9d75c..a6def6b0 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 f43ef671..1bdb92f3 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 8cc5a92c..f5ca9fb5 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 e452cf72..19a6c861 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 fc1c7965..dcbaa017 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 fb6a75c5..f4f2c681 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 af109010..e8732650 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 22c4cc05..2085c036 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 b3f09758..1382d026 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 add5c80a..65ae8f29 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 979b0b6a..a43465a5 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 bec372b3..8de3329f 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 5525649d..be1079ab 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 7dbf5dcb..4a486d99 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 d1d7ca24..109f10e4 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 6202c730..818d9ed7 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 00000000..75c6b9da --- /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 00000000..b5aecfc0 --- /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 00000000..f6f304b5 --- /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 00000000..2781ca9a --- /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 00000000..91968a12 --- /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 0fd724fb..ad7a077d 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); }