Page - Documentation

Constructor

new Page()

Source:

Page.js, line 25

Properties:

Name	Type	Description
`mouse`	Mouse

Extends

EventEmitter

Methods

(async) $(selector) → {Promise.<?ElementHandle>}

Source:

Page.js, line 319

The method runs document.querySelector() within the page.
If no element matches the selector, the return value resolve to null.

Parameters:

Name	Type	Description
`selector`	string	A selector to query page for

Returns:

Type: Promise.<?ElementHandle>

(async) $$(selector) → {Promise.<Array.<ElementHandle>>}

Source:

Page.js, line 332

The method runs document.querySelectorAll() within the page.
If no elements match the selector, the return value resolve to [ ].

Parameters:

Name	Type	Description
`selector`	string	A selector to query page for

Returns:

Type: Promise.<Array.<ElementHandle>>

$$eval(selector, runInPage, …parameter) → {Promise.<Serializable>}

Source:

Page.js, line 432

This method runs Array.from(document.querySelectorAll(selector)) within the page
and passes it as the first argument to runInPage.

Parameters:

Name	Type	Attributes	Description
`selector`	String		A selector to query page for
`runInPage`	function		Function to be evaluated in browser context
`parameter`	Serializable	<repeatable>	Arguments to pass to `runInPage`

Returns:

Promise which resolves to the return value of runInPage

Type: Promise.<Serializable>

$eval(selector, runInPage, …parameter) → {Promise.<Serializable>}

Source:

Page.js, line 402

This method runs document.querySelector() within the page
and passes it as the first argument to runInPage.
If there's no element matching selector, the method throws an error.

Parameters:

Name	Type	Attributes	Description
`selector`	String		A selector to query page for
`runInPage`	function		Function to be evaluated in browser context
`parameter`	Serializable	<repeatable>	Arguments to pass to `runInPage`

Returns:

Promise which resolves to the return value of runInPage

Type: Promise.<Serializable>

(async) addScriptTag(options) → {Promise.<ElementHandle>}

Source:

Page.js, line 601

Adds a <script> tag into the page with the desired url or content

Parameters:

Name Type Description

options

object

Properties

Name	Type	Attributes	Description
`path`	string	<optional>	Path to the JavaScript file to be injected into frame. If path is a relative path, then it is resolved relative to current working directory.
`url`	string	<optional>	URL of a script to be added
`content`	string	<optional>	Raw JavaScript content to be injected into frame

Returns:

which resolves to the added tag when the script's onload fires
or when the script content was injected into frame

Type: Promise.<ElementHandle>

(async) addStyleTag(options) → {Promise.<ElementHandle>}

Source:

Page.js, line 557

Adds a <link rel="stylesheet"> tag into the page with the desired url
or a <style type="text/css"> tag with the content

Parameters:

Name Type Description

options

object

Properties

Name	Type	Attributes	Description
`path`	string	<optional>	Path to the CSS file to be injected into frame. If path is a relative path, then it is resolved relative to current working directory.
`url`	string	<optional>	URL of the tag
`content`	string	<optional>	Raw CSS content to be injected into frame

Returns:

which resolves to the added tag when the stylesheet's onload fires
or when the CSS content was injected into frame

Type: Promise.<ElementHandle>

(async) click(selector, optionsopt) → {Promise}

Source:

Page.js, line 797

This method fetches an element with selector, scrolls it into view if needed,
and then uses page.mouse to click in the center of the element.
If there's no element matching selector, the method throws an error.

Bare in mind that if .click() triggers a navigation event
and there's a separate page.waitForNavigation() promise to be resolved,
you may end up with a race condition that yields unexpected results.

Parameters:

Name Type Attributes Description

selector

string

A selector to search for element to click.
If there are multiple elements satisfying the selector,
the first will be clicked.

options

object

Properties

Name	Type	Attributes	Default	Description
`button`	string	<optional>	`'left'`	`left`, `right`, or `middle`
`clickCount`	number	<optional>	`1`	UIEvent.detail
`delay`	number	<optional>	`0`	Time to wait between `mousedown` and `mouseup` in milliseconds

Returns:

Promise which resolves when the element matching selector is successfully clicked.
The Promise will be rejected if there is no element matching selector.

Type: Promise

(async) close()

Source:

Page.js, line 148

Fires:

Page#event:close

(async) content() → {Promise.<string>}

Source:

Page.js, line 284

Gets the full HTML contents of the page, including the doctype.

Returns:

Type: Promise.<string>

cookies(…urls) → {Promise.<Array.<Object>>}

Source:

Page.js, line 206

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.

Parameters:

Name	Type	Attributes	Description
`urls`	string	<repeatable>

Returns:

Include keys of name, value, domain, path,
expires, httpOnly, secure, session & sameSite.

Type: Promise.<Array.<Object>>

deleteCookie(…cookies) → {Promise}

Source:

Page.js, line 277

Parameters:

Name Type Attributes Description

cookies

object

Properties

Name	Type	Attributes
`name`	string
`url`	string	<optional>
`domain`	string	<optional>
`path`	string	<optional>
`secure`	boolean	<optional>

Returns:

Type: Promise

evaluate(expression, …parameter) → {Promise.<Serializable>}

Source:

Page.js, line 373

If the function passed to the page.evaluate returns a Promise,
then page.evaluate would wait for the promise to resolve and return its value.

Parameters:

Name	Type	Attributes	Description
`expression`	function \| string		Function or Expression to be evaluated in the page context
`parameter`	Serializable	<repeatable>	Arguments to pass to the function

Returns:

Promise which resolves to the value of expression

Type: Promise.<Serializable>

(async) evaluateHandle(expression, …parameter) → {Promise.<ElementHandle>}

Source:

Page.js, line 384

Parameters:

Name	Type	Attributes	Description
`expression`	function \| string		Function or Expression to be evaluated in the page context
`parameter`	Serializable	<repeatable>	Arguments to pass to the function

Returns:

Promise which resolves to the value of expression as in-page Element

Type: Promise.<ElementHandle>

(async) exposeFunction(name, puppeteerFunction) → {Promise}

Source:

Page.js, line 485

The method adds a function called name on the page's window object.

Parameters:

Name	Type	Description
`name`	string	Name of the function on the `window` object
`puppeteerFunction`	function	Callback function which will be called in Puppeteer's context, if the function returns a Promise, it will be awaited. (It survives navigations)

Returns:

Promise which resolves to the return value of puppeteerFunction

Type: Promise

(async) focus(selector) → {Promise}

Source:

Page.js, line 631

This method fetches an element with selector and focuses it.
If there's no element matching selector, the method throws an error.

Parameters:

Name	Type	Description
`selector`	string	A 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.

Type: Promise

goBack(optionsopt) → {Promise}

Source:

Page.js, line 106

Navigate to the previous page in history

Parameters:

Name Type Attributes Description

options

object

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	`30000`	Maximum navigation time in milliseconds, pass 0 to disable timeout.
`waitUntil`	number	<optional>	`'load'`	When to consider navigation succeeded

Returns:

Type: Promise

goForward(optionsopt) → {Promise}

Source:

Page.js, line 123

Navigate to the next page in history

Parameters:

Name Type Attributes Description

options

object

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	`30000`	Maximum navigation time in milliseconds, pass 0 to disable timeout.
`waitUntil`	number	<optional>	`'load'`	When to consider navigation succeeded

Returns:

Type: Promise

goto(urlopt, optionsopt) → {Promise}

Source:

Page.js, line 89

Parameters:

Name Type Attributes Default Description

url

string

'about:blank'

URL to navigate page to.
The url should include scheme, e.g. https://.

options

object

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	`30000`	Maximum navigation time in milliseconds, pass 0 to disable timeout.
`waitUntil`	number	<optional>	`'load'`	When to consider navigation succeeded

Returns:

Type: Promise

(async) hover(selector) → {Promise}

Source:

Page.js, line 766

This method fetches an element with selector, scrolls it into view if needed,
and then uses page.mouse to hover over the center of the element.

If there's no element matching selector, the method throws an error.

Parameters:

Name	Type	Description
`selector`	string	A 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.

Type: Promise

reload(optionsopt) → {Promise}

Source:

Page.js, line 138

Parameters:

Name Type Attributes Description

options

object

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	`30000`	Maximum navigation time in milliseconds, pass 0 to disable timeout.
`waitUntil`	number	<optional>	`'load'`	When to consider navigation succeeded

Returns:

Type: Promise

(async) screenshot(optionsopt) → {Promise.<Buffer>}

Source:

Page.js, line 830

Parameters:

Name Type Attributes Description

options

object

Properties

Name Type Attributes Default Description

type

string

"png"

Specify screenshot type, can be either jpeg or png.

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 current working directory.
If no path is provided, the image won't be saved to the disk.

fullPage

boolean

false

When true, takes a screenshot of the full scrollable page

omitBackground

boolean

false

Hides default white background
and allows capturing screenshots with transparency.

clip

object

An object which specifies clipping region of the page

Properties

Name	Type	Attributes	Description
`x`	number	<optional>	X-coordinate of top-left corner of clip area
`y`	number	<optional>	Y-coordinate of top-left corner of clip area
`width`	number	<optional>	Width of clipping area
`height`	number	<optional>	Height of clipping area

quality

number

The quality of the image, between 0-100.
Not applicable to png images.

Returns:

Promise which resolves to buffer with captured screenshot

Type: Promise.<Buffer>

(async) select(selector, …values) → {Promise.<Array.<string>>}

Source:

Page.js, line 667

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.

Parameters:

Name	Type	Attributes	Description
`selector`	string		A selector to query page for
`values`	string	<repeatable>	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:

Returns an array of option values
that have been successfully selected

Type: Promise.<Array.<string>>

(async) setContent(HTML)

Source:

Page.js, line 302

Parameters:

Name	Type	Description
`HTML`	string	HTML markup to assign to the page

setCookie(…cookies) → {Promise}

Source:

Page.js, line 265

Parameters:

Name Type Attributes Description

cookies

object

Properties

Name	Type	Attributes	Description
`name`	string
`value`	string
`url`	string	<optional>
`domain`	string	<optional>
`path`	string	<optional>
`expires`	number	<optional>	Unix time in seconds
`httpOnly`	boolean	<optional>
`secure`	boolean	<optional>
`sameSite`	string	<optional>	"Strict" or "Lax"

Returns:

Type: Promise

setViewport(viewport) → {Promise}

Source:

Page.js, line 500

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

Parameters:

Name Type Description

viewport

object

Properties

Name	Type	Attributes	Description
`width`	number	<optional>	page width in pixels
`height`	number	<optional>	page height in pixels

Returns:

Type: Promise

(async) title() → {Promise.<string>}

Source:

Page.js, line 72

Returns:

Type: Promise.<string>

(async) type(selector, text, optionsopt) → {Promise}

Source:

Page.js, line 706

Sends a keydown, keypress/input, and keyup event
for each character in the text.

Parameters:

Name Type Attributes Description

selector

string

A selector of an element to type into.
If there are multiple elements satisfying the selector,
the first will be used.

text

string

A text to type into a focused element

options

object

Properties

Name	Type	Attributes	Default	Description
`delay`	number	<optional>	`0`	Time to wait between key presses in milliseconds

Returns:

Type: Promise

url() → {string}

Source:

Page.js, line 45

Returns:

Type: string

(async) viewport() → {Promise.<object>}

Source:

Page.js, line 525

Returns:

Include keys of width, height, deviceScaleFactor,
isMobile, hasTouch & isLandscape

Type: Promise.<object>

waitFor(condition, optionsnullable, …parameteropt) → {Promise}

Source:

Page.js, line 467

Parameters:

Name	Type	Attributes	Description
`condition`	number \| string \| function		A selector, predicate or timeout to wait for
`options`	object	<nullable>
`parameter`	Serializable	<optional> <repeatable>	Arguments to pass to the function

Returns:

Promise which resolves to a success value

Type: Promise

waitForFunction(expression, optionsopt, …parameteropt) → {Promise}

Source:

Page.js, line 453

Parameters:

Name Type Attributes Description

expression

function | string

Function or Expression to be evaluated in the page context

options

object

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	`30000`	Maximum time to wait for in milliseconds, pass 0 to disable timeout.

parameter

Serializable

Arguments to pass to the function

Returns:

Promise which resolves when the function returns a truthy value

Type: Promise

(async) waitForNavigation(optionsopt)

Source:

Page.js, line 53

Parameters:

Name Type Attributes Description

options

object

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	`30000`	Maximum navigation time in milliseconds, pass 0 to disable timeout.

Fires:

Page#event:load

waitForSelector(selector, optionsopt) → {Promise.<ElementHandle>}

Source:

Page.js, line 359

Wait for the selector to appear in page.

If at the moment of calling the method the selector already exists,
the method will return immediately.
If the selector doesn't appear after the timeout milliseconds of waiting,
the function will throw.

Parameters:

Name Type Attributes Description

selector

string

A selector of an element to wait for

options

object

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	`30000`	Maximum time to wait for in milliseconds, pass 0 to disable timeout.

Returns:

Promise which resolves when element specified by selector string is added to DOM

Type: Promise.<ElementHandle>