diff --git a/docs/api/index.md b/docs/api/index.md index 38272c2ff31..b4af89c9dc6 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -120,19 +120,20 @@ 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) | | -| [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md) | A list of network conditions to be used with [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md). | +| 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) | | +| [errors](./puppeteer.errors.md) | | +| [EVALUATION_SCRIPT_URL](./puppeteer.evaluation_script_url.md) | | +| [executablePath](./puppeteer.executablepath.md) | | +| [KnownDevices](./puppeteer.knowndevices.md) | A list of devices to be used with [Page.emulate()](./puppeteer.page.emulate.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 @@ -142,7 +143,6 @@ sidebar_label: API | [Awaitable](./puppeteer.awaitable.md) | | | [ChromeReleaseChannel](./puppeteer.chromereleasechannel.md) | | | [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. | -| [DevicesMap](./puppeteer.devicesmap.md) | | | [ErrorCode](./puppeteer.errorcode.md) | | | [EvaluateFunc](./puppeteer.evaluatefunc.md) | | | [EventType](./puppeteer.eventtype.md) | | diff --git a/docs/api/puppeteer.device.md b/docs/api/puppeteer.device.md index f284e7b0924..d2ccae149d2 100644 --- a/docs/api/puppeteer.device.md +++ b/docs/api/puppeteer.device.md @@ -12,8 +12,7 @@ export interface Device ## Properties -| Property | Modifiers | Type | Description | -| -------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | -| [name](./puppeteer.device.name.md) | | string | | -| [userAgent](./puppeteer.device.useragent.md) | | string | | -| [viewport](./puppeteer.device.viewport.md) | | { width: number; height: number; deviceScaleFactor: number; isMobile: boolean; hasTouch: boolean; isLandscape: boolean; } | | +| Property | Modifiers | Type | Description | +| -------------------------------------------- | --------- | ----------------------------------- | ----------- | +| [userAgent](./puppeteer.device.useragent.md) | | string | | +| [viewport](./puppeteer.device.viewport.md) | | [Viewport](./puppeteer.viewport.md) | | diff --git a/docs/api/puppeteer.device.name.md b/docs/api/puppeteer.device.name.md deleted file mode 100644 index 467a6bd1a1f..00000000000 --- a/docs/api/puppeteer.device.name.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: Device.name ---- - -# Device.name property - -**Signature:** - -```typescript -interface Device { - name: string; -} -``` diff --git a/docs/api/puppeteer.device.viewport.md b/docs/api/puppeteer.device.viewport.md index 5b3e8bd0488..ba1048132ca 100644 --- a/docs/api/puppeteer.device.viewport.md +++ b/docs/api/puppeteer.device.viewport.md @@ -8,13 +8,6 @@ sidebar_label: Device.viewport ```typescript interface Device { - viewport: { - width: number; - height: number; - deviceScaleFactor: number; - isMobile: boolean; - hasTouch: boolean; - isLandscape: boolean; - }; + viewport: Viewport; } ``` diff --git a/docs/api/puppeteer.devices.md b/docs/api/puppeteer.devices.md index 8b688a4f1b1..72cc7667e1b 100644 --- a/docs/api/puppeteer.devices.md +++ b/docs/api/puppeteer.devices.md @@ -4,26 +4,131 @@ sidebar_label: devices # devices variable -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). +> Warning: This API is now obsolete. +> +> Import [KnownDevices](./puppeteer.knowndevices.md) **Signature:** ```typescript -devices: DevicesMap; -``` - -## Example - -```ts -const puppeteer = require('puppeteer'); -const iPhone = puppeteer.devices['iPhone 6']; - -(async () => { - const browser = await puppeteer.launch(); - const page = await browser.newPage(); - await page.emulate(iPhone); - await page.goto('https://www.google.com'); - // other actions... - await browser.close(); -})(); +devices: Readonly< + Record< + | 'Blackberry PlayBook' + | 'Blackberry PlayBook landscape' + | 'BlackBerry Z30' + | 'BlackBerry Z30 landscape' + | 'Galaxy Note 3' + | 'Galaxy Note 3 landscape' + | 'Galaxy Note II' + | 'Galaxy Note II landscape' + | 'Galaxy S III' + | 'Galaxy S III landscape' + | 'Galaxy S5' + | 'Galaxy S5 landscape' + | 'Galaxy S8' + | 'Galaxy S8 landscape' + | 'Galaxy S9+' + | 'Galaxy S9+ landscape' + | 'Galaxy Tab S4' + | 'Galaxy Tab S4 landscape' + | 'iPad' + | 'iPad landscape' + | 'iPad (gen 6)' + | 'iPad (gen 6) landscape' + | 'iPad (gen 7)' + | 'iPad (gen 7) landscape' + | 'iPad Mini' + | 'iPad Mini landscape' + | 'iPad Pro' + | 'iPad Pro landscape' + | 'iPad Pro 11' + | 'iPad Pro 11 landscape' + | 'iPhone 4' + | 'iPhone 4 landscape' + | 'iPhone 5' + | 'iPhone 5 landscape' + | 'iPhone 6' + | 'iPhone 6 landscape' + | 'iPhone 6 Plus' + | 'iPhone 6 Plus landscape' + | 'iPhone 7' + | 'iPhone 7 landscape' + | 'iPhone 7 Plus' + | 'iPhone 7 Plus landscape' + | 'iPhone 8' + | 'iPhone 8 landscape' + | 'iPhone 8 Plus' + | 'iPhone 8 Plus landscape' + | 'iPhone SE' + | 'iPhone SE landscape' + | 'iPhone X' + | 'iPhone X landscape' + | 'iPhone XR' + | 'iPhone XR landscape' + | 'iPhone 11' + | 'iPhone 11 landscape' + | 'iPhone 11 Pro' + | 'iPhone 11 Pro landscape' + | 'iPhone 11 Pro Max' + | 'iPhone 11 Pro Max landscape' + | 'iPhone 12' + | 'iPhone 12 landscape' + | 'iPhone 12 Pro' + | 'iPhone 12 Pro landscape' + | 'iPhone 12 Pro Max' + | 'iPhone 12 Pro Max landscape' + | 'iPhone 12 Mini' + | 'iPhone 12 Mini landscape' + | 'iPhone 13' + | 'iPhone 13 landscape' + | 'iPhone 13 Pro' + | 'iPhone 13 Pro landscape' + | 'iPhone 13 Pro Max' + | 'iPhone 13 Pro Max landscape' + | 'iPhone 13 Mini' + | 'iPhone 13 Mini landscape' + | 'JioPhone 2' + | 'JioPhone 2 landscape' + | 'Kindle Fire HDX' + | 'Kindle Fire HDX landscape' + | 'LG Optimus L70' + | 'LG Optimus L70 landscape' + | 'Microsoft Lumia 550' + | 'Microsoft Lumia 950' + | 'Microsoft Lumia 950 landscape' + | 'Nexus 10' + | 'Nexus 10 landscape' + | 'Nexus 4' + | 'Nexus 4 landscape' + | 'Nexus 5' + | 'Nexus 5 landscape' + | 'Nexus 5X' + | 'Nexus 5X landscape' + | 'Nexus 6' + | 'Nexus 6 landscape' + | 'Nexus 6P' + | 'Nexus 6P landscape' + | 'Nexus 7' + | 'Nexus 7 landscape' + | 'Nokia Lumia 520' + | 'Nokia Lumia 520 landscape' + | 'Nokia N9' + | 'Nokia N9 landscape' + | 'Pixel 2' + | 'Pixel 2 landscape' + | 'Pixel 2 XL' + | 'Pixel 2 XL landscape' + | 'Pixel 3' + | 'Pixel 3 landscape' + | 'Pixel 4' + | 'Pixel 4 landscape' + | 'Pixel 4a (5G)' + | 'Pixel 4a (5G) landscape' + | 'Pixel 5' + | 'Pixel 5 landscape' + | 'Moto G4' + | 'Moto G4 landscape', + Device + > +>; ``` diff --git a/docs/api/puppeteer.devicesmap.md b/docs/api/puppeteer.devicesmap.md deleted file mode 100644 index ec2b4a3da02..00000000000 --- a/docs/api/puppeteer.devicesmap.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: DevicesMap ---- - -# DevicesMap type - -**Signature:** - -```typescript -export declare type DevicesMap = { - [name: string]: Device; -}; -``` - -**References:** [Device](./puppeteer.device.md) diff --git a/docs/api/puppeteer.knowndevices.md b/docs/api/puppeteer.knowndevices.md new file mode 100644 index 00000000000..018e0b84dad --- /dev/null +++ b/docs/api/puppeteer.knowndevices.md @@ -0,0 +1,148 @@ +--- +sidebar_label: KnownDevices +--- + +# KnownDevices variable + +A list of devices to be used with [Page.emulate()](./puppeteer.page.emulate.md). + +**Signature:** + +```typescript +KnownDevices: Readonly< + Record< + | 'Blackberry PlayBook' + | 'Blackberry PlayBook landscape' + | 'BlackBerry Z30' + | 'BlackBerry Z30 landscape' + | 'Galaxy Note 3' + | 'Galaxy Note 3 landscape' + | 'Galaxy Note II' + | 'Galaxy Note II landscape' + | 'Galaxy S III' + | 'Galaxy S III landscape' + | 'Galaxy S5' + | 'Galaxy S5 landscape' + | 'Galaxy S8' + | 'Galaxy S8 landscape' + | 'Galaxy S9+' + | 'Galaxy S9+ landscape' + | 'Galaxy Tab S4' + | 'Galaxy Tab S4 landscape' + | 'iPad' + | 'iPad landscape' + | 'iPad (gen 6)' + | 'iPad (gen 6) landscape' + | 'iPad (gen 7)' + | 'iPad (gen 7) landscape' + | 'iPad Mini' + | 'iPad Mini landscape' + | 'iPad Pro' + | 'iPad Pro landscape' + | 'iPad Pro 11' + | 'iPad Pro 11 landscape' + | 'iPhone 4' + | 'iPhone 4 landscape' + | 'iPhone 5' + | 'iPhone 5 landscape' + | 'iPhone 6' + | 'iPhone 6 landscape' + | 'iPhone 6 Plus' + | 'iPhone 6 Plus landscape' + | 'iPhone 7' + | 'iPhone 7 landscape' + | 'iPhone 7 Plus' + | 'iPhone 7 Plus landscape' + | 'iPhone 8' + | 'iPhone 8 landscape' + | 'iPhone 8 Plus' + | 'iPhone 8 Plus landscape' + | 'iPhone SE' + | 'iPhone SE landscape' + | 'iPhone X' + | 'iPhone X landscape' + | 'iPhone XR' + | 'iPhone XR landscape' + | 'iPhone 11' + | 'iPhone 11 landscape' + | 'iPhone 11 Pro' + | 'iPhone 11 Pro landscape' + | 'iPhone 11 Pro Max' + | 'iPhone 11 Pro Max landscape' + | 'iPhone 12' + | 'iPhone 12 landscape' + | 'iPhone 12 Pro' + | 'iPhone 12 Pro landscape' + | 'iPhone 12 Pro Max' + | 'iPhone 12 Pro Max landscape' + | 'iPhone 12 Mini' + | 'iPhone 12 Mini landscape' + | 'iPhone 13' + | 'iPhone 13 landscape' + | 'iPhone 13 Pro' + | 'iPhone 13 Pro landscape' + | 'iPhone 13 Pro Max' + | 'iPhone 13 Pro Max landscape' + | 'iPhone 13 Mini' + | 'iPhone 13 Mini landscape' + | 'JioPhone 2' + | 'JioPhone 2 landscape' + | 'Kindle Fire HDX' + | 'Kindle Fire HDX landscape' + | 'LG Optimus L70' + | 'LG Optimus L70 landscape' + | 'Microsoft Lumia 550' + | 'Microsoft Lumia 950' + | 'Microsoft Lumia 950 landscape' + | 'Nexus 10' + | 'Nexus 10 landscape' + | 'Nexus 4' + | 'Nexus 4 landscape' + | 'Nexus 5' + | 'Nexus 5 landscape' + | 'Nexus 5X' + | 'Nexus 5X landscape' + | 'Nexus 6' + | 'Nexus 6 landscape' + | 'Nexus 6P' + | 'Nexus 6P landscape' + | 'Nexus 7' + | 'Nexus 7 landscape' + | 'Nokia Lumia 520' + | 'Nokia Lumia 520 landscape' + | 'Nokia N9' + | 'Nokia N9 landscape' + | 'Pixel 2' + | 'Pixel 2 landscape' + | 'Pixel 2 XL' + | 'Pixel 2 XL landscape' + | 'Pixel 3' + | 'Pixel 3 landscape' + | 'Pixel 4' + | 'Pixel 4 landscape' + | 'Pixel 4a (5G)' + | 'Pixel 4a (5G) landscape' + | 'Pixel 5' + | 'Pixel 5 landscape' + | 'Moto G4' + | 'Moto G4 landscape', + Device + > +>; +``` + +## Example + +```ts +import {KnownDevices} from 'puppeteer'; +const iPhone = KnownDevices['iPhone 6']; + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.emulate(iPhone); + await page.goto('https://www.google.com'); + // other actions... + await browser.close(); +})(); +``` diff --git a/docs/api/puppeteer.page.emulate.md b/docs/api/puppeteer.page.emulate.md index b365ff32c2f..32bf0edd519 100644 --- a/docs/api/puppeteer.page.emulate.md +++ b/docs/api/puppeteer.page.emulate.md @@ -4,21 +4,23 @@ sidebar_label: Page.emulate # Page.emulate() method -Emulates given device metrics and user agent. +Emulates a given device's metrics and user agent. + +To aid emulation, Puppeteer provides a list of known devices that can be via [KnownDevices](./puppeteer.knowndevices.md). **Signature:** ```typescript class Page { - emulate(options: {viewport: Viewport; userAgent: string}): Promise; + emulate(device: Device): Promise; } ``` ## Parameters -| Parameter | Type | Description | -| --------- | --------------------------------------------------------------------- | ----------- | -| options | { viewport: [Viewport](./puppeteer.viewport.md); userAgent: string; } | | +| Parameter | Type | Description | +| --------- | ------------------------------- | ----------- | +| device | [Device](./puppeteer.device.md) | | **Returns:** @@ -26,13 +28,14 @@ Promise<void> ## Remarks -List of all available devices is available in the source code: [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts). +This method will resize the page. A lot of websites don't expect phones to change size, so you should emulate before navigating to the page. ## Example ```ts -const puppeteer = require('puppeteer'); -const iPhone = puppeteer.devices['iPhone 6']; +import {KnownDevices} from 'puppeteer'; +const iPhone = KnownDevices['iPhone 6']; + (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md index 8348a2f59e7..132727b994b 100644 --- a/docs/api/puppeteer.page.md +++ b/docs/api/puppeteer.page.md @@ -95,7 +95,7 @@ page.off('request', logRequest); | [cookies(urls)](./puppeteer.page.cookies.md) | | If no URLs are specified, this method returns cookies for the current page URL. If URLs are specified, only cookies for those URLs are returned. | | [createPDFStream(options)](./puppeteer.page.createpdfstream.md) | | Generates a PDF of the page with the print CSS media type. | | [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) | | | -| [emulate(options)](./puppeteer.page.emulate.md) | | Emulates given device metrics and user agent. | +| [emulate(device)](./puppeteer.page.emulate.md) | |

Emulates a given device's metrics and user agent.

To aid emulation, Puppeteer provides a list of known devices that can be via [KnownDevices](./puppeteer.knowndevices.md).

| | [emulateCPUThrottling(factor)](./puppeteer.page.emulatecputhrottling.md) | | Enables CPU throttling to emulate slow CPUs. | | [emulateIdleState(overrides)](./puppeteer.page.emulateidlestate.md) | | Emulates the idle state. If no arguments set, clears idle state emulation. | | [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | | diff --git a/docs/api/puppeteer.puppeteer.devices.md b/docs/api/puppeteer.puppeteer.devices.md deleted file mode 100644 index 6301dc04c09..00000000000 --- a/docs/api/puppeteer.puppeteer.devices.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: Puppeteer.devices ---- - -# Puppeteer.devices property - -> Warning: This API is now obsolete. -> -> Import directly puppeteer. - -**Signature:** - -```typescript -class Puppeteer { - get devices(): typeof devices; -} -``` - -## Example - -```ts -import {devices} from 'puppeteer'; -``` diff --git a/docs/api/puppeteer.puppeteer.md b/docs/api/puppeteer.puppeteer.md index a9e9c7d70f5..3ede0dcafd8 100644 --- a/docs/api/puppeteer.puppeteer.md +++ b/docs/api/puppeteer.puppeteer.md @@ -18,12 +18,6 @@ export declare class Puppeteer The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Puppeteer` class. -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------- | --------------------- | ---------------------------------------- | ----------- | -| [devices](./puppeteer.puppeteer.devices.md) | readonly | typeof [devices](./puppeteer.devices.md) | | - ## Methods | Method | Modifiers | Description | diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts index 6c45c981cdc..b1dfd6a7268 100644 --- a/packages/puppeteer-core/src/api/Page.ts +++ b/packages/puppeteer-core/src/api/Page.ts @@ -17,9 +17,9 @@ import {Protocol} from 'devtools-protocol'; import type {Readable} from 'stream'; import type {Accessibility} from '../common/Accessibility.js'; -import type {Browser, BrowserContext} from './Browser.js'; import type {ConsoleMessage} from '../common/ConsoleMessage.js'; import type {Coverage} from '../common/Coverage.js'; +import {Device} from '../common/Device.js'; import type {Dialog} from '../common/Dialog.js'; import type {ElementHandle} from '../common/ElementHandle.js'; import {EventEmitter, Handler} from '../common/EventEmitter.js'; @@ -48,6 +48,7 @@ import type {Target} from '../common/Target.js'; import type {Tracing} from '../common/Tracing.js'; import type {EvaluateFunc, HandleFor, NodeFor} from '../common/types.js'; import type {WebWorker} from '../common/WebWorker.js'; +import type {Browser, BrowserContext} from './Browser.js'; /** * @public @@ -1656,20 +1657,25 @@ export class Page extends EventEmitter { } /** - * Emulates given device metrics and user agent. + * Emulates a given device's metrics and user agent. + * + * To aid emulation, Puppeteer provides a list of known devices that can be + * via {@link KnownDevices}. * * @remarks * This method is a shortcut for calling two methods: - * {@link Page.setUserAgent} and {@link Page.setViewport} To aid emulation, - * Puppeteer provides a list of device descriptors that can be obtained via - * {@link devices}. `page.emulate` will resize the page. A lot of websites - * don't expect phones to change size, so you should emulate before navigating - * to the page. + * {@link Page.setUserAgent} and {@link Page.setViewport}. + * + * @remarks + * This method will resize the page. A lot of websites don't expect phones to + * change size, so you should emulate before navigating to the page. + * * @example * * ```ts - * const puppeteer = require('puppeteer'); - * const iPhone = puppeteer.devices['iPhone 6']; + * import {KnownDevices} from 'puppeteer'; + * const iPhone = KnownDevices['iPhone 6']; + * * (async () => { * const browser = await puppeteer.launch(); * const page = await browser.newPage(); @@ -1679,21 +1685,16 @@ export class Page extends EventEmitter { * await browser.close(); * })(); * ``` - * - * @remarks List of all available devices is available in the source code: - * {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts | src/common/DeviceDescriptors.ts}. */ - async emulate(options: { - viewport: Viewport; - userAgent: string; - }): Promise; - async emulate(): Promise { - throw new Error('Not implemented'); + async emulate(device: Device): Promise { + await Promise.all([ + this.setUserAgent(device.userAgent), + this.setViewport(device.viewport), + ]); } /** * @param enabled - Whether or not to enable JavaScript on the page. - * @returns * @remarks * NOTE: changing this value won't affect scripts that have already been run. * It will take full effect on the next navigation. diff --git a/packages/puppeteer-core/src/common/DeviceDescriptors.ts b/packages/puppeteer-core/src/common/Device.ts similarity index 98% rename from packages/puppeteer-core/src/common/DeviceDescriptors.ts rename to packages/puppeteer-core/src/common/Device.ts index 58cd9dde4c9..ddd0447c3a2 100644 --- a/packages/puppeteer-core/src/common/DeviceDescriptors.ts +++ b/packages/puppeteer-core/src/common/Device.ts @@ -14,23 +14,17 @@ * limitations under the License. */ +import {Viewport} from './PuppeteerViewport.js'; + /** * @public */ export interface Device { - name: string; userAgent: string; - viewport: { - width: number; - height: number; - deviceScaleFactor: number; - isMobile: boolean; - hasTouch: boolean; - isLandscape: boolean; - }; + viewport: Viewport; } -const deviceArray: Device[] = [ +const knownDevices = [ { name: 'Blackberry PlayBook', userAgent: @@ -1526,23 +1520,25 @@ const deviceArray: Device[] = [ isLandscape: true, }, }, -]; +] as const; + +const knownDevicesByName = {} as Record< + typeof knownDevices[number]['name'], + Device +>; + +for (const device of knownDevices) { + knownDevicesByName[device.name] = device; +} /** - * @public - */ -export type DevicesMap = { - [name: string]: Device; -}; - -/** - * A list of devices to be used with `page.emulate(options)`. Actual list of devices can be found in {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts | src/common/DeviceDescriptors.ts}. + * A list of devices to be used with {@link Page.emulate}. * * @example * * ```ts - * const puppeteer = require('puppeteer'); - * const iPhone = puppeteer.devices['iPhone 6']; + * import {KnownDevices} from 'puppeteer'; + * const iPhone = KnownDevices['iPhone 6']; * * (async () => { * const browser = await puppeteer.launch(); @@ -1556,10 +1552,11 @@ export type DevicesMap = { * * @public */ -const devices: DevicesMap = {}; +export const KnownDevices = Object.freeze(knownDevicesByName); -for (const device of deviceArray) { - devices[device.name] = device; -} - -export {devices}; +/** + * @deprecated Import {@link KnownDevices} + * + * @public + */ +export const devices = KnownDevices; diff --git a/packages/puppeteer-core/src/common/Page.ts b/packages/puppeteer-core/src/common/Page.ts index 0bfaf7b2157..39ea0fd6850 100644 --- a/packages/puppeteer-core/src/common/Page.ts +++ b/packages/puppeteer-core/src/common/Page.ts @@ -16,6 +16,18 @@ import {Protocol} from 'devtools-protocol'; import type {Readable} from 'stream'; +import type {Browser, BrowserContext} from '../api/Browser.js'; +import { + GeolocationOptions, + MediaFeature, + Metrics, + Page, + PageEmittedEvents, + ScreenshotClip, + ScreenshotOptions, + WaitForOptions, + WaitTimeoutOptions, +} from '../api/Page.js'; import {assert} from '../util/assert.js'; import { createDeferredPromise, @@ -23,7 +35,6 @@ import { } from '../util/DeferredPromise.js'; import {isErrorLike} from '../util/ErrorLike.js'; import {Accessibility} from './Accessibility.js'; -import type {Browser, BrowserContext} from '../api/Browser.js'; import { CDPSession, CDPSessionEmittedEvents, @@ -80,17 +91,6 @@ import { waitWithTimeout, } from './util.js'; import {WebWorker} from './WebWorker.js'; -import { - Page, - PageEmittedEvents, - WaitForOptions, - Metrics, - ScreenshotClip, - ScreenshotOptions, - WaitTimeoutOptions, - GeolocationOptions, - MediaFeature, -} from '../api/Page.js'; /** * @internal @@ -1932,44 +1932,6 @@ export class CDPPage extends Page { await this.#client.send('Page.bringToFront'); } - /** - * Emulates given device metrics and user agent. - * - * @remarks - * This method is a shortcut for calling two methods: - * {@link Page.setUserAgent} and {@link Page.setViewport} To aid emulation, - * Puppeteer provides a list of device descriptors that can be obtained via - * {@link devices}. `page.emulate` will resize the page. A lot of websites - * don't expect phones to change size, so you should emulate before navigating - * to the page. - * @example - * - * ```ts - * const puppeteer = require('puppeteer'); - * const iPhone = puppeteer.devices['iPhone 6']; - * (async () => { - * const browser = await puppeteer.launch(); - * const page = await browser.newPage(); - * await page.emulate(iPhone); - * await page.goto('https://www.google.com'); - * // other actions... - * await browser.close(); - * })(); - * ``` - * - * @remarks List of all available devices is available in the source code: - * {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts | src/common/DeviceDescriptors.ts}. - */ - override async emulate(options: { - viewport: Viewport; - userAgent: string; - }): Promise { - await Promise.all([ - this.setViewport(options.viewport), - this.setUserAgent(options.userAgent), - ]); - } - /** * @param enabled - Whether or not to enable JavaScript on the page. * @returns diff --git a/packages/puppeteer-core/src/common/Puppeteer.ts b/packages/puppeteer-core/src/common/Puppeteer.ts index 1de3249c0dd..ca2eb0299c4 100644 --- a/packages/puppeteer-core/src/common/Puppeteer.ts +++ b/packages/puppeteer-core/src/common/Puppeteer.ts @@ -19,7 +19,6 @@ import { _connectToCDPBrowser, } from './BrowserConnector.js'; import {ConnectionTransport} from './ConnectionTransport.js'; -import {devices} from './DeviceDescriptors.js'; import { clearCustomQueryHandlers, CustomQueryHandler, @@ -85,18 +84,6 @@ export class Puppeteer { return _connectToCDPBrowser(options); } - /** - * @deprecated Import directly puppeteer. - * @example - * - * ```ts - * import {devices} from 'puppeteer'; - * ``` - */ - get devices(): typeof devices { - return devices; - } - /** * @deprecated Import directly puppeteer. * @example diff --git a/packages/puppeteer-core/src/puppeteer-core.ts b/packages/puppeteer-core/src/puppeteer-core.ts index 352118a5688..e9cbb3b17c4 100644 --- a/packages/puppeteer-core/src/puppeteer-core.ts +++ b/packages/puppeteer-core/src/puppeteer-core.ts @@ -15,7 +15,7 @@ */ export {Protocol} from 'devtools-protocol'; -export * from './common/DeviceDescriptors.js'; +export * from './common/Device.js'; export * from './common/Errors.js'; export * from './common/PredefinedNetworkConditions.js'; export * from './common/QueryHandler.js'; diff --git a/packages/puppeteer-core/src/types.ts b/packages/puppeteer-core/src/types.ts index 7788965b8a3..6ee87aed728 100644 --- a/packages/puppeteer-core/src/types.ts +++ b/packages/puppeteer-core/src/types.ts @@ -13,7 +13,7 @@ export * from './common/ConnectionTransport.js'; export * from './common/ConsoleMessage.js'; export * from './common/Coverage.js'; export * from './common/Debug.js'; -export * from './common/DeviceDescriptors.js'; +export * from './common/Device.js'; export * from './common/Dialog.js'; export * from './common/ElementHandle.js'; export * from './common/EmulationManager.js'; diff --git a/packages/puppeteer/src/puppeteer.ts b/packages/puppeteer/src/puppeteer.ts index e7baa1b5582..a0c89a29634 100644 --- a/packages/puppeteer/src/puppeteer.ts +++ b/packages/puppeteer/src/puppeteer.ts @@ -15,7 +15,7 @@ */ export {Protocol} from 'devtools-protocol'; -export * from 'puppeteer-core/internal/common/DeviceDescriptors.js'; +export * from 'puppeteer-core/internal/common/Device.js'; export * from 'puppeteer-core/internal/common/Errors.js'; export * from 'puppeteer-core/internal/common/PredefinedNetworkConditions.js'; export * from 'puppeteer-core/internal/common/QueryHandler.js'; diff --git a/packages/puppeteer/src/types.ts b/packages/puppeteer/src/types.ts index cf8db15ee45..8a4ef1f9c63 100644 --- a/packages/puppeteer/src/types.ts +++ b/packages/puppeteer/src/types.ts @@ -13,7 +13,7 @@ export * from 'puppeteer-core/internal/common/ConnectionTransport.js'; export * from 'puppeteer-core/internal/common/ConsoleMessage.js'; export * from 'puppeteer-core/internal/common/Coverage.js'; export * from 'puppeteer-core/internal/common/Debug.js'; -export * from 'puppeteer-core/internal/common/DeviceDescriptors.js'; +export * from 'puppeteer-core/internal/common/Device.js'; export * from 'puppeteer-core/internal/common/Dialog.js'; export * from 'puppeteer-core/internal/common/ElementHandle.js'; export * from 'puppeteer-core/internal/common/EmulationManager.js'; diff --git a/test/src/click.spec.ts b/test/src/click.spec.ts index b9e7f47a00b..44b65968005 100644 --- a/test/src/click.spec.ts +++ b/test/src/click.spec.ts @@ -15,10 +15,11 @@ */ import expect from 'expect'; +import {KnownDevices} from 'puppeteer'; import { getTestState, - setupTestPageAndContextHooks, setupTestBrowserHooks, + setupTestPageAndContextHooks, } from './mocha-utils.js'; import utils from './utils.js'; @@ -278,9 +279,9 @@ describe('Page.click', function () { }); // @see https://github.com/puppeteer/puppeteer/issues/161 it('should not hang with touch-enabled viewports', async () => { - const {page, puppeteer} = getTestState(); + const {page} = getTestState(); - await page.setViewport(puppeteer.devices['iPhone 6']!.viewport); + await page.setViewport(KnownDevices['iPhone 6'].viewport); await page.mouse.down(); await page.mouse.move(100, 10); await page.mouse.up(); diff --git a/test/src/emulation.spec.ts b/test/src/emulation.spec.ts index 5f5f1419204..8dcc87c79f6 100644 --- a/test/src/emulation.spec.ts +++ b/test/src/emulation.spec.ts @@ -15,25 +15,19 @@ */ import expect from 'expect'; -import {PredefinedNetworkConditions} from 'puppeteer'; -import {Device} from 'puppeteer-core/internal/common/DeviceDescriptors.js'; +import {KnownDevices, PredefinedNetworkConditions} from 'puppeteer'; import { getTestState, setupTestBrowserHooks, setupTestPageAndContextHooks, } from './mocha-utils.js'; +const iPhone = KnownDevices['iPhone 6']; +const iPhoneLandscape = KnownDevices['iPhone 6 landscape']; + describe('Emulation', () => { setupTestBrowserHooks(); setupTestPageAndContextHooks(); - let iPhone!: Device; - let iPhoneLandscape!: Device; - - before(() => { - const {puppeteer} = getTestState(); - iPhone = puppeteer.devices['iPhone 6']!; - iPhoneLandscape = puppeteer.devices['iPhone 6 landscape']!; - }); describe('Page.viewport', function () { it('should get the proper viewport size', async () => { diff --git a/test/src/page.spec.ts b/test/src/page.spec.ts index 0264a5bbe0a..e5700164bf5 100644 --- a/test/src/page.spec.ts +++ b/test/src/page.spec.ts @@ -28,7 +28,7 @@ import { } from './mocha-utils.js'; import utils, {attachFrame, waitEvent} from './utils.js'; import {CDPPage} from 'puppeteer-core/internal/common/Page.js'; -import {TimeoutError} from 'puppeteer'; +import {KnownDevices, TimeoutError} from 'puppeteer'; describe('Page', function () { setupTestBrowserHooks(); @@ -1357,7 +1357,7 @@ describe('Page', function () { expect(request.headers['user-agent']).toBe('foobar'); }); it('should emulate device user-agent', async () => { - const {page, server, puppeteer} = getTestState(); + const {page, server} = getTestState(); await page.goto(server.PREFIX + '/mobile.html'); expect( @@ -1365,7 +1365,7 @@ describe('Page', function () { return navigator.userAgent; }) ).not.toContain('iPhone'); - await page.setUserAgent(puppeteer.devices['iPhone 6']!.userAgent); + await page.setUserAgent(KnownDevices['iPhone 6'].userAgent); expect( await page.evaluate(() => { return navigator.userAgent; diff --git a/test/src/touchscreen.spec.ts b/test/src/touchscreen.spec.ts index bfdfb3bbc5c..be7bf3fcb50 100644 --- a/test/src/touchscreen.spec.ts +++ b/test/src/touchscreen.spec.ts @@ -15,6 +15,7 @@ */ import expect from 'expect'; +import {KnownDevices} from 'puppeteer'; import { getTestState, setupTestBrowserHooks, @@ -26,8 +27,8 @@ describe('Touchscreen', function () { setupTestPageAndContextHooks(); it('should tap the button', async () => { - const {puppeteer, page, server} = getTestState(); - const iPhone = puppeteer.devices['iPhone 6']!; + const {page, server} = getTestState(); + const iPhone = KnownDevices['iPhone 6']!; await page.emulate(iPhone); await page.goto(server.PREFIX + '/input/button.html'); await page.tap('button'); @@ -38,8 +39,8 @@ describe('Touchscreen', function () { ).toBe('Clicked'); }); it('should report touches', async () => { - const {puppeteer, page, server} = getTestState(); - const iPhone = puppeteer.devices['iPhone 6']!; + const {page, server} = getTestState(); + const iPhone = KnownDevices['iPhone 6']!; await page.emulate(iPhone); await page.goto(server.PREFIX + '/input/touches.html'); const button = (await page.$('button'))!;