Page class

Page provides methods to interact with a single tab or extension background page in the browser.

:::note

One Browser instance might have multiple Page instances.

:::

Signature

export declare abstract class Page extends EventEmitter<PageEvents>

Extends: EventEmitter<PageEvents>

Remarks

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Page class.

Example 1

This example creates a page, navigates it to a URL, and then saves a screenshot:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({path: 'screenshot.png'});
await browser.close();

The Page class extends from Puppeteer's EventEmitter class and will emit various events which are documented in the PageEvent enum.

Example 2

This example logs a message for a single page load event:

page.once('load', () => console.log('Page loaded!'));

To unsubscribe from events use the EventEmitter.off() method:

function logRequest(interceptedRequest) {
  console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.off('request', logRequest);

Properties

Property

Modifiers

Type

Description

<span id="accessibility">accessibility</span>

readonly

Accessibility

The Accessibility class provides methods for inspecting the browser's accessibility tree. The accessibility tree is used by assistive technology such as screen readers or switches.

Remarks:

Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.

Blink - Chrome's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree.

Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree.

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Accessibility class.

<span id="bluetooth">bluetooth</span>

readonly

BluetoothEmulation

Exposes the bluetooth emulation abilities.

Remarks:

Web Bluetooth specification requires the emulated adapters should be isolated per top-level navigable. However, at the moment Chromium's bluetooth emulation implementation is tight to the browser context, not the page. This means the bluetooth emulation exposed from different pages of the same browser context would interfere their states.

<span id="coverage">coverage</span>

readonly

Coverage

The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page.

Remarks:

To output coverage in a form consumable by Istanbul, see puppeteer-to-istanbul.

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Coverage class.

<span id="keyboard">keyboard</span>

readonly

Keyboard

Keyboard provides an api for managing a virtual keyboard. The high level api is Keyboard.type(), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.

Remarks:

For finer control, you can use Keyboard.down(), Keyboard.up(), and Keyboard.sendCharacter() to manually fire events as if they were generated from a real keyboard.

On macOS, keyboard shortcuts like ⌘ A -> Select All do not work. See #1313.

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Keyboard class.

<span id="mouse">mouse</span>

readonly

Mouse

The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.

Remarks:

Every page object has its own Mouse, accessible with Page.mouse.

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Mouse class.

<span id="touchscreen">touchscreen</span>

readonly

Touchscreen

The Touchscreen class exposes touchscreen events.

<span id="tracing">tracing</span>

readonly

Tracing

The Tracing class exposes the tracing audit interface.

Remarks:

You can use tracing.start and tracing.stop to create a trace file which can be opened in Chrome DevTools or timeline viewer.

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Tracing class.

Methods

Method

Modifiers

Description

<span id="_">$(selector)</span>

Finds the first element that matches the selector. If no element matches the selector, the return value resolves to null.

Remarks:

Shortcut for Page.mainFrame().$(selector).

<span id="__">$$(selector, options)</span>

Finds elements on the page that match the selector. If no elements match the selector, the return value resolves to [].

Remarks:

Shortcut for Page.mainFrame().$$(selector).

<span id="__eval">$$eval(selector, pageFunction, args)</span>

This method returns all elements matching the selector and passes the resulting array as the first argument to the pageFunction.

Remarks:

If pageFunction returns a promise $$eval will wait for the promise to resolve and then return its value.

<span id="_eval">$eval(selector, pageFunction, args)</span>

This method finds the first element within the page that matches the selector and passes the result as the first argument to the pageFunction.

Remarks:

If no element is found matching selector, the method will throw an error.

If pageFunction returns a promise $eval will wait for the promise to resolve and then return its value.

<span id="addscripttag">addScriptTag(options)</span>

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

Remarks:

Shortcut for page.mainFrame().addScriptTag(options).

<span id="addstyletag">addStyleTag(options)</span>

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

Shortcut for page.mainFrame().addStyleTag(options).

<span id="addstyletag">addStyleTag(options)</span>

<span id="authenticate">authenticate(credentials)</span>

Provide credentials for HTTP authentication.

:::note

Request interception will be turned on behind the scenes to implement authentication. This might affect performance.

:::

Remarks:

To disable authentication, pass null.

<span id="bringtofront">bringToFront()</span>

Brings page to front (activates tab).

<span id="browser">browser()</span>

Get the browser the page belongs to.

<span id="browsercontext">browserContext()</span>

Get the browser context that the page belongs to.

<span id="captureheapsnapshot">captureHeapSnapshot(options)</span>

Captures a snapshot of the JavaScript heap and writes it to a file.

<span id="click">click(selector, options)</span>

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.

Remarks:

Bear 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. The correct pattern for click and wait for navigation is the following:

const [response] = await Promise.all([
  page.waitForNavigation(waitOptions),
  page.click(selector, clickOptions),
]);

Shortcut for page.mainFrame().click(selector[, options]).

<span id="close">close(options)</span>

<span id="content">content()</span>

The full HTML contents of the page, including the DOCTYPE.

<span id="cookies">cookies(urls)</span>

deprecated

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.

Deprecated:

Page-level cookie API is deprecated. Use Browser.cookies() or BrowserContext.cookies() instead.

<span id="createcdpsession">createCDPSession()</span>

Creates a Chrome Devtools Protocol session attached to the page.

<span id="createpdfstream">createPDFStream(options)</span>

Generates a PDF of the page with the print CSS media type.

Remarks:

To generate a PDF with the screen media type, call `page.emulateMediaType('screen')` before calling page.pdf().

By default, page.pdf() generates a pdf with modified colors for printing. Use the `-webkit-print-color-adjust` property to force rendering of exact colors.

<span id="deletecookie">deleteCookie(cookies)</span>

deprecated

Deprecated:

Page-level cookie API is deprecated. Use Browser.deleteCookie(), BrowserContext.deleteCookie(), Browser.deleteMatchingCookies() or BrowserContext.deleteMatchingCookies() instead.

<span id="emulate">emulate(device)</span>

Emulates a given device's metrics and user agent.

To aid emulation, Puppeteer provides a list of known devices that can be via KnownDevices.

Remarks:

This method is a shortcut for calling two methods: Page.setUserAgent() and Page.setViewport().

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.

<span id="emulatecputhrottling">emulateCPUThrottling(factor)</span>

Enables CPU throttling to emulate slow CPUs.

<span id="emulatefocusedpage">emulateFocusedPage(enabled)</span>

Emulates focus state of the page.

<span id="emulateidlestate">emulateIdleState(overrides)</span>

Emulates the idle state. If no arguments set, clears idle state emulation.

<span id="emulatemediafeatures">emulateMediaFeatures(features)</span>

<span id="emulatemediatype">emulateMediaType(type)</span>

<span id="emulatenetworkconditions">emulateNetworkConditions(networkConditions)</span>

This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use Page.setOfflineMode().

A list of predefined network conditions can be used by importing PredefinedNetworkConditions.

<span id="emulatetimezone">emulateTimezone(timezoneId)</span>

<span id="emulatevisiondeficiency">emulateVisionDeficiency(type)</span>

Simulates the given vision deficiency on the page.

<span id="evaluate">evaluate(pageFunction, args)</span>

Evaluates a function in the page's context and returns the result.

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

<span id="evaluatehandle">evaluateHandle(pageFunction, args)</span>

Remarks:

The only difference between page.evaluate and page.evaluateHandle is that evaluateHandle will return the value wrapped in an in-page object.

If the function passed to page.evaluateHandle returns a Promise, the function will wait for the promise to resolve and return its value.

You can pass a string instead of a function (although functions are recommended as they are easier to debug and use with TypeScript):

<span id="evaluateonnewdocument">evaluateOnNewDocument(pageFunction, args)</span>

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.

<span id="exposefunction">exposeFunction(name, pptrFunction)</span>

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.

:::

<span id="focus">focus(selector)</span>

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

Remarks:

Shortcut for page.mainFrame().focus(selector).

<span id="frames">frames()</span>

An array of all frames attached to the page.

<span id="getdefaultnavigationtimeout">getDefaultNavigationTimeout()</span>

Maximum navigation time in milliseconds.

<span id="getdefaulttimeout">getDefaultTimeout()</span>

Maximum time in milliseconds.

<span id="goback">goBack(options)</span>

This method navigate to the previous page in history.

<span id="goforward">goForward(options)</span>

This method navigate to the next page in history.

<span id="goto">goto(url, options)</span>

Navigates the frame or page to the given url.

Remarks:

Navigation to about:blank or navigation to the same URL with a different hash will succeed and return null.

:::warning

Headless shell mode doesn't support navigation to a PDF document. See the upstream issue.

:::

In headless shell, this method 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 HTTPResponse.status().

<span id="hasdevtools">hasDevTools()</span>

(Experimental) Returns true if DevTools is attached to the current page. Use Page.openDevTools() to get the DevTools page.

<span id="hover">hover(selector)</span>

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.

Remarks:

Shortcut for page.mainFrame().hover(selector).

<span id="isclosed">isClosed()</span>

Indicates that the page has been closed.

<span id="isdraginterceptionenabled">isDragInterceptionEnabled()</span>

deprecated

true if drag events are being intercepted, false otherwise.

Deprecated:

We no longer support intercepting drag payloads. Use the new drag APIs found on ElementHandle to drag (or just use the Page.mouse).

<span id="isjavascriptenabled">isJavaScriptEnabled()</span>

true if the page has JavaScript enabled, false otherwise.

<span id="isserviceworkerbypassed">isServiceWorkerBypassed()</span>

true if the service worker are being bypassed, false otherwise.

<span id="locator">locator(selector)</span>

Creates a locator for the provided selector. See Locator for details and supported actions.

<span id="locator">locator(func)</span>

Creates a locator for the provided function. See Locator for details and supported actions.

<span id="mainframe">mainFrame()</span>

The page's main frame.

<span id="metrics">metrics()</span>

Object containing metrics as key/value pairs.

Remarks:

All timestamps are in monotonic time: monotonically increasing time in seconds since an arbitrary point in the past.

<span id="opendevtools">openDevTools()</span>

Opens DevTools for the current Page and returns the DevTools Page. This method is only available in Chrome.

<span id="pdf">pdf(options)</span>

Generates a PDF of the page with the print CSS media type.

Remarks:

To generate a PDF with the screen media type, call `page.emulateMediaType('screen')` before calling page.pdf().

By default, page.pdf() generates a pdf with modified colors for printing. Use the `-webkit-print-color-adjust` property to force rendering of exact colors.

<span id="queryobjects">queryObjects(prototypeHandle)</span>

This method iterates the JavaScript heap and finds all objects with the given prototype.

<span id="reload">reload(options)</span>

Reloads the page.

<span id="removeexposedfunction">removeExposedFunction(name)</span>

The method removes a previously added function via $Page.exposeFunction() called name from the page's window object.

<span id="removescripttoevaluateonnewdocument">removeScriptToEvaluateOnNewDocument(identifier)</span>

Removes script that injected into page by Page.evaluateOnNewDocument.

<span id="resize">resize(params)</span>

(Experimental) Resizes the browser window of this page so that the content area (excluding browser UI) has the specified width and height.

<span id="screencast">screencast(options)</span>

(Experimental) Captures a screencast of this page.

Remarks:

By default, all recordings will be WebM format using the VP9 video codec, with a frame rate of 30 FPS.

You must have ffmpeg installed on your system.

<span id="screenshot">screenshot(options)</span>

Captures a screenshot of this page.

Remarks:

While a screenshot is being taken in a BrowserContext, the following methods will automatically wait for the screenshot to finish to prevent interference with the screenshot process: BrowserContext.newPage(), Browser.newPage(), Page.close().

Calling Page.bringToFront() will not wait for existing screenshot operations.

<span id="screenshot">screenshot(options)</span>

<span id="select">select(selector, values)</span>

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.

Remarks:

Shortcut for page.mainFrame().select()

<span id="setbypasscsp">setBypassCSP(enabled)</span>

Toggles bypassing 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.

<span id="setbypassserviceworker">setBypassServiceWorker(bypass)</span>

Toggles ignoring of service worker for each request.

<span id="setcacheenabled">setCacheEnabled(enabled)</span>

Toggles ignoring cache for each request based on the enabled state. By default, caching is enabled.

<span id="setcontent">setContent(html, options)</span>

Set the content of the page.

<span id="setcookie">setCookie(cookies)</span>

deprecated

Deprecated:

Page-level cookie API is deprecated. Use Browser.setCookie() or BrowserContext.setCookie() instead.

<span id="setdefaultnavigationtimeout">setDefaultNavigationTimeout(timeout)</span>

This setting will change the default maximum navigation time for the following methods and related shortcuts:

• page.goBack(options)

• page.goForward(options)

• page.goto(url,options)

• page.reload(options)

• page.setContent(html,options)

• page.waitForNavigation(options)

<span id="setdefaulttimeout">setDefaultTimeout(timeout)</span>

<span id="setdraginterception">setDragInterception(enabled)</span>

deprecated

Deprecated:

We no longer support intercepting drag payloads. Use the new drag APIs found on ElementHandle to drag (or just use the Page.mouse).

<span id="setextrahttpheaders">setExtraHTTPHeaders(headers)</span>

The extra HTTP headers will be sent with every request the page initiates.

:::tip

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.

:::

<span id="setgeolocation">setGeolocation(options)</span>

Sets the page's geolocation.

Remarks:

Consider using BrowserContext.overridePermissions() to grant permissions for the page to read its geolocation.

<span id="setjavascriptenabled">setJavaScriptEnabled(enabled)</span>

Remarks:

NOTE: changing this value won't affect scripts that have already been run. It will take full effect on the next navigation.

<span id="setofflinemode">setOfflineMode(enabled)</span>

Emulates the offline mode.

It does not change the download/upload/latency parameters set by Page.emulateNetworkConditions()

<span id="setrequestinterception">setRequestInterception(value)</span>

Activating request interception enables HTTPRequest.abort(), HTTPRequest.continue() and HTTPRequest.respond() methods. This provides the capability to modify network requests that are made by a page.

Once request interception is enabled, every request will stall unless it's continued, responded or aborted; or completed using the browser cache.

See the Request interception guide for more details.

<span id="setuseragent">setUserAgent(userAgent, userAgentMetadata)</span>

deprecated

Deprecated:

Use Page.setUserAgent() instead.

<span id="setuseragent">setUserAgent(options)</span>

<span id="setviewport">setViewport(viewport)</span>

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. Setting the viewport to null resets the viewport to its default value.

Remarks:

NOTE: in certain cases, setting viewport will reload the page in order to set the isMobile or hasTouch properties.

<span id="tap">tap(selector)</span>

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

Remarks:

Shortcut for page.mainFrame().tap(selector).

<span id="target">target()</span>

deprecated

A target this page was created from.

Deprecated:

Use Page.createCDPSession() directly.

<span id="title">title()</span>

The page's title

Remarks:

Shortcut for page.mainFrame().title().

<span id="type">type(selector, text, options)</span>

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

To press a special key, like Control or ArrowDown, use Keyboard.press().

<span id="url">url()</span>

The page's URL.

Remarks:

Shortcut for page.mainFrame().url().

<span id="viewport">viewport()</span>

Returns the current page viewport settings without checking the actual page viewport.

This is either the viewport set with the previous Page.setViewport() call or the default viewport set via ConnectOptions.defaultViewport.

<span id="waitfordeviceprompt">waitForDevicePrompt(options)</span>

This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.

:::caution

This must be called before the device request is made. It will not return a currently active device prompt.

:::

<span id="waitforfilechooser">waitForFileChooser(options)</span>

This method is typically coupled with an action that triggers file choosing.

:::caution

This must be called before the file chooser is launched. It will not return a currently active file chooser.

:::

:::caution

Interception of file dialogs triggered via DOM APIs such as window.showOpenFilePicker is currently not supported.

:::

Remarks:

In the "headful" browser, this method results in the native file picker dialog not showing up for the user.

<span id="waitforframe">waitForFrame(urlOrPredicate, options)</span>

Waits for a frame matching the given conditions to appear.

<span id="waitforfunction">waitForFunction(pageFunction, options, args)</span>

Waits for the provided function, pageFunction, to return a truthy value when evaluated in the page's context.

<span id="waitfornavigation">waitForNavigation(options)</span>

Waits for the page to navigate to a new URL or to reload. It is useful when you run code that will indirectly cause the page to navigate.

Remarks:

Usage of the History API to change the URL is considered a navigation.

<span id="waitfornetworkidle">waitForNetworkIdle(options)</span>

Waits for the network to be idle.

Remarks:

The function will always wait at least the set IdleTime.

<span id="waitforrequest">waitForRequest(urlOrPredicate, options)</span>

Remarks:

Optional Waiting Parameters have:

• timeout: Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. The default value can be changed by using the Page.setDefaultTimeout() method.

• signal: A signal object that allows you to cancel a waitForRequest call.

<span id="waitforresponse">waitForResponse(urlOrPredicate, options)</span>

Remarks:

Optional Parameter have:

• timeout: Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. The default value can be changed by using the Page.setDefaultTimeout() method.

• signal: A signal object that allows you to cancel a waitForResponse call.

<span id="waitforselector">waitForSelector(selector, options)</span>

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.

Remarks:

The optional Parameter in Arguments options are:

• visible: A boolean wait for element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties. Defaults to false.

• hidden: Wait for element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties. Defaults to false.

• timeout: maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultTimeout() method.

• signal: A signal object that allows you to cancel a waitForSelector call.

<span id="windowid">windowId()</span>

(Experimental) Returns the page's window id.

<span id="workers">workers()</span>

All of the dedicated WebWorkers associated with the page.

Remarks:

This does not contain ServiceWorkers