thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: add documentation to page.ts (#7355)

Browse Source 
Co-authored-by: Tasneem Koushar <imatasneemkoushar@gmail.com>
This commit is contained in:
Jack Franklin 2021-06-23 09:23:36 +01:00 committed by GitHub
parent 083b297a67
commit edc18b46f9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 605 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

612
src/common/Page.ts
View File

@ -656,11 +656,9 @@ export class Page extends EventEmitter {
/**
* Sets the page's geolocation.
*
* @remarks
* Consider using {@link BrowserContext.overridePermissions} to grant
* NOTE: 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});
@ -724,6 +722,8 @@ export class Page extends EventEmitter {
/**
* @returns The page's main frame.
* @remarks
* Page is guaranteed to have a main frame which persists during navigations.
*/
mainFrame(): Frame {
return this._frameManager.mainFrame();
@ -799,6 +799,7 @@ export class Page extends EventEmitter {
* await browser.close();
* })();
* ```
* NOTE: Enabling request interception disables page caching.
*/
async setRequestInterception(value: boolean): Promise<void> {
return this._frameManager.networkManager().setRequestInterception(value);
@ -824,6 +825,26 @@ export class Page extends EventEmitter {
return this._frameManager.networkManager().setOfflineMode(enabled);
}
/**
* @param networkConditions - Passing `null` disables network condition emulation.
* @example
* ```js
* 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)
*/
emulateNetworkConditions(
networkConditions: NetworkConditions | null
): Promise<void> {
@ -833,6 +854,20 @@ export class Page extends EventEmitter {
}
/**
* This setting will change the default maximum navigation time for the
* following methods and related shortcuts:
*
* - {@link Page.goBack | page.goBack(options)}
*
* - {@link Page.goForward | page.goForward(options)}
*
* - {@link Page.goto | page.goto(url,options)}
*
* - {@link Page.reload | page.reload(options)}
*
* - {@link Page.setContent | page.setContent(html,options)}
*
* - {@link Page.waitForNavigation | page.waitForNavigation(options)}
* @param timeout - Maximum navigation time in milliseconds.
*/
setDefaultNavigationTimeout(timeout: number): void {
@ -925,6 +960,9 @@ export class Page extends EventEmitter {
* given prototype.
*
* @remarks
* Shortcut for
* {@link ExecutionContext.queryObjects |
* page.mainFrame().executionContext().queryObjects(prototypeHandle)}.
*
* @example
*
@ -941,6 +979,8 @@ export class Page extends EventEmitter {
* await mapPrototype.dispose();
* ```
* @param prototypeHandle - a handle to the object prototype.
* @returns Promise which resolves to a handle to an array of objects with
* this prototype.
*/
async queryObjects(prototypeHandle: JSHandle): Promise<JSHandle> {
const context = await this.mainFrame().executionContext();
@ -1160,6 +1200,12 @@ export class Page extends EventEmitter {
}
}
/**
* @example
* ```js
* await page.setCookie(cookieObject1, cookieObject2);
* ```
*/
async setCookie(...cookies: Protocol.Network.CookieParam[]): Promise<void> {
const pageURL = this.url();
const startsWithHTTP = pageURL.startsWith('http');
@ -1211,6 +1257,65 @@ export class Page extends EventEmitter {
return this.mainFrame().addStyleTag(options);
}
/**
* The method adds a function called `name` on the page's `window` object. When
* called, the function executes `puppeteerFunction` in node.js and returns a
* `Promise` which resolves to the return value of `puppeteerFunction`.
*
* If the puppeteerFunction returns a `Promise`, it will be awaited.
*
* NOTE: Functions installed via `page.exposeFunction` survive navigations.
* @param name - Name of the function on the window object
* @param puppeteerFunction - Callback function which will be called in
* Puppeteer's context.
* @example
* An example of adding an `md5` function into the page:
* ```js
* const puppeteer = require('puppeteer');
* const crypto = require('crypto');
*
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* page.on('console', (msg) => console.log(msg.text()));
* await page.exposeFunction('md5', (text) =>
* crypto.createHash('md5').update(text).digest('hex')
* );
* await page.evaluate(async () => {
* // use window.md5 to compute hashes
* const myString = 'PUPPETEER';
* const myHash = await window.md5(myString);
* console.log(`md5 of ${myString} is ${myHash}`);
* });
* await browser.close();
* })();
* ```
* An example of adding a `window.readfile` function into the page:
* ```js
* const puppeteer = require('puppeteer');
* const fs = require('fs');
*
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* page.on('console', (msg) => console.log(msg.text()));
* await page.exposeFunction('readfile', async (filePath) => {
* return new Promise((resolve, reject) => {
* fs.readFile(filePath, 'utf8', (err, text) => {
* if (err) reject(err);
* else resolve(text);
* });
* });
* });
* await page.evaluate(async () => {
* // use window.readfile to read contents of a file
* const content = await window.readfile('/etc/hosts');
* console.log(content);
* });
* await browser.close();
* })();
* ```
*/
async exposeFunction(
name: string,
puppeteerFunction: Function
@ -1239,14 +1344,61 @@ export class Page extends EventEmitter {
return this._frameManager.networkManager().authenticate(credentials);
}
/**
* The extra HTTP headers will be sent with every request the page initiates.
* NOTE: 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.
* @param headers - An object containing additional HTTP headers to be sent
* with every request. All header values must be strings.
* @returns
*/
async setExtraHTTPHeaders(headers: Record<string, string>): Promise<void> {
return this._frameManager.networkManager().setExtraHTTPHeaders(headers);
}
/**
* @param userAgent - Specific user agent to use in this page
* @returns Promise which resolves when the user agent is set.
*/
async setUserAgent(userAgent: string): Promise<void> {
return this._frameManager.networkManager().setUserAgent(userAgent);
}
/**
* @returns Object containing metrics as key/value pairs.
*
* - `Timestamp` : <number> The timestamp when the metrics sample was taken.
*
* - `Documents` : <number> Number of documents in the page.
*
* - `Frames` : <number> Number of frames in the page.
*
* - `JSEventListeners` : <number> Number of events in the page.
*
* - `Nodes` : <number> Number of DOM nodes in the page.
*
* - `LayoutCount` : <number> Total number of full or partial page layout.
*
* - `RecalcStyleCount` : <number> Total number of page style recalculations.
*
* - `LayoutDuration` : <number> Combined durations of all page layouts.
*
* - `RecalcStyleDuration` : <number> Combined duration of all page style
* recalculations.
*
* - `ScriptDuration` : <number> Combined duration of JavaScript execution.
*
* - `TaskDuration` : <number> Combined duration of all tasks performed by the browser.
*
* - `JSHeapUsedSize` : <number> Used JavaScript heap size.
*
* - `JSHeapTotalSize` : <number> Total JavaScript heap size.
* @remarks
* NOTE: All timestamps are in monotonic time: monotonically increasing time
* in seconds since an arbitrary point in the past.
*/
async metrics(): Promise<Metrics> {
const response = await this._client.send('Performance.getMetrics');
return this._buildMetricsObject(response.metrics);
@ -1417,6 +1569,12 @@ export class Page extends EventEmitter {
});
}
/**
*
* @returns
* @remarks Shortcut for
* {@link Frame.url | page.mainFrame().url()}.
*/
url(): string {
return this.mainFrame().url();
}
@ -1425,10 +1583,95 @@ export class Page extends EventEmitter {
return await this._frameManager.mainFrame().content();
}
/**
* @param html - HTML markup to assign to the page.
* @param options - Parameters that has some properties.
* @remarks
* The parameter `options` might have the following options.
*
* - `timeout` : Maximum time in milliseconds for resources to load, defaults
* to 30 seconds, pass `0` to disable timeout. The default value can be
* changed by using the
* {@link Page.setDefaultNavigationTimeout |
* page.setDefaultNavigationTimeout(timeout)}
* or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
* methods.
*
* - `waitUntil`: <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array>
* When to consider setting markup succeeded, defaults to `load`. Given an
* array of event strings, setting content is considered to be successful
* after all events have been fired. Events can be either:<br/>
* - `load` : consider setting content to be finished when the `load` event is
* fired.<br/>
* - `domcontentloaded` : consider setting content to be finished when the
* `DOMContentLoaded` event is fired.<br/>
* - `networkidle0` : consider setting content to be finished when there are no
* more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider setting content to be finished when there are no
* more than 2 network connections for at least `500` ms.
*/
async setContent(html: string, options: WaitForOptions = {}): Promise<void> {
await this._frameManager.mainFrame().setContent(html, options);
}
/**
* @param url - URL to navigate page to. The URL should include scheme, e.g.
* `https://`
* @param options - Navigation Parameter
* @returns Promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect.
* @remarks
* The argument `options` might have the following properties:
*
* - `timeout` : Maximum navigation time in milliseconds, defaults to 30
* seconds, pass 0 to disable timeout. The default value can be changed by
* using the
* {@link Page.setDefaultNavigationTimeout |
* page.setDefaultNavigationTimeout(timeout)}
* or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
* methods.
*
* - `waitUntil`:
* <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array> When to
* consider navigation succeeded, defaults to `load`. Given an array of
* event strings, navigation is considered to be successful after all events
* have been fired. Events can be either:<br/>
* - `load` : consider navigation to be finished when the load event is
* fired.<br/>
* - `domcontentloaded` : consider navigation to be finished when the
* DOMContentLoaded event is fired.<br/>
* - `networkidle0` : consider navigation to be finished when there are no
* more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider navigation to be finished when there are no
* more than 2 network connections for at least `500` ms.
*
* - `referer` : Referer header value. If provided it will take preference
* over the referer header value set by
* {@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).
* - target URL is invalid.
* - the timeout is exceeded during navigation.
* - the remote server does not respond or is unreachable.
* - the main resource failed to load.
*
* `page.goto` will not throw an error when any valid HTTP status code is
* returned by the remote server, including 404 "Not Found" and 500
* "Internal Server Error". The status code for such responses can be
* retrieved by calling response.status().
*
* NOTE: `page.goto` either throws an error or returns a main resource
* response. The only exceptions are navigation to about:blank or navigation
* to the same URL with a different hash, which would succeed and return null.
*
* NOTE: Headless mode doesn't support navigation to a PDF document. See the
* {@link https://bugs.chromium.org/p/chromium/issues/detail?id=761295
* | upstream issue}.
*
* Shortcut for {@link Frame.goto | page.mainFrame().goto(url, options)}.
*/
async goto(
url: string,
options: WaitForOptions & { referer?: string } = {}
@ -1436,6 +1679,35 @@ export class Page extends EventEmitter {
return await this._frameManager.mainFrame().goto(url, options);
}
/**
* @param options - Navigation parameters which might have the following
* properties:
* @returns Promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect.
* @remarks
* The argument `options` might have the following properties:
*
* - `timeout` : Maximum navigation time in milliseconds, defaults to 30
* seconds, pass 0 to disable timeout. The default value can be changed by
* using the
* {@link Page.setDefaultNavigationTimeout |
* page.setDefaultNavigationTimeout(timeout)}
* or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
* methods.
*
* - `waitUntil`: <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array>
* When to consider navigation succeeded, defaults to `load`. Given an array
* of event strings, navigation is considered to be successful after all
* events have been fired. Events can be either:<br/>
* - `load` : consider navigation to be finished when the load event is fired.<br/>
* - `domcontentloaded` : consider navigation to be finished when the
* DOMContentLoaded event is fired.<br/>
* - `networkidle0` : consider navigation to be finished when there are no
* more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider navigation to be finished when there are no
* more than 2 network connections for at least `500` ms.
*/
async reload(options?: WaitForOptions): Promise<HTTPResponse | null> {
const result = await Promise.all<HTTPResponse, void>([
this.waitForNavigation(options),
@ -1503,10 +1775,68 @@ export class Page extends EventEmitter {
);
}
/**
* This method navigate to the previous page in history.
* @param options - Navigation parameters
* @returns Promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect. If can not go back, resolves to `null`.
* @remarks
* The argument `options` might have the following properties:
*
* - `timeout` : Maximum navigation time in milliseconds, defaults to 30
* seconds, pass 0 to disable timeout. The default value can be changed by
* using the
* {@link Page.setDefaultNavigationTimeout
* | page.setDefaultNavigationTimeout(timeout)}
* or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
* methods.
*
* - `waitUntil` : <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array>
* When to consider navigation succeeded, defaults to `load`. Given an array
* of event strings, navigation is considered to be successful after all
* events have been fired. Events can be either:<br/>
* - `load` : consider navigation to be finished when the load event is fired.<br/>
* - `domcontentloaded` : consider navigation to be finished when the
* DOMContentLoaded event is fired.<br/>
* - `networkidle0` : consider navigation to be finished when there are no
* more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider navigation to be finished when there are no
* more than 2 network connections for at least `500` ms.
*/
async goBack(options: WaitForOptions = {}): Promise<HTTPResponse | null> {
return this._go(-1, options);
}
/**
* This method navigate to the next page in history.
* @param options - Navigation Parameter
* @returns Promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect. If can not go forward, resolves to `null`.
* @remarks
* The argument `options` might have the following properties:
*
* - `timeout` : Maximum navigation time in milliseconds, defaults to 30
* seconds, pass 0 to disable timeout. The default value can be changed by
* using the
* {@link Page.setDefaultNavigationTimeout
* | page.setDefaultNavigationTimeout(timeout)}
* or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
* methods.
*
* - `waitUntil`: <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array>
* When to consider navigation succeeded, defaults to `load`. Given an array
* of event strings, navigation is considered to be successful after all
* events have been fired. Events can be either:<br/>
* - `load` : consider navigation to be finished when the load event is fired.<br/>
* - `domcontentloaded` : consider navigation to be finished when the
* DOMContentLoaded event is fired.<br/>
* - `networkidle0` : consider navigation to be finished when there are no
* more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider navigation to be finished when there are no
* more than 2 network connections for at least `500` ms.
*/
async goForward(options: WaitForOptions = {}): Promise<HTTPResponse | null> {
return this._go(+1, options);
}
@ -1534,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
@ -1565,6 +1895,13 @@ export class Page extends EventEmitter {
]);
}
/**
* @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.
*/
async setJavaScriptEnabled(enabled: boolean): Promise<void> {
if (this._javascriptEnabled === enabled) return;
this._javascriptEnabled = enabled;
@ -1573,10 +1910,42 @@ export class Page extends EventEmitter {
});
}
/**
* Toggles bypassing page's Content-Security-Policy.
* @param enabled - sets bypassing of page's Content-Security-Policy.
* @remarks
* NOTE: CSP bypassing happens at the moment of CSP initialization rather than
* evaluation. Usually, this means that `page.setBypassCSP` should be called
* before navigating to the domain.
*/
async setBypassCSP(enabled: boolean): Promise<void> {
await this._client.send('Page.setBypassCSP', { enabled });
}
/**
* @param type - Changes the CSS media type of the page. The only allowed
* values are `screen`, `print` and `null`. Passing `null` disables CSS media
* emulation.
* @example
* ```
* await page.evaluate(() => matchMedia('screen').matches);
* // → true
* await page.evaluate(() => matchMedia('print').matches);
* // → false
*
* await page.emulateMediaType('print');
* await page.evaluate(() => matchMedia('screen').matches);
* // → false
* await page.evaluate(() => matchMedia('print').matches);
* // → true
*
* await page.emulateMediaType(null);
* await page.evaluate(() => matchMedia('screen').matches);
* // → true
* await page.evaluate(() => matchMedia('print').matches);
* // → false
* ```
*/
async emulateMediaType(type?: string): Promise<void> {
assert(
type === 'screen' || type === 'print' || type === null,
@ -1669,6 +2038,12 @@ export class Page extends EventEmitter {
}
}
/**
* @param timezoneId - Changes the timezone of the page. See
* {@link https://source.chromium.org/chromium/chromium/deps/icu.git/+/faee8bc70570192d82d2978a71e2a615788597d1:source/data/misc/metaZones.txt | ICU’s metaZones.txt}
* for a list of supported timezone IDs. Passing
* `null` disables timezone emulation.
*/
async emulateTimezone(timezoneId?: string): Promise<void> {
try {
await this._client.send('Emulation.setTimezoneOverride', {
@ -1766,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;
}
@ -1831,6 +2264,37 @@ export class Page extends EventEmitter {
return this._frameManager.mainFrame().evaluate<T>(pageFunction, ...args);
}
/**
* Adds a function which would be invoked in one of the following scenarios:
*
* - whenever the page is navigated
*
* - whenever the child frame is attached or navigated. In this case, the
* function is invoked in the context of the newly attached frame.
*
* The function is invoked after the document was created but before any of
* its scripts were run. This is useful to amend the JavaScript environment,
* e.g. to seed `Math.random`.
* @param pageFunction - Function to be evaluated in browser context
* @param args - Arguments to pass to `pageFunction`
* @example
* An example of overriding the navigator.languages property before the page loads:
* ```js
* // preload.js
*
* // overwrite the `languages` property to use a custom getter
* Object.defineProperty(navigator, 'languages', {
* get: function () {
* return ['en-US', 'en', 'bn'];
* },
* });
*
* // In your puppeteer script, assuming the preload.js file is
* in same folder of our script
* const preloadFile = fs.readFileSync('./preload.js', 'utf8');
* await page.evaluateOnNewDocument(preloadFile);
* ```
*/
async evaluateOnNewDocument(
pageFunction: Function | string,
...args: unknown[]
@ -1841,10 +2305,54 @@ export class Page extends EventEmitter {
});
}
/**
* Toggles ignoring cache for each request based on the enabled state. By
* default, caching is enabled.
* @param enabled - sets the `enabled` state of cache
*/
async setCacheEnabled(enabled = true): Promise<void> {
await this._frameManager.networkManager().setCacheEnabled(enabled);
}
/**
* @remarks
* Options object which might have the following properties:
*
* - `path` : <string> The file path to save the image to. The screenshot type
* will be inferred from file extension. If `path` is a relative path, then
* it is resolved relative to
* {@link https://nodejs.org/api/process.html#process_process_cwd
* | current working directory}.
* If no path is provided, the image won't be saved to the disk.
*
* - `type` : <string> Specify screenshot type, can be either `jpeg` or `png`.
* Defaults to 'png'.
*
* - `quality` : <number> The quality of the image, between 0-100. Not
* applicable to `png` images.
*
* - `fullPage` : <boolean> When true, takes a screenshot of the full
* scrollable page. Defaults to `false`
*
* - `clip` : <Object> An object which specifies clipping region of the page.
* Should have the following fields:<br/>
* - `x` : <number> x-coordinate of top-left corner of clip area.<br/>
* - `y` : <number> y-coordinate of top-left corner of clip area.<br/>
* - `width` : <number> width of clipping area.<br/>
* - `height` : <number> height of clipping area.
*
* - `omitBackground` : <boolean> Hides default white background and allows
* capturing screenshots with transparency. Defaults to `false`
*
* - `encoding` : <string> The encoding of the image, can be either base64 or
* binary. Defaults to `binary`.
*
*
* NOTE: Screenshots take at least 1/6 second on OS X. See
* {@link https://crbug.com/741689} for discussion.
* @returns Promise which resolves to buffer or a base64 string (depending on
* the value of `encoding`) with captured screenshot.
*/
async screenshot(
options: ScreenshotOptions = {}
): Promise<Buffer | string | void> {
@ -2024,7 +2532,7 @@ export class Page extends EventEmitter {
* Generatees a PDF of the page with the `print` CSS media type.
* @remarks
*
* IMPORTANT: PDF generation is only supported in Chrome headless mode.
* NOTE: PDF generation is only supported in Chrome headless mode.
*
* To generate a PDF with the `screen` media type, call
* {@link Page.emulateMediaType | `page.emulateMediaType('screen')`} before
@ -2100,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();
}
@ -2122,6 +2635,10 @@ export class Page extends EventEmitter {
}
}
/**
* Indicates that the page has been closed.
* @returns
*/
isClosed(): boolean {
return this._closed;
}
@ -2132,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
@ -2164,22 +2681,103 @@ export class Page extends EventEmitter {
return this.mainFrame().click(selector, options);
}
/**
* This method fetches an element with `selector` and focuses it. 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 }
* of an element to focus. If there are multiple elements satisfying the
* selector, the first will be focused.
* @returns Promise which resolves when the element matching selector is
* successfully focused. The promise will be rejected if there is no element
* matching selector.
* @remarks
* Shortcut for {@link Frame.focus | page.mainFrame().focus(selector)}.
*/
focus(selector: string): Promise<void> {
return this.mainFrame().focus(selector);
}
/**
* 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.
* 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 hover. If there are multiple elements satisfying
* the selector, the first will be hovered.
* @returns Promise which resolves when the element matching `selector` is
* successfully hovered. Promise gets rejected if there's no element matching
* `selector`.
* @remarks
* Shortcut for {@link Page.hover | page.mainFrame().hover(selector)}.
*/
hover(selector: string): Promise<void> {
return this.mainFrame().hover(selector);
}
/**
* Triggers a `change` and `input` event once all the provided options have been
* selected. If there's no `<select>` element matching `selector`, the method
* throws an error.
*
* @example
* ```js
* page.select('select#colors', 'blue'); // single selection
* page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
* ```
* @param selector - A {@link https://developer.mozilla.org/en-US/docs/Web/CSS/
* CSS_Selectors | Selector} to query the page for
* @param values - Values of options to select. If the `<select>` has the
* `multiple` attribute, all values are considered, otherwise only the first one
* is taken into account.
* @returns
*
* @remarks
* Shortcut for {@link Frame.select | page.mainFrame().select()}
*/
select(selector: string, ...values: string[]): Promise<string[]> {
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,