diff --git a/docs/api/index.md b/docs/api/index.md index 13251d41..38272c2f 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -120,18 +120,19 @@ sidebar_label: API ## Variables -| Variable | Description | -| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [connect](./puppeteer.connect.md) | | -| [createBrowserFetcher](./puppeteer.createbrowserfetcher.md) | | -| [DEFAULT_INTERCEPT_RESOLUTION_PRIORITY](./puppeteer.default_intercept_resolution_priority.md) | The default cooperative request interception resolution priority | -| [defaultArgs](./puppeteer.defaultargs.md) | | -| [devices](./puppeteer.devices.md) | A list of devices to be used with page.emulate(options). Actual list of devices can be found in [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts). | -| [errors](./puppeteer.errors.md) | | -| [EVALUATION_SCRIPT_URL](./puppeteer.evaluation_script_url.md) | | -| [executablePath](./puppeteer.executablepath.md) | | -| [launch](./puppeteer.launch.md) | | -| [networkConditions](./puppeteer.networkconditions.md) | A list of network conditions to be used with page.emulateNetworkConditions(networkConditions). Actual list of predefined conditions can be found in [src/common/NetworkConditions.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/NetworkConditions.ts). | +| Variable | Description | +| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [connect](./puppeteer.connect.md) | | +| [createBrowserFetcher](./puppeteer.createbrowserfetcher.md) | | +| [DEFAULT_INTERCEPT_RESOLUTION_PRIORITY](./puppeteer.default_intercept_resolution_priority.md) | The default cooperative request interception resolution priority | +| [defaultArgs](./puppeteer.defaultargs.md) | | +| [devices](./puppeteer.devices.md) | A list of devices to be used with page.emulate(options). Actual list of devices can be found in [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts). | +| [errors](./puppeteer.errors.md) | | +| [EVALUATION_SCRIPT_URL](./puppeteer.evaluation_script_url.md) | | +| [executablePath](./puppeteer.executablepath.md) | | +| [launch](./puppeteer.launch.md) | | +| [networkConditions](./puppeteer.networkconditions.md) | | +| [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md) | A list of network conditions to be used with [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md). | ## Type Aliases diff --git a/docs/api/puppeteer.networkconditions.md b/docs/api/puppeteer.networkconditions.md index ec4630bd..2ed13349 100644 --- a/docs/api/puppeteer.networkconditions.md +++ b/docs/api/puppeteer.networkconditions.md @@ -4,7 +4,9 @@ sidebar_label: networkConditions # networkConditions variable -A list of network conditions to be used with `page.emulateNetworkConditions(networkConditions)`. Actual list of predefined conditions can be found in [src/common/NetworkConditions.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/NetworkConditions.ts). +> Warning: This API is now obsolete. +> +> Import [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md). **Signature:** @@ -14,19 +16,3 @@ networkConditions: Readonly<{ 'Fast 3G': NetworkConditions; }>; ``` - -## Example - -```ts -const puppeteer = require('puppeteer'); -const slow3G = puppeteer.networkConditions['Slow 3G']; - -(async () => { - const browser = await puppeteer.launch(); - const page = await browser.newPage(); - await page.emulateNetworkConditions(slow3G); - await page.goto('https://www.google.com'); - // other actions... - await browser.close(); -})(); -``` diff --git a/docs/api/puppeteer.page.emulatenetworkconditions.md b/docs/api/puppeteer.page.emulatenetworkconditions.md index 6729e570..dac0edf0 100644 --- a/docs/api/puppeteer.page.emulatenetworkconditions.md +++ b/docs/api/puppeteer.page.emulatenetworkconditions.md @@ -4,6 +4,10 @@ sidebar_label: Page.emulateNetworkConditions # Page.emulateNetworkConditions() method +This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use [Page.setOfflineMode()](./puppeteer.page.setofflinemode.md). + +A list of predefined network conditions can be used by importing [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md). + **Signature:** ```typescript @@ -24,15 +28,11 @@ class Page { Promise<void> -## Remarks - -NOTE: This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use \[page.setOfflineMode(enabled)\](\#pagesetofflinemodeenabled). - ## Example ```ts -const puppeteer = require('puppeteer'); -const slow3G = puppeteer.networkConditions['Slow 3G']; +import {PredefinedNetworkConditions} from 'puppeteer'; +const slow3G = PredefinedNetworkConditions['Slow 3G']; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md index abfc4da5..8348a2f5 100644 --- a/docs/api/puppeteer.page.md +++ b/docs/api/puppeteer.page.md @@ -100,7 +100,7 @@ page.off('request', logRequest); | [emulateIdleState(overrides)](./puppeteer.page.emulateidlestate.md) | | Emulates the idle state. If no arguments set, clears idle state emulation. | | [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | | | [emulateMediaType(type)](./puppeteer.page.emulatemediatype.md) | | | -| [emulateNetworkConditions(networkConditions)](./puppeteer.page.emulatenetworkconditions.md) | | | +| [emulateNetworkConditions(networkConditions)](./puppeteer.page.emulatenetworkconditions.md) | |

