Class PageAbstract

{@inheritDoc Accessibility}

{@inheritDoc Coverage}

{@inheritDoc Keyboard}

{@inheritDoc Mouse}

{@inheritDoc Touchscreen}

{@inheritDoc Tracing}

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

Remarks

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

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

Remarks

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

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.

Example

// get the amount of divs on the page
const divCount = await page.$$eval('div', divs => divs.length);

// get the text content of all the `.options` elements:
const options = await page.$$eval('div > span.options', options => {
  return options.map(option => option.textContent);
});
Copy

If you are using TypeScript, you may have to provide an explicit type to the first argument of the pageFunction. By default it is typed as Element[], but you may need to provide a more specific sub-type:

Example

await page.$$eval('input', elements => {
  return elements.map(e => e.value);
});
Copy

The compiler should be able to infer the return type from the pageFunction you provide. If it is unable to, you can use the generic type to tell the compiler what return type you expect from $$eval:

Example

const allInputValues = await page.$$eval('input', elements =>
  elements.map(e => e.textContent)
);
Copy

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.

Example

const searchValue = await page.$eval('#search', el => el.value);
const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
const html = await page.$eval('.main-container', el => el.outerHTML);
Copy

If you are using TypeScript, you may have to provide an explicit type to the first argument of the pageFunction. By default it is typed as Element, but you may need to provide a more specific sub-type:

Example

// if you don't provide HTMLInputElement here, TS will error
// as `value` is not on `Element`
const searchValue = await page.$eval(
  '#search',
  (el: HTMLInputElement) => el.value
);
Copy

The compiler should be able to infer the return type from the pageFunction you provide. If it is unable to, you can use the generic type to tell the compiler what return type you expect from $eval:

Example

// The compiler can infer the return type in this case, but if it can't
// or if you want to be more explicit, provide it as the generic type.
const searchValue = await page.$eval<string>(
  '#search',
  (el: HTMLInputElement) => el.value
);
Copy

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

Remarks

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

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 Frame.(addStyleTag:2) | page.mainFrame().addStyleTag(options).

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.

Brings page to front (activates tab).

Get the browser the page belongs to.

Get the browser context that the page belongs to.

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),
]);
Copy

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

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

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.

Creates a Chrome Devtools Protocol session attached to the page.

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.

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.

Example

import {KnownDevices} from 'puppeteer';
const iPhone = KnownDevices['iPhone 15 Pro'];

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.emulate(iPhone);
  await page.goto('https://www.google.com');
  // other actions...
  await browser.close();
})();
Copy

Enables CPU throttling to emulate slow CPUs.

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

Example

// set idle emulation
await page.emulateIdleState({isUserActive: true, isScreenUnlocked: false});

// do some checks here
...

// clear idle emulation
await page.emulateIdleState();
Copy

Example

await page.emulateMediaFeatures([
  {name: 'prefers-color-scheme', value: 'dark'},
]);
await page.evaluate(
  () => matchMedia('(prefers-color-scheme: dark)').matches
);
// → true
await page.evaluate(
  () => matchMedia('(prefers-color-scheme: light)').matches
);
// → false

await page.emulateMediaFeatures([
  {name: 'prefers-reduced-motion', value: 'reduce'},
]);
await page.evaluate(
  () => matchMedia('(prefers-reduced-motion: reduce)').matches
);
// → true
await page.evaluate(
  () => matchMedia('(prefers-reduced-motion: no-preference)').matches
);
// → false

await page.emulateMediaFeatures([
  {name: 'prefers-color-scheme', value: 'dark'},
  {name: 'prefers-reduced-motion', value: 'reduce'},
]);
await page.evaluate(
  () => matchMedia('(prefers-color-scheme: dark)').matches
);
// → true
await page.evaluate(
  () => matchMedia('(prefers-color-scheme: light)').matches
);
// → false
await page.evaluate(
  () => matchMedia('(prefers-reduced-motion: reduce)').matches
);
// → true
await page.evaluate(
  () => matchMedia('(prefers-reduced-motion: no-preference)').matches
);
// → false

await page.emulateMediaFeatures([{name: 'color-gamut', value: 'p3'}]);
await page.evaluate(() => matchMedia('(color-gamut: srgb)').matches);
// → true
await page.evaluate(() => matchMedia('(color-gamut: p3)').matches);
// → true
await page.evaluate(() => matchMedia('(color-gamut: rec2020)').matches);
// → false
Copy

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
Copy

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.

Example

import {PredefinedNetworkConditions} from 'puppeteer';
const slow3G = PredefinedNetworkConditions['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();
})();
Copy

Simulates the given vision deficiency on the page.

Example

import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://v8.dev/blog/10-years');

  await page.emulateVisionDeficiency('achromatopsia');
  await page.screenshot({path: 'achromatopsia.png'});

  await page.emulateVisionDeficiency('deuteranopia');
  await page.screenshot({path: 'deuteranopia.png'});

  await page.emulateVisionDeficiency('blurredVision');
  await page.screenshot({path: 'blurred-vision.png'});

  await browser.close();
})();
Copy

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.

Example

const result = await frame.evaluate(() => {
  return Promise.resolve(8 * 7);
});
console.log(result); // prints "56"
Copy

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

Example

const aHandle = await page.evaluate('1 + 2');
Copy

To get the best TypeScript experience, you should pass in as the generic the type of pageFunction:

