Core concepts

Along with a test runner Playwright can be used to automate user interactions to validate and test web applications. The Playwright API enables this through the following primitives.

A refers to an instance of Chromium, Firefox or WebKit. Playwright scripts generally start with launching a browser instance and end with closing the browser. Browser instances can be launched in headless (without a GUI) or headful mode.

Launching a browser instance can be expensive, and Playwright is designed to maximize what a single instance can do through multiple browser contexts.

API reference

Browser contexts

A BrowserContext is an isolated incognito-alike session within a browser instance. Browser contexts are fast and cheap to create. Browser contexts can be used to parallelize isolated test executions.

  1. const browser = await chromium.launch();
  2. const context = await browser.newContext();

Browser contexts can also be used to emulate multi-page scenarios involving mobile devices, permissions, locale and color scheme.

  1. const { devices } = require('playwright');
  2. const iPhone = devices['iPhone 11 Pro'];
  4. const context = await browser.newContext({
  5.   ...iPhone,
  6.   permissions: ['geolocation'],
  7.   geolocation: { latitude: 52.52, longitude: 13.39},
  8.   colorScheme: 'dark',
  9.   locale: 'de-DE'
  10. });

API reference

A Browser context can have multiple pages. A refers to a single tab or a popup window within a browser context. It should be used to navigate to URLs and interact with the page content.

  1. // Create a page.
  2. const page = await context.newPage();
  1. // Navigate explicitly, similar to entering a URL in the browser.
  2. await page.goto('http://example.com');
  3. // Fill an input.
  4. await page.fill('#search', 'query');
  1. // Navigate implicitly by clicking a link.
  2. // Expect a new url.
  3. console.log(page.url());
  1. // Page can navigate from the script - this will be picked up by Playwright.
  2. window.location.href = 'https://example.com';

A page can have one or more Frame objects attached to it. Each page has a main frame and page-level interactions (like click) are assumed to operate in the main frame.

A page can have additional frames attached with the iframe HTML tag. These frames can be accessed for interactions inside the frame.

API reference

To learn more about navigation and loading, read this document.

Selectors

You can explicitly specify the selector engine you are using or let Playwright detect it.

All selector engines except for XPath pierce shadow DOM by default. If you want to enforce regular DOM selection, you can use the *:light versions of the selectors. You don’t typically need to though.

Learn more about selectors and selector engines here.

Some examples below:

  1. // Using data-test-id= selector engine
  2. await page.click('data-test-id=foo');
  1. // CSS and XPath selector engines are automatically detected
  2. await page.click('div');
  3. await page.click('//html/body/div');
  1. // Find node by text substring
  2. await page.click('text=Hello w');
  1. // Explicit CSS and XPath notation
  2. await page.click('css=div');
  3. await page.click('xpath=//html/body/div');
  1. // Only search light DOM, outside WebComponent shadow DOM:
  2. await page.click('css:light=div');

Selectors using the same or different engines can be combined using the >> separator. For example,

  1. // Click an element with text 'Sign Up' inside of a #free-month-promo.
  2. await page.click('#free-month-promo >> text=Sign Up');

Actions like click and fill auto-wait for the element to be visible and actionable. For example, click will:

  • wait for an element with the given selector to appear in the DOM
  • wait for it to become displayed: have non-empty bounding box and no visibility:hidden
  • wait for it to stop moving: for example, wait until css transition finishes
  • scroll the element into view
  • wait for it to receive pointer events at the action point: for example, wait until element becomes non-obscured by other elements
  • retry if the element is detached during any of the above checks
  1. // Playwright waits for #search element to be in the DOM
  2. await page.fill('#search', 'query');
  1. // Playwright waits for element to stop animating
  2. // and accept clicks.
  3. await page.click('#search');

You can explicitly wait for an element to appear in the DOM or to become visible:

  1. // Wait for #search to appear in the DOM.
  2. await page.waitForSelector('#search', { state: 'attached' });
  3. await page.waitForSelector('#promo');

… or to become hidden or detached

  1. // Wait for #details to become hidden, for example with `display:none`.
  2. await page.waitForSelector('#details', { state: 'hidden' });
  3. // Wait for #promo to be removed from the DOM.
  4. await page.waitForSelector('#promo', { state: 'detached' });

API reference

Node.js and browser execution contexts

Playwright scripts run in your Node.js environment. You page scripts run in the page environment. Those environments don’t intersect, they are running in different virtual machines in different processes and potentially on different computers.

The page.evaluate API can run a JavaScript function in the context of the web page and bring results back to the Node.js environment. Globals like and document along with the web page runtime can be used in evaluate.

Right:

  1. const data = { text: 'some data', value: 1 };
  2. // Pass |data| as a parameter.
  3. const result = await page.evaluate(data => {
  4.   window.myApp.use(data);
  5. }, data);

Wrong:

  1. const data = { text: 'some data', value: 1 };
  2. const result = await page.evaluate(() => {
  3.   // There is no |data| in the web page.
  4.   window.myApp.use(data);
  5. });

Evaluation parameters are serialized and sent into your web page over the wire. You can pass primitive types, JSON-alike objects and remote object handles received from the page.

Playwright has an API to create Node-side handles to the page DOM elements or any other objects inside the page. These handles live in the Node.js process, whereas the actual objects reside in browser.

IMAGE PLACEHOLDER

There are two types of handles:

  • to reference any javascript objects in the page
  • ElementHandle to reference DOM elements in the page

Note that since any DOM element in the page is also a javascript object, Playwright’s extends JSHandle.

Handles Lifetime:

  • Handles can be acquired using the page methods , page.$ or or their frame counterparts frame.evaluateHandle, or frame.$$.
  • Once created, handles will retain object from
  • Handles will be automatically disposed once the page or frame they belong to navigates or closes.
  • Handles can be manually disposed using jsHandle.dispose method.

Alternatively, handles can be passed as arguments to function:

  1. // In the page API, you can pass handle as a parameter.
  2. const ulElementHandle = await page.$('ul');
  3. await page.evaluate(uiElement => getComputedStyle(uiElement).getPropertyValue('display'), uiElement);

API reference