This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use [Page.setOfflineMode()](./puppeteer.page.setofflinemode.md).

A list of predefined network conditions can be used by importing [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md).

| | [emulateTimezone(timezoneId)](./puppeteer.page.emulatetimezone.md) | | | | [emulateVisionDeficiency(type)](./puppeteer.page.emulatevisiondeficiency.md) | | Simulates the given vision deficiency on the page. | | [evaluate(pageFunction, args)](./puppeteer.page.evaluate.md) | |

Evaluates a function in the page's context and returns the result.

If the function passed to page.evaluteHandle returns a Promise, the function will wait for the promise to resolve and return its value.

| @@ -137,7 +137,7 @@ page.off('request', logRequest); | [setExtraHTTPHeaders(headers)](./puppeteer.page.setextrahttpheaders.md) | |

The extra HTTP headers will be sent with every request the page initiates.

:::tip

All HTTP header names are lowercased. (HTTP headers are case-insensitive, so this shouldn’t impact your server code.)

:::

:::note

page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.

:::

| | [setGeolocation(options)](./puppeteer.page.setgeolocation.md) | | Sets the page's geolocation. | | [setJavaScriptEnabled(enabled)](./puppeteer.page.setjavascriptenabled.md) | | | -| [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) | | | +| [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) | |

Sets the network connection to offline.

It does not change the parameters used in [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md)

| | [setRequestInterception(value)](./puppeteer.page.setrequestinterception.md) | |

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; or completed using the browser cache.

Enabling request interception disables page caching.

See the [Request interception guide](https://pptr.dev/next/guides/request-interception) for more details.

| | [setUserAgent(userAgent, userAgentMetadata)](./puppeteer.page.setuseragent.md) | | | | [setViewport(viewport)](./puppeteer.page.setviewport.md) | |

page.setViewport will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport before navigating to the page.

In the case of multiple pages in a single browser, each page can have its own viewport size.

| diff --git a/docs/api/puppeteer.page.setofflinemode.md b/docs/api/puppeteer.page.setofflinemode.md index d706b8de..0a1fd7f9 100644 --- a/docs/api/puppeteer.page.setofflinemode.md +++ b/docs/api/puppeteer.page.setofflinemode.md @@ -4,6 +4,10 @@ sidebar_label: Page.setOfflineMode # Page.setOfflineMode() method +Sets the network connection to offline. + +It does not change the parameters used in [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md) + **Signature:** ```typescript @@ -21,7 +25,3 @@ class Page { **Returns:** Promise<void> - -## Remarks - -NOTE: while this method sets the network connection to offline, it does not change the parameters used in \[page.emulateNetworkConditions(networkConditions)\] (\#pageemulatenetworkconditionsnetworkconditions) diff --git a/docs/api/puppeteer.predefinednetworkconditions.md b/docs/api/puppeteer.predefinednetworkconditions.md new file mode 100644 index 00000000..ec88b6c0 --- /dev/null +++ b/docs/api/puppeteer.predefinednetworkconditions.md @@ -0,0 +1,32 @@ +--- +sidebar_label: PredefinedNetworkConditions +--- + +# PredefinedNetworkConditions variable + +A list of network conditions to be used with [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md). + +**Signature:** + +```typescript +PredefinedNetworkConditions: Readonly<{ + 'Slow 3G': NetworkConditions; + 'Fast 3G': NetworkConditions; +}>; +``` + +## Example + +```ts +import {PredefinedNetworkConditions} from 'puppeteer'; +const slow3G = PredefinedNetworkConditions['Slow 3G']; + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.emulateNetworkConditions(slow3G); + await page.goto('https://www.google.com'); + // other actions... + await browser.close(); +})(); +``` diff --git a/docs/api/puppeteer.puppeteer.md b/docs/api/puppeteer.puppeteer.md index bfc92d79..a9e9c7d7 100644 --- a/docs/api/puppeteer.puppeteer.md +++ b/docs/api/puppeteer.puppeteer.md @@ -20,10 +20,9 @@ The constructor for this class is marked as internal. Third-party code should no ## Properties -| Property | Modifiers | Type | Description | -| --------------------------------------------------------------- | --------------------- | ------------------------------------------------------------ | ----------- | -| [devices](./puppeteer.puppeteer.devices.md) | readonly | typeof [devices](./puppeteer.devices.md) | | -| [networkConditions](./puppeteer.puppeteer.networkconditions.md) | readonly | typeof [networkConditions](./puppeteer.networkconditions.md) | | +| Property | Modifiers | Type | Description | +| ------------------------------------------- | --------------------- | ---------------------------------------- | ----------- | +| [devices](./puppeteer.puppeteer.devices.md) | readonly | typeof [devices](./puppeteer.devices.md) | | ## Methods diff --git a/docs/api/puppeteer.puppeteer.networkconditions.md b/docs/api/puppeteer.puppeteer.networkconditions.md deleted file mode 100644 index c79ba272..00000000 --- a/docs/api/puppeteer.puppeteer.networkconditions.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: Puppeteer.networkConditions ---- - -# Puppeteer.networkConditions property - -> Warning: This API is now obsolete. -> -> Import directly puppeteer. - -**Signature:** - -```typescript -class Puppeteer { - get networkConditions(): typeof networkConditions; -} -``` - -## Example - -```ts -import {networkConditions} from 'puppeteer'; -``` diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts index faccee57..6c45c981 100644 --- a/packages/puppeteer-core/src/api/Page.ts +++ b/packages/puppeteer-core/src/api/Page.ts @@ -675,11 +675,11 @@ export class Page extends EventEmitter { } /** + * Sets the network connection to offline. + * + * It does not change the parameters used in {@link Page.emulateNetworkConditions} + * * @param enabled - When `true`, enables offline mode for the page. - * @remarks - * NOTE: while this method sets the network connection to offline, it does - * not change the parameters used in [page.emulateNetworkConditions(networkConditions)] - * (#pageemulatenetworkconditionsnetworkconditions) */ setOfflineMode(enabled: boolean): Promise; setOfflineMode(): Promise { @@ -687,12 +687,18 @@ export class Page extends EventEmitter { } /** - * @param networkConditions - Passing `null` disables network condition emulation. + * This does not affect WebSockets and WebRTC PeerConnections (see + * https://crbug.com/563644). To set the page offline, you can use + * {@link Page.setOfflineMode}. + * + * A list of predefined network conditions can be used by importing + * {@link PredefinedNetworkConditions}. + * * @example * * ```ts - * const puppeteer = require('puppeteer'); - * const slow3G = puppeteer.networkConditions['Slow 3G']; + * import {PredefinedNetworkConditions} from 'puppeteer'; + * const slow3G = PredefinedNetworkConditions['Slow 3G']; * * (async () => { * const browser = await puppeteer.launch(); @@ -704,10 +710,8 @@ export class Page extends EventEmitter { * })(); * ``` * - * @remarks - * NOTE: This does not affect WebSockets and WebRTC PeerConnections (see - * https://crbug.com/563644). To set the page offline, you can use - * [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled). + * @param networkConditions - Passing `null` disables network condition + * emulation. */ emulateNetworkConditions( networkConditions: NetworkConditions | null diff --git a/packages/puppeteer-core/src/common/Page.ts b/packages/puppeteer-core/src/common/Page.ts index 684aac43..0bfaf7b2 100644 --- a/packages/puppeteer-core/src/common/Page.ts +++ b/packages/puppeteer-core/src/common/Page.ts @@ -589,40 +589,10 @@ export class CDPPage extends Page { return this.#client.send('Input.setInterceptDrags', {enabled}); } - /** - * @param enabled - When `true`, enables offline mode for the page. - * @remarks - * NOTE: while this method sets the network connection to offline, it does - * not change the parameters used in [page.emulateNetworkConditions(networkConditions)] - * (#pageemulatenetworkconditionsnetworkconditions) - */ override setOfflineMode(enabled: boolean): Promise { return this.#frameManager.networkManager.setOfflineMode(enabled); } - /** - * @param networkConditions - Passing `null` disables network condition emulation. - * @example - * - * ```ts - * const puppeteer = require('puppeteer'); - * const slow3G = puppeteer.networkConditions['Slow 3G']; - * - * (async () => { - * const browser = await puppeteer.launch(); - * const page = await browser.newPage(); - * await page.emulateNetworkConditions(slow3G); - * await page.goto('https://www.google.com'); - * // other actions... - * await browser.close(); - * })(); - * ``` - * - * @remarks - * NOTE: This does not affect WebSockets and WebRTC PeerConnections (see - * https://crbug.com/563644). To set the page offline, you can use - * [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled). - */ override emulateNetworkConditions( networkConditions: NetworkConditions | null ): Promise { diff --git a/packages/puppeteer-core/src/common/NetworkConditions.ts b/packages/puppeteer-core/src/common/PredefinedNetworkConditions.ts similarity index 73% rename from packages/puppeteer-core/src/common/NetworkConditions.ts rename to packages/puppeteer-core/src/common/PredefinedNetworkConditions.ts index 786a7323..69ee56ed 100644 --- a/packages/puppeteer-core/src/common/NetworkConditions.ts +++ b/packages/puppeteer-core/src/common/PredefinedNetworkConditions.ts @@ -18,15 +18,13 @@ import {NetworkConditions} from './NetworkManager.js'; /** * A list of network conditions to be used with - * `page.emulateNetworkConditions(networkConditions)`. Actual list of predefined - * conditions can be found in - * {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/NetworkConditions.ts | src/common/NetworkConditions.ts}. + * {@link Page.emulateNetworkConditions}. * * @example * * ```ts - * const puppeteer = require('puppeteer'); - * const slow3G = puppeteer.networkConditions['Slow 3G']; + * import {PredefinedNetworkConditions} from 'puppeteer'; + * const slow3G = PredefinedNetworkConditions['Slow 3G']; * * (async () => { * const browser = await puppeteer.launch(); @@ -40,18 +38,22 @@ import {NetworkConditions} from './NetworkManager.js'; * * @public */ -export const networkConditions: Readonly<{ - 'Slow 3G': NetworkConditions; - 'Fast 3G': NetworkConditions; -}> = Object.freeze({ +export const PredefinedNetworkConditions = Object.freeze({ 'Slow 3G': { download: ((500 * 1000) / 8) * 0.8, upload: ((500 * 1000) / 8) * 0.8, latency: 400 * 5, - }, + } as NetworkConditions, 'Fast 3G': { download: ((1.6 * 1000 * 1000) / 8) * 0.9, upload: ((750 * 1000) / 8) * 0.9, latency: 150 * 3.75, - }, + } as NetworkConditions, }); + +/** + * @deprecated Import {@link PredefinedNetworkConditions}. + * + * @public + */ +export const networkConditions = PredefinedNetworkConditions; diff --git a/packages/puppeteer-core/src/common/Puppeteer.ts b/packages/puppeteer-core/src/common/Puppeteer.ts index 994b5eb3..1de3249c 100644 --- a/packages/puppeteer-core/src/common/Puppeteer.ts +++ b/packages/puppeteer-core/src/common/Puppeteer.ts @@ -20,7 +20,6 @@ import { } from './BrowserConnector.js'; import {ConnectionTransport} from './ConnectionTransport.js'; import {devices} from './DeviceDescriptors.js'; -import {networkConditions} from './NetworkConditions.js'; import { clearCustomQueryHandlers, CustomQueryHandler, @@ -98,18 +97,6 @@ export class Puppeteer { return devices; } - /** - * @deprecated Import directly puppeteer. - * @example - * - * ```ts - * import {networkConditions} from 'puppeteer'; - * ``` - */ - get networkConditions(): typeof networkConditions { - return networkConditions; - } - /** * @deprecated Import directly puppeteer. * @example diff --git a/packages/puppeteer-core/src/puppeteer-core.ts b/packages/puppeteer-core/src/puppeteer-core.ts index fbafa000..352118a5 100644 --- a/packages/puppeteer-core/src/puppeteer-core.ts +++ b/packages/puppeteer-core/src/puppeteer-core.ts @@ -17,7 +17,7 @@ export {Protocol} from 'devtools-protocol'; export * from './common/DeviceDescriptors.js'; export * from './common/Errors.js'; -export * from './common/NetworkConditions.js'; +export * from './common/PredefinedNetworkConditions.js'; export * from './common/QueryHandler.js'; import {rootDirname} from './constants.js'; diff --git a/packages/puppeteer-core/src/types.ts b/packages/puppeteer-core/src/types.ts index 6794b28c..7788965b 100644 --- a/packages/puppeteer-core/src/types.ts +++ b/packages/puppeteer-core/src/types.ts @@ -33,12 +33,12 @@ export * from './common/IsolatedWorld.js'; export * from './common/JSHandle.js'; export * from './common/LazyArg.js'; export * from './common/LifecycleWatcher.js'; -export * from './common/NetworkConditions.js'; export * from './common/NetworkEventManager.js'; export * from './common/NetworkManager.js'; export * from './common/NodeWebSocketTransport.js'; export * from './common/Page.js'; export * from './common/PDFOptions.js'; +export * from './common/PredefinedNetworkConditions.js'; export * from './common/Product.js'; export * from './common/Puppeteer.js'; export * from './common/PuppeteerViewport.js'; diff --git a/packages/puppeteer/src/puppeteer.ts b/packages/puppeteer/src/puppeteer.ts index e931c235..e7baa1b5 100644 --- a/packages/puppeteer/src/puppeteer.ts +++ b/packages/puppeteer/src/puppeteer.ts @@ -17,7 +17,7 @@ export {Protocol} from 'devtools-protocol'; export * from 'puppeteer-core/internal/common/DeviceDescriptors.js'; export * from 'puppeteer-core/internal/common/Errors.js'; -export * from 'puppeteer-core/internal/common/NetworkConditions.js'; +export * from 'puppeteer-core/internal/common/PredefinedNetworkConditions.js'; export * from 'puppeteer-core/internal/common/QueryHandler.js'; export {BrowserFetcher} from 'puppeteer-core/internal/node/BrowserFetcher.js'; export {LaunchOptions} from 'puppeteer-core/internal/node/LaunchOptions.js'; diff --git a/packages/puppeteer/src/types.ts b/packages/puppeteer/src/types.ts index ec2f0a78..cf8db15e 100644 --- a/packages/puppeteer/src/types.ts +++ b/packages/puppeteer/src/types.ts @@ -33,12 +33,12 @@ export * from 'puppeteer-core/internal/common/IsolatedWorld.js'; export * from 'puppeteer-core/internal/common/JSHandle.js'; export * from 'puppeteer-core/internal/common/LazyArg.js'; export * from 'puppeteer-core/internal/common/LifecycleWatcher.js'; -export * from 'puppeteer-core/internal/common/NetworkConditions.js'; export * from 'puppeteer-core/internal/common/NetworkEventManager.js'; export * from 'puppeteer-core/internal/common/NetworkManager.js'; export * from 'puppeteer-core/internal/common/NodeWebSocketTransport.js'; export * from 'puppeteer-core/internal/common/Page.js'; export * from 'puppeteer-core/internal/common/PDFOptions.js'; +export * from 'puppeteer-core/internal/common/PredefinedNetworkConditions.js'; export * from 'puppeteer-core/internal/common/Product.js'; export * from 'puppeteer-core/internal/common/Puppeteer.js'; export * from 'puppeteer-core/internal/common/PuppeteerViewport.js'; diff --git a/test/src/emulation.spec.ts b/test/src/emulation.spec.ts index 45e93110..5f5f1419 100644 --- a/test/src/emulation.spec.ts +++ b/test/src/emulation.spec.ts @@ -15,6 +15,7 @@ */ import expect from 'expect'; +import {PredefinedNetworkConditions} from 'puppeteer'; import {Device} from 'puppeteer-core/internal/common/DeviceDescriptors.js'; import { getTestState, @@ -478,7 +479,7 @@ describe('Emulation', () => { let error!: Error; await page - // @ts-expect-error deliberately passign invalid deficiency + // @ts-expect-error deliberately passing invalid deficiency .emulateVisionDeficiency('invalid') .catch(error_ => { return (error = error_); @@ -489,10 +490,10 @@ describe('Emulation', () => { describe('Page.emulateNetworkConditions', function () { it('should change navigator.connection.effectiveType', async () => { - const {page, puppeteer} = getTestState(); + const {page} = getTestState(); - const slow3G = puppeteer.networkConditions['Slow 3G']!; - const fast3G = puppeteer.networkConditions['Fast 3G']!; + const slow3G = PredefinedNetworkConditions['Slow 3G']!; + const fast3G = PredefinedNetworkConditions['Fast 3G']!; expect( await page.evaluate('window.navigator.connection.effectiveType')