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';

(async () => {
  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
accessibility	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.
coverage	readonly	Coverage	The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page.
keyboard	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.
mouse	readonly	Mouse	The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
touchscreen	readonly	Touchscreen	The Touchscreen class exposes touchscreen events.
tracing	readonly	Tracing	The Tracing class exposes the tracing audit interface.

Methods

Method	Modifiers	Description
$		Runs document.querySelector within the page. If no element matches the selector, the return value resolves to null.
$$		The method runs document.querySelectorAll within the page. If no elements match the selector, the return value resolves to [].
$$eval		This method runs Array.from(document.querySelectorAll(selector)) within the page and passes the result as the first argument to the pageFunction.
$eval		This method runs document.querySelector within the page and passes the result as the first argument to the pageFunction.
$x		The method evaluates the XPath expression relative to the page document as its context node. If there are no such elements, the method resolves to an empty array.
addScriptTag		Adds a <script> tag into the page with the desired URL or content.
addStyleTag		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).
addStyleTag
authenticate		Provide credentials for HTTP authentication.
bringToFront		Brings page to front (activates tab).
browser		Get the browser the page belongs to.
browserContext		Get the browser context that the page belongs to.
click		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.
close
content		The full HTML contents of the page, including the DOCTYPE.
cookies		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.
createCDPSession		Creates a Chrome Devtools Protocol session attached to the page.
createPDFStream		Generates a PDF of the page with the print CSS media type.
deleteCookie
emulate		Emulates a given device's metrics and user agent. To aid emulation, Puppeteer provides a list of known devices that can be via KnownDevices.
emulateCPUThrottling		Enables CPU throttling to emulate slow CPUs.
emulateIdleState		Emulates the idle state. If no arguments set, clears idle state emulation.
emulateMediaFeatures
emulateMediaType
emulateNetworkConditions		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.
emulateTimezone
emulateVisionDeficiency		Simulates the given vision deficiency on the page.
evaluate		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.
evaluateHandle
evaluateOnNewDocument		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.
exposeFunction		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. :::note
focus		This method fetches an element with selector and focuses it. If there's no element matching selector, the method throws an error.
frames		An array of all frames attached to the page.
getDefaultTimeout		Maximum time in milliseconds.
goBack		This method navigate to the previous page in history.
goForward		This method navigate to the next page in history.
goto		Navigates the page to the given url.
hover		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.
isClosed		Indicates that the page has been closed.
isDragInterceptionEnabled		true if drag events are being intercepted, false otherwise.
isJavaScriptEnabled		true if the page has JavaScript enabled, false otherwise.
isServiceWorkerBypassed		true if the service worker are being bypassed, false otherwise.
locator		Creates a locator for the provided selector. See Locator for details and supported actions.
locator		Creates a locator for the provided function. See Locator for details and supported actions.
mainFrame		The page's main frame.
metrics		Object containing metrics as key/value pairs.
pdf		Generates a PDF of the page with the print CSS media type.
queryObjects		This method iterates the JavaScript heap and finds all objects with the given prototype.
reload		Reloads the page.
removeExposedFunction		The method removes a previously added function via $Page.exposeFunction() called name from the page's window object.
removeScriptToEvaluateOnNewDocument		Removes script that injected into page by Page.evaluateOnNewDocument.
screencast		Captures a screencast of this page.
screenshot		Captures a screenshot of this page.
screenshot
select		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.
setBypassCSP		Toggles bypassing page's Content-Security-Policy.
setBypassServiceWorker		Toggles ignoring of service worker for each request.
setCacheEnabled		Toggles ignoring cache for each request based on the enabled state. By default, caching is enabled.
setContent		Set the content of the page.
setCookie
setDefaultNavigationTimeout		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)
setDefaultTimeout
setDragInterception
setExtraHTTPHeaders		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. :::
setGeolocation		Sets the page's geolocation.
setJavaScriptEnabled
setOfflineMode		Sets the network connection to offline. It does not change the parameters used in Page.emulateNetworkConditions()
setRequestInterception		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.
setUserAgent
setViewport		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.
tap		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.
target		A target this page was created from.
title		The page's title
type		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().
url		The page's URL.
viewport		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 BrowserConnectOptions.defaultViewport.
waitForDevicePrompt		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. :::
waitForFileChooser		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. :::
waitForFrame		Waits for a frame matching the given conditions to appear.
waitForFunction		Waits for the provided function, pageFunction, to return a truthy value when evaluated in the page's context.
waitForNavigation		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.
waitForNetworkIdle
waitForRequest
waitForResponse
waitForSelector		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.
waitForTimeout
waitForXPath		Wait for the xpath to appear in page. If at the moment of calling the method the xpath already exists, the method will return immediately. If the xpath doesn't appear after the timeout milliseconds of waiting, the function will throw.
workers		All of the dedicated WebWorkers associated with the page.