const aHandle = await page.evaluate(() => 2);
Copy

Example

ElementHandle instances (including JSHandles) can be passed as arguments to the pageFunction:

const bodyHandle = await page.$('body');
const html = await page.evaluate(body => body.innerHTML, bodyHandle);
await bodyHandle.dispose();
Copy

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):

Example

const aHandle = await page.evaluateHandle('document');
Copy

Example

JSHandle instances can be passed as arguments to the pageFunction:

const aHandle = await page.evaluateHandle(() => document.body);
const resultHandle = await page.evaluateHandle(
  body => body.innerHTML,
  aHandle
);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();
Copy

Most of the time this function returns a JSHandle, but if pageFunction returns a reference to an element, you instead get an ElementHandle back:

Example

const button = await page.evaluateHandle(() =>
  document.querySelector('button')
);
// can call `click` because `button` is an `ElementHandle`
await button.click();
Copy

The TypeScript definitions assume that evaluateHandle returns a JSHandle, but if you know it's going to return an ElementHandle, pass it as the generic argument:

const button = await page.evaluateHandle<ElementHandle>(...);
Copy

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.

Example

An example of overriding the navigator.languages property before the page loads:

// 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);
Copy

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.

:::

Example

An example of adding an md5 function into the page:

import puppeteer from 'puppeteer';
import crypto from '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();
})();
Copy

Example

An example of adding a window.readfile function into the page:

import puppeteer from 'puppeteer';
import fs from '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();
})();
Copy

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 Frame.focus | page.mainFrame().focus(selector).

An array of all frames attached to the page.

Maximum time in milliseconds.

This method navigate to the previous page in history.

This method navigate to the next page in history.

{@inheritDoc Frame.goto}

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).

Indicates that the page has been closed.

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).

true if the page has JavaScript enabled, false otherwise.

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

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

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

The page's main frame.

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.

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.

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

Example

// Create a Map object
await page.evaluate(() => (window.map = new Map()));
// Get a handle to the Map object prototype
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Query all map instances into an array
const mapInstances = await page.queryObjects(mapPrototype);
// Count amount of map objects in heap
const count = await page.evaluate(maps => maps.length, mapInstances);
await mapInstances.dispose();
await mapPrototype.dispose();
Copy

Reloads the page.

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

Removes script that injected into page by Page.evaluateOnNewDocument.

Captures a screencast of this page.

Example

Recording a page:

import puppeteer from 'puppeteer';

// Launch a browser
const browser = await puppeteer.launch();

// Create a new page
const page = await browser.newPage();

// Go to your site.
await page.goto("https://www.example.com");

// Start recording.
const recorder = await page.screencast({path: 'recording.webm'});

// Do something.

// Stop recording.
await recorder.stop();

browser.close();
Copy

Remarks

All recordings will be WebM format using the VP9 video codec. The FPS is 30.

You must have ffmpeg installed on your system.

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.

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

page.select('select#colors', 'blue'); // single selection
page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
Copy

Remarks

Shortcut for Frame.select | page.mainFrame().select()

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.

Toggles ignoring of service worker for each request.

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

Default Value

true

Set the content of the page.

Example

await page.setCookie(cookieObject1, cookieObject2);
Copy

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)

Deprecated

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

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.

:::

Sets the page's geolocation.

Remarks

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

Example

await page.setGeolocation({latitude: 59.95, longitude: 30.31667});
Copy

Remarks

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

Sets the network connection to offline.

It does not change the parameters used in Page.emulateNetworkConditions

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 interception guide for more details.

Example

An example of a naïve request interceptor that aborts all image requests:

import puppeteer from 'puppeteer';
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setRequestInterception(true);
  page.on('request', interceptedRequest => {
    if (
      interceptedRequest.url().endsWith('.png') ||
      interceptedRequest.url().endsWith('.jpg')
    )
      interceptedRequest.abort();
    else interceptedRequest.continue();
  });
  await page.goto('https://example.com');
  await browser.close();
})();
Copy

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.

Example

const page = await browser.newPage();
await page.setViewport({
  width: 640,
  height: 480,
  deviceScaleFactor: 1,
});
await page.goto('https://example.com');
Copy

Remarks

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

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 Frame.tap | page.mainFrame().tap(selector).

A target this page was created from.

Deprecated

Use Page.createCDPSession directly.

The page's title

Remarks

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

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.

Example

await page.type('#mytextarea', 'Hello');
// Types instantly
await page.type('#mytextarea', 'World', {delay: 100});
// Types slower, like a user
Copy

The page's URL.

Remarks

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

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 | BrowserConnectOptions.defaultViewport.

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.

:::

Example

const [devicePrompt] = Promise.all([
  page.waitForDevicePrompt(),
  page.click('#connect-bluetooth'),
]);
await devicePrompt.select(
  await devicePrompt.waitForDevice(({name}) => name.includes('My Device'))
);
Copy

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.

Example

The following example clicks a button that issues a file chooser and then responds with /tmp/myfile.pdf as if a user has selected this file.

const [fileChooser] = await Promise.all([
  page.waitForFileChooser(),
  page.click('#upload-file-button'),
  // some button that triggers file selection
]);
await fileChooser.accept(['/tmp/myfile.pdf']);
Copy

Waits for a frame matching the given conditions to appear.

Example

const frame = await page.waitForFrame(async frame => {
  return frame.name() === 'Test';
});
Copy