From bb57305f6271d8ec0f8f6f6f2cb5d7d06acf1443 Mon Sep 17 00:00:00 2001 From: TASNEEM KOUSHAR Date: Tue, 22 Jun 2021 21:23:13 +0530 Subject: [PATCH] added comments in class Page (#7345) * fix: modified comment for method product, platform and newPage * fix: added comment for browsercontext, StartCSSCoverage, StartJSCoverage * fix: corrected comments for JSONValue, asElement, evaluateHandle * fix: corrected comments for JSONValue, asElement, evaluateHandle * fix: added comments for some of the method * fix: added proper comments * fix: added comment for some methods in page.ts * fix: rectified the comments * fix: changed some of the comments * fix: added comments for 3 more methods of class page * fix: added comments for 3 more methods of class page * fix: added comments for 5 more methods in class page * fix: removed the extra whitespace * fix: added comments for 5 more method in page class * fix: added comments for 5 more methods in class page * fix: commented 12 more methods in class Page * fix: commented 12 methods in class Page * fix: commented 12 more methods in class Page * fix: commented 12 more methods in class Page * chore: fix typo in connection.spec.js (#7326) recieved -> received * chore: synchronize Bug 1710839: update comment about firefox preference remote.enabled (#7324) * fix: added comments for methods in class page * docs: add download location to the FAQ (#7339) Co-authored-by: Mathias Bynens * fix: added comments * fix: comments added * feat: add page.emulateCPUThrottling (#7343) * fix: added comments Co-authored-by: Jack Franklin Co-authored-by: Ikko Ashimine Co-authored-by: Julian Descottes Co-authored-by: Diego Fernandez Co-authored-by: Mathias Bynens Co-authored-by: Jan Scheffler --- README.md | 23 +++++++- docs/api.md | 22 ++++++++ src/common/Page.ts | 125 +++++++++++++++++++++++++++++++++++++++-- test/emulation.spec.ts | 9 +++ 4 files changed, 172 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d40f06c038669..b82ba75c628f2 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ npm i puppeteer # or "yarn add puppeteer" ``` -Note: When you install Puppeteer, it downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. To skip the download, or to download a different browser, see [Environment variables](https://github.com/puppeteer/puppeteer/blob/v10.0.0/docs/api.md#environment-variables). +Note: When you install Puppeteer, it downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. To skip the download, download into another path, or download a different browser, see [Environment variables](https://github.com/puppeteer/puppeteer/blob/v10.0.0/docs/api.md#environment-variables). ### puppeteer-core @@ -440,6 +440,27 @@ You may find that Puppeteer does not behave as expected when controlling pages t We have a [troubleshooting](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md) guide for various operating systems that lists the required dependencies. +#### Q: Chromium gets downloaded on every `npm ci` run. How can I cache the download? + +The default download path is `node_modules/puppeteer/.local-chromium`. However, you can change that path with the `PUPPETTER_DOWNLOAD_PATH` environment variable. + +Puppeteer uses that variable to resolve the Chromium executable location during launch, so you don’t need to specify `PUPPETEER_EXECUTABLE_PATH` as well. + +For example, if you wish to keep the Chromium download in `~/.npm/chromium`: + +```sh +export PUPPETEER_DOWNLOAD_PATH=~/.npm/chromium +npm ci + +# by default the Chromium executable path is inferred +# from the download path +npm test + +# a new run of npm ci will check for the existence of +# Chromium in ~/.npm/chromium +npm ci +``` + #### Q: How do I try/test a prerelease version of Puppeteer? You can check out this repo or install the latest prerelease from npm: diff --git a/docs/api.md b/docs/api.md index 2e7e35965f58f..9862a0f704a25 100644 --- a/docs/api.md +++ b/docs/api.md @@ -138,6 +138,7 @@ * [page.coverage](#pagecoverage) * [page.deleteCookie(...cookies)](#pagedeletecookiecookies) * [page.emulate(options)](#pageemulateoptions) + * [page.emulateCPUThrottling(factor)](#pageemulatecputhrottlingfactor) * [page.emulateIdleState(overrides)](#pageemulateidlestateoverrides) * [page.emulateMediaFeatures(features)](#pageemulatemediafeaturesfeatures) * [page.emulateMediaType(type)](#pageemulatemediatypetype) @@ -1535,6 +1536,27 @@ const iPhone = puppeteer.devices['iPhone 6']; 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). +#### page.emulateCPUThrottling(factor) + +- `factor` Factor at which the CPU will be throttled (2x, 2.5x. 3x, ...). Passing `null` disables cpu throttling. +- returns: <[Promise]> + +> **NOTE** Real device CPU performance is impacted by many factors that are not trivial to emulate via the Chrome DevTools Protocol / Puppeteer. e.g core count, L1/L2 cache, thermal throttling impacting performance, architecture etc. Simulating CPU performance can be a good guideline, but ideally also verify any numbers you see on a real mobile device. + +```js +const puppeteer = require('puppeteer'); +const slow3G = puppeteer.networkConditions['Slow 3G']; + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.emulateCPUThrottling(2); + await page.goto('https://www.google.com'); + // other actions... + await browser.close(); +})(); +``` + #### page.emulateIdleState(overrides) - `overrides` If not set, clears emulation diff --git a/src/common/Page.ts b/src/common/Page.ts index 3eacafc8830ab..155dd600283fb 100644 --- a/src/common/Page.ts +++ b/src/common/Page.ts @@ -1569,6 +1569,12 @@ export class Page extends EventEmitter { }); } + /** + * + * @returns + * @remarks Shortcut for + * {@link Frame.url | page.mainFrame().url()}. + */ url(): string { return this.mainFrame().url(); } @@ -1642,7 +1648,7 @@ export class Page extends EventEmitter { * * - `referer` : Referer header value. If provided it will take preference * over the referer header value set by - * {@link page.setExtraHTTPHeaders |page.setExtraHTTPHeaders()}. + * {@link Page.setExtraHTTPHeaders |page.setExtraHTTPHeaders()}. * * `page.goto` will throw an error if: * - there's an SSL error (e.g. in case of self-signed certificates). @@ -1858,9 +1864,9 @@ export class Page extends EventEmitter { /** * Emulates given device metrics and user agent. This method is a shortcut for - * calling two methods: {@link page.setUserAgent} and {@link page.setViewport} + * 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 the {@link puppeteer.devices} `page.emulate` will resize + * be obtained via the {@link Puppeteer.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 @@ -1950,6 +1956,16 @@ export class Page extends EventEmitter { }); } + async emulateCPUThrottling(factor: number | null): Promise { + assert( + factor === null || factor >= 1, + 'Throttling rate should be greater or equal to 1' + ); + await this._client.send('Emulation.setCPUThrottlingRate', { + rate: factor !== null ? factor : 1, + }); + } + /** * @param features - `>` Given an array of media feature * objects, emulates CSS media features on the page. Each media feature object @@ -2125,12 +2141,70 @@ export class Page extends EventEmitter { } } + /** + * `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. + * @example + * ```js + * const page = await browser.newPage(); + * await page.setViewport({ + * width: 640, + * height: 480, + * deviceScaleFactor: 1, + * }); + * await page.goto('https://example.com'); + * ``` + * + * @param viewport + * @remarks + * Argument viewport have following properties: + * + * - `width`: page width in pixels. required + * + * - `height`: page height in pixels. required + * + * - `deviceScaleFactor`: Specify device scale factor (can be thought of as + * DPR). Defaults to `1`. + * + * - `isMobile`: Whether the meta viewport tag is taken into account. Defaults + * to `false`. + * + * - `hasTouch`: Specifies if viewport supports touch events. Defaults to `false` + * + * - `isLandScape`: Specifies if viewport is in landscape mode. Defaults to false. + * + * NOTE: in certain cases, setting viewport will reload the page in order to + * set the isMobile or hasTouch properties. + */ async setViewport(viewport: Viewport): Promise { const needsReload = await this._emulationManager.emulateViewport(viewport); this._viewport = viewport; if (needsReload) await this.reload(); } + /** + * @returns + * + * - `width`: page's width in pixels + * + * - `height`: page's height in pixels + * + * - `deviceScalarFactor`: Specify device scale factor (can be though of as + * dpr). Defaults to `1`. + * + * - `isMobile`: Whether the meta viewport tag is taken into account. Defaults + * to `false`. + * + * - `hasTouch`: Specifies if viewport supports touch events. Defaults to + * `false`. + * + * - `isLandScape`: Specifies if viewport is in landscape mode. Defaults to + * `false`. + */ viewport(): Viewport | null { return this._viewport; } @@ -2534,6 +2608,11 @@ export class Page extends EventEmitter { return await helper.readProtocolStream(this._client, result.stream, path); } + /** + * @returns The page's title + * @remarks + * Shortcut for {@link Frame.title | page.mainFrame().title()}. + */ async title(): Promise { return this.mainFrame().title(); } @@ -2570,7 +2649,7 @@ export class Page extends EventEmitter { /** * This method fetches an element with `selector`, scrolls it into view if - * needed, and then uses {@link page.mouse} to click in the center of the + * needed, and then uses {@link Page.mouse} to click in the center of the * element. If there's no element matching `selector`, the method throws an * error. * @remarks Bear in mind that if `click()` triggers a navigation event and @@ -2621,7 +2700,7 @@ export class Page extends EventEmitter { /** * This method fetches an element with `selector`, scrolls it into view if - * needed, and then uses {@link page.mouse} to hover over the center of the element. + * needed, and then uses {@link Page.mouse} to hover over the center of the element. * If there's no element matching `selector`, the method throws an error. * @param selector - A * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector} @@ -2642,7 +2721,7 @@ export class Page extends EventEmitter { * selected. If there's no `