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 <mathias@qiwi.be> * fix: added comments * fix: comments added * feat: add page.emulateCPUThrottling (#7343) * fix: added comments Co-authored-by: Jack Franklin <jacktfranklin@chromium.org> Co-authored-by: Ikko Ashimine <eltociear@gmail.com> Co-authored-by: Julian Descottes <julian.descottes@gmail.com> Co-authored-by: Diego Fernandez <dfernandez79@users.noreply.github.com> Co-authored-by: Mathias Bynens <mathias@qiwi.be> Co-authored-by: Jan Scheffler <janscheffler@chromium.org>
puppeteer · Jun 22, 2021 · bb57305 · bb57305
1 parent ae440f5
commit bb57305
Show file tree

Hide file tree

Showing 4 changed files with 172 additions and 7 deletions.
diff --git 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
@@ -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` <?[number]> 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` <?[Object]> If not set, clears emulation

diff --git 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<void> {
+    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 - `<?Array<Object>>` 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<void> {
     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<string> {
     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 `<select>` element matching `selector`, the method
    * throws an error.
    *
-   * @examples
+   * @example
    * ```js
    * page.select('select#colors', 'blue'); // single selection
    * page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
@@ -2661,10 +2740,44 @@ export class Page extends EventEmitter {
     return this.mainFrame().select(selector, ...values);
   }
 
+  /**
+   * This method fetches an element with `selector`, scrolls it into view if
+   * needed, and then uses {@link Page.touchscreen} to tap in 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}
+   * to search for element to tap. If there are multiple elements satisfying the
+   * selector, the first will be tapped.
+   * @returns
+   * @remarks
+   * Shortcut for {@link Frame.tap | page.mainFrame().tap(selector)}.
+   */
   tap(selector: string): Promise<void> {
     return this.mainFrame().tap(selector);
   }
 
+  /**
+   * Sends a `keydown`, `keypress/input`, and `keyup` event for each character
+   * in the text.
+   *
+   * To press a special key, like `Control` or `ArrowDown`, use {@link Keyboard.press}.
+   * @example
+   * ```
+   * await page.type('#mytextarea', 'Hello');
+   * // Types instantly
+   * await page.type('#mytextarea', 'World', { delay: 100 });
+   * // Types slower, like a user
+   * ```
+   * @param selector - A
+   * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
+   * of an element to type into. If there are multiple elements satisfying the
+   * selector, the first will be used.
+   * @param text - A text to type into a focused element.
+   * @param options - have property `delay` which is the Time to wait between
+   * key presses in milliseconds. Defaults to `0`.
+   * @returns
+   * {@link page.mainFrame().type(selector, text[, options])}
+   */
   type(
     selector: string,
     text: string,

diff --git a/test/emulation.spec.ts b/test/emulation.spec.ts
@@ -408,4 +408,13 @@ describe('Emulation', () => {
       await page.emulateNetworkConditions(null);
     });
   });
+
+  describeFailsFirefox('Page.emulateCPUThrottling', function () {
+    it('should change the CPU throttling rate successfully', async () => {
+      const { page } = getTestState();
+
+      await page.emulateCPUThrottling(100);
+      await page.emulateCPUThrottling(null);
+    });
+  });
 });