Interface Page

NOTE Use locator-based page.locator(selector[, options]) instead. Read more about locators.

The method finds an element matching the specified selector within the page. If no elements match the selector, the return value resolves to null. To wait for an element on the page, use locator.waitFor([options]).

NOTE Use locator-based page.locator(selector[, options]) instead. Read more about locators.

The method finds an element matching the specified selector within the page. If no elements match the selector, the return value resolves to null. To wait for an element on the page, use locator.waitFor([options]).

NOTE Use locator-based page.locator(selector[, options]) instead. Read more about locators.

The method finds all elements matching the specified selector within the page. If no elements match the selector, the return value resolves to [].

NOTE Use locator-based page.locator(selector[, options]) instead. Read more about locators.

The method finds all elements matching the specified selector within the page. If no elements match the selector, the return value resolves to [].

NOTE In most cases, locator.evaluateAll(pageFunction[, arg]), other [Locator] helper methods and web-first assertions do a better job.

The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to pageFunction. Returns the result of pageFunction invocation.

If pageFunction returns a [Promise], then page.$$eval(selector, pageFunction[, arg]) would wait for the promise to resolve and return its value.

Usage

const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);

NOTE In most cases, locator.evaluateAll(pageFunction[, arg]), other [Locator] helper methods and web-first assertions do a better job.

The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to pageFunction. Returns the result of pageFunction invocation.

If pageFunction returns a [Promise], then page.$$eval(selector, pageFunction[, arg]) would wait for the promise to resolve and return its value.

Usage

const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);

NOTE In most cases, locator.evaluateAll(pageFunction[, arg]), other [Locator] helper methods and web-first assertions do a better job.

The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to pageFunction. Returns the result of pageFunction invocation.

If pageFunction returns a [Promise], then page.$$eval(selector, pageFunction[, arg]) would wait for the promise to resolve and return its value.

Usage

const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);

NOTE In most cases, locator.evaluateAll(pageFunction[, arg]), other [Locator] helper methods and web-first assertions do a better job.

The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to pageFunction. Returns the result of pageFunction invocation.

If pageFunction returns a [Promise], then page.$$eval(selector, pageFunction[, arg]) would wait for the promise to resolve and return its value.

Usage

const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);

NOTE This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use locator.evaluate(pageFunction[, arg, options]), other [Locator] helper methods or web-first assertions instead.

The method finds an element matching the specified selector within the page and passes it as a first argument to pageFunction. If no elements match the selector, the method throws an error. Returns the value of pageFunction.

If pageFunction returns a [Promise], then page.$eval(selector, pageFunction[, arg, options]) would wait for the promise to resolve and return its value.

Usage

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', (e, suffix) => e.outerHTML + suffix, 'hello');
// In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);

NOTE This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use locator.evaluate(pageFunction[, arg, options]), other [Locator] helper methods or web-first assertions instead.

The method finds an element matching the specified selector within the page and passes it as a first argument to pageFunction. If no elements match the selector, the method throws an error. Returns the value of pageFunction.

If pageFunction returns a [Promise], then page.$eval(selector, pageFunction[, arg, options]) would wait for the promise to resolve and return its value.

Usage

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', (e, suffix) => e.outerHTML + suffix, 'hello');
// In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);

NOTE This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use locator.evaluate(pageFunction[, arg, options]), other [Locator] helper methods or web-first assertions instead.

The method finds an element matching the specified selector within the page and passes it as a first argument to pageFunction. If no elements match the selector, the method throws an error. Returns the value of pageFunction.

If pageFunction returns a [Promise], then page.$eval(selector, pageFunction[, arg, options]) would wait for the promise to resolve and return its value.

Usage

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', (e, suffix) => e.outerHTML + suffix, 'hello');
// In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);

NOTE This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use locator.evaluate(pageFunction[, arg, options]), other [Locator] helper methods or web-first assertions instead.

The method finds an element matching the specified selector within the page and passes it as a first argument to pageFunction. If no elements match the selector, the method throws an error. Returns the value of pageFunction.

If pageFunction returns a [Promise], then page.$eval(selector, pageFunction[, arg, options]) would wait for the promise to resolve and return its value.

Usage

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', (e, suffix) => e.outerHTML + suffix, 'hello');
// In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);

Adds a script which would be evaluated in one of the following scenarios:

• Whenever the page is navigated.
• Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.

The script is evaluated 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.

Usage

An example of overriding Math.random before the page loads:

// preload.js
Math.random = () => 42;

// In your playwright script, assuming the preload.js file is in same directory
await page.addInitScript({ path: './preload.js' });

NOTE The order of evaluation of multiple scripts installed via browserContext.addInitScript(script[, arg]) and page.addInitScript(script[, arg]) is not defined.

Emitted when the page closes.

Emitted when JavaScript within the page calls one of console API methods, e.g. console.log or console.dir. Also emitted if the page throws an error or a warning.

The arguments passed into console.log appear as arguments on the event handler.

An example of handling console event:

page.on('console', async msg => {
  const values = [];
  for (const arg of msg.args())
    values.push(await arg.jsonValue());
  console.log(...values);
});
await page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));

Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page crashes, ongoing and subsequent operations will throw.

The most common way to deal with crashes is to catch an exception:

try {
  // Crash might happen during a click.
  await page.click('button');
  // Or while waiting for an event.
  await page.waitForEvent('popup');
} catch (e) {
  // When the page crashes, exception message contains 'crash'.
}

Emitted when a JavaScript dialog appears, such as alert, prompt, confirm or beforeunload. Listener must either dialog.accept([promptText]) or dialog.dismiss() the dialog - otherwise the page will freeze waiting for the dialog, and actions like click will never finish.

page.on('dialog', dialog => {
  dialog.accept();
});

NOTE When no page.on('dialog') listeners are present, all dialogs are automatically dismissed.

Emitted when the JavaScript DOMContentLoaded event is dispatched.

Emitted when attachment download started. User can access basic file operations on downloaded content via the passed [Download] instance.

Emitted when a file chooser is supposed to appear, such as after clicking the <input type=file>. Playwright can respond to it via setting the input files using fileChooser.setFiles(files[, options]) that can be uploaded after that.

page.on('filechooser', async (fileChooser) => {
  await fileChooser.setFiles('/tmp/myfile.pdf');
});

Emitted when a frame is attached.

Emitted when a frame is detached.

Emitted when a frame is navigated to a new url.

Emitted when the JavaScript load event is dispatched.

Emitted when an uncaught exception happens within the page.

// Log all uncaught errors to the terminal
page.on('pageerror', exception => {
  console.log(`Uncaught exception: "${exception}"`);
});

// Navigate to a page with an exception.
await page.goto('data:text/html,<script>throw new Error("Test")</script>');

Emitted when the page opens a new tab or window. This event is emitted in addition to the browserContext.on('page'), but only for popups relevant to this page.

The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with window.open('http://example.com'), this event will fire when the network request to "http://example.com" is done and its response has started loading in the popup.

// Start waiting for popup before clicking. Note no await.
const popupPromise = page.waitForEvent('popup');
await page.getByText('open the popup').click();
const popup = await popupPromise;
console.log(await popup.evaluate('location.href'));

NOTE Use page.waitForLoadState([state, options]) to wait until the page gets to a particular state (you should not need it in most cases).

Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see page.route(url, handler[, options]) or browserContext.route(url, handler[, options]).

Emitted when a request fails, for example by timing out.

page.on('requestfailed', request => {
  console.log(request.url() + ' ' + request.failure().errorText);
});

NOTE HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with page.on('requestfinished') event and not with page.on('requestfailed'). A request will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network error net::ERR_FAILED.

Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is request, response and requestfinished.

Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is request, response and requestfinished.

Emitted when [WebSocket] request is sent.

Emitted when a dedicated WebWorker is spawned by the page.

Adds a <script> tag into the page with the desired url or content. Returns the added tag when the script's onload fires or when the script content was injected into frame.

Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.

Brings page to front (activates tab).

NOTE Use locator-based locator.check([options]) instead. Read more about locators.

This method checks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
4. Scroll the element into view if needed.
5. Use page.mouse to click in the center of the element.
6. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
7. Ensure that the element is now checked. If not, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a [TimeoutError]. Passing zero timeout disables this.

NOTE Use locator-based locator.click([options]) instead. Read more about locators.

This method clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to click in the center of the element, or the specified position.
5. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.

When all steps combined have not finished during the specified timeout, this method throws a [TimeoutError]. Passing zero timeout disables this.

If runBeforeUnload is false, does not run any unload handlers and waits for the page to be closed. If runBeforeUnload is true the method will run unload handlers, but will not wait for the page to close.

By default, page.close() does not run beforeunload handlers.

NOTE if runBeforeUnload is passed as true, a beforeunload dialog might be summoned and should be handled manually via page.on('dialog') event.

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

Get the browser context that the page belongs to.

NOTE Use locator-based locator.dblclick([options]) instead. Read more about locators.

This method double clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to double click in the center of the element, or the specified position.
5. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set. Note that if the first click of the dblclick() triggers a navigation event, this method will throw.

When all steps combined have not finished during the specified timeout, this method throws a [TimeoutError]. Passing zero timeout disables this.

NOTE page.dblclick() dispatches two click events and a single dblclick event.

NOTE Use locator-based locator.dispatchEvent(type[, eventInit, options]) instead. Read more about locators.

The snippet below dispatches the click event on the element. Regardless of the visibility state of the element, click is dispatched. This is equivalent to calling element.click().

Usage

await page.dispatchEvent('button#submit', 'click');

Under the hood, it creates an instance of an event based on the given type, initializes it with eventInit properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:

• DragEvent
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• Event

You can also specify JSHandle as the property value if you want live objects to be passed into the event:

// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await page.dispatchEvent('#source', 'dragstart', { dataTransfer });

This method drags the source element to the target element. It will first move to the source element, perform a mousedown, then move to the target element and perform a mouseup.

Usage

await page.dragAndDrop('#source', '#target');
// or specify exact positions relative to the top-left corners of the elements:
await page.dragAndDrop('#source', '#target', {
  sourcePosition: { x: 34, y: 7 },
  targetPosition: { x: 10, y: 20 },
});

This method changes the CSS media type through the media argument, and/or the 'prefers-colors-scheme' media feature, using the colorScheme argument.

Usage

await page.evaluate(() => matchMedia('screen').matches);
// → true
await page.evaluate(() => matchMedia('print').matches);
// → false

await page.emulateMedia({ media: 'print' });
await page.evaluate(() => matchMedia('screen').matches);
// → false
await page.evaluate(() => matchMedia('print').matches);
// → true

await page.emulateMedia({});
await page.evaluate(() => matchMedia('screen').matches);
// → true
await page.evaluate(() => matchMedia('print').matches);
// → false

await page.emulateMedia({ colorScheme: 'dark' });
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-color-scheme: no-preference)').matches);
// → false

Returns the value of the pageFunction invocation.

If the function passed to the page.evaluate(pageFunction[, arg]) returns a [Promise], then page.evaluate(pageFunction[, arg]) would wait for the promise to resolve and return its value.

If the function passed to the page.evaluate(pageFunction[, arg]) returns a non-[Serializable] value, then page.evaluate(pageFunction[, arg]) resolves to undefined. Playwright also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity.

Usage

Passing argument to pageFunction:

const result = await page.evaluate(([x, y]) => {
  return Promise.resolve(x * y);
}, [7, 8]);
console.log(result); // prints "56"

A string can also be passed in instead of a function:

console.log(await page.evaluate('1 + 2')); // prints "3"
const x = 10;
console.log(await page.evaluate(`1 + ${x}`)); // prints "11"

[ElementHandle] instances can be passed as an argument to the page.evaluate(pageFunction[, arg]):

const bodyHandle = await page.evaluate('document.body');
const html = await page.evaluate(([body, suffix]) => body.innerHTML + suffix, [bodyHandle, 'hello']);
await bodyHandle.dispose();

Returns the value of the pageFunction invocation.

If the function passed to the page.evaluate(pageFunction[, arg]) returns a [Promise], then page.evaluate(pageFunction[, arg]) would wait for the promise to resolve and return its value.

If the function passed to the page.evaluate(pageFunction[, arg]) returns a non-[Serializable] value, then page.evaluate(pageFunction[, arg]) resolves to undefined. Playwright also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity.

Usage

Passing argument to pageFunction:

const result = await page.evaluate(([x, y]) => {
  return Promise.resolve(x * y);
}, [7, 8]);
console.log(result); // prints "56"

A string can also be passed in instead of a function:

console.log(await page.evaluate('1 + 2')); // prints "3"
const x = 10;
console.log(await page.evaluate(`1 + ${x}`)); // prints "11"

[ElementHandle] instances can be passed as an argument to the page.evaluate(pageFunction[, arg]):

const bodyHandle = await page.evaluate('document.body');
const html = await page.evaluate(([body, suffix]) => body.innerHTML + suffix, [bodyHandle, 'hello']);
await bodyHandle.dispose();

Returns the value of the pageFunction invocation as a [JSHandle].

The only difference between page.evaluate(pageFunction[, arg]) and page.evaluateHandle(pageFunction[, arg]) is that page.evaluateHandle(pageFunction[, arg]) returns [JSHandle].

If the function passed to the page.evaluateHandle(pageFunction[, arg]) returns a [Promise], then page.evaluateHandle(pageFunction[, arg]) would wait for the promise to resolve and return its value.

Usage

const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window));
aWindowHandle; // Handle for the window object.

A string can also be passed in instead of a function:

const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'

[JSHandle] instances can be passed as an argument to the page.evaluateHandle(pageFunction[, arg]):

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

Returns the value of the pageFunction invocation as a [JSHandle].

The only difference between page.evaluate(pageFunction[, arg]) and page.evaluateHandle(pageFunction[, arg]) is that page.evaluateHandle(pageFunction[, arg]) returns [JSHandle].

If the function passed to the page.evaluateHandle(pageFunction[, arg]) returns a [Promise], then page.evaluateHandle(pageFunction[, arg]) would wait for the promise to resolve and return its value.

Usage

const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window));
aWindowHandle; // Handle for the window object.

A string can also be passed in instead of a function:

const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'

[JSHandle] instances can be passed as an argument to the page.evaluateHandle(pageFunction[, arg]):

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

The method adds a function called name on the window object of every frame in this page. When called, the function executes callback and returns a [Promise] which resolves to the return value of callback. If the callback returns a [Promise], it will be awaited.

The first argument of the callback function contains information about the caller: { browserContext: BrowserContext, page: Page, frame: Frame }.

See browserContext.exposeBinding(name, callback[, options]) for the context-wide version.

NOTE Functions installed via page.exposeBinding(name, callback[, options]) survive navigations.

Usage

An example of exposing page URL to all frames in a page:

const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.

(async () => {
  const browser = await webkit.launch({ headless: false });
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.exposeBinding('pageURL', ({ page }) => page.url());
  await page.setContent(`
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.pageURL();
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
  `);
  await page.click('button');
})();

An example of passing an element handle:

await page.exposeBinding('clicked', async (source, element) => {
  console.log(await element.textContent());
}, { handle: true });
await page.setContent(`
  <script>
    document.addEventListener('click', event => window.clicked(event.target));
  </script>
  <div>Click me</div>
  <div>Or click me</div>
`);

The method adds a function called name on the window object of every frame in this page. When called, the function executes callback and returns a [Promise] which resolves to the return value of callback. If the callback returns a [Promise], it will be awaited.

The first argument of the callback function contains information about the caller: { browserContext: BrowserContext, page: Page, frame: Frame }.

See browserContext.exposeBinding(name, callback[, options]) for the context-wide version.

NOTE Functions installed via page.exposeBinding(name, callback[, options]) survive navigations.

Usage

An example of exposing page URL to all frames in a page:

const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.

(async () => {
  const browser = await webkit.launch({ headless: false });
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.exposeBinding('pageURL', ({ page }) => page.url());
  await page.setContent(`
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.pageURL();
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
  `);
  await page.click('button');
})();

An example of passing an element handle:

await page.exposeBinding('clicked', async (source, element) => {
  console.log(await element.textContent());
}, { handle: true });
await page.setContent(`
  <script>
    document.addEventListener('click', event => window.clicked(event.target));
  </script>
  <div>Click me</div>
  <div>Or click me</div>
`);

The method adds a function called name on the window object of every frame in the page. When called, the function executes callback and returns a [Promise] which resolves to the return value of callback.

If the callback returns a [Promise], it will be awaited.

See browserContext.exposeFunction(name, callback) for context-wide exposed function.

NOTE Functions installed via page.exposeFunction(name, callback) survive navigations.

Usage

An example of adding a sha256 function to the page:

const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.
const crypto = require('crypto');

(async () => {
  const browser = await webkit.launch({ headless: false });
  const page = await browser.newPage();
  await page.exposeFunction('sha256', text => crypto.createHash('sha256').update(text).digest('hex'));
  await page.setContent(`
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
  `);
  await page.click('button');
})();

NOTE Use locator-based locator.fill(value[, options]) instead. Read more about locators.

This method waits for an element matching selector, waits for actionability checks, focuses the element, fills it and triggers an input event after filling. Note that you can pass an empty string to clear the input field.

If the target element is not an <input>, <textarea> or [contenteditable] element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be filled instead.

To send fine-grained keyboard events, use page.type(selector, text[, options]).