Core concepts
Playwright provides a set of APIs to automate Chromium, Firefox and WebKit browsers. By using the Playwright API, you can write JavaScript code to create new browser pages, navigate to URLs and then interact with elements on a page.
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.
- Browser
- Browser contexts
- Pages and frames
- Selectors
- Auto-waiting
- Execution contexts: Node.js and Browser
- Object & Element handles
#
BrowserA Browser
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 contextsA 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.
Browser contexts can also be used to emulate multi-page scenarios involving mobile devices, permissions, locale and color scheme.
#
ExampleThis script logs in on GitHub.com through Chromium, and then reuses the login cookies state in WebKit. This recipe can be used to speed up tests by logging in once and reusing login state.
#
API reference#
Pages and framesA Browser context can have multiple pages. A Page
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.
Read more on page navigation and loading.
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#
SelectorsPlaywright can search for elements using CSS selectors, XPath selectors, HTML attributes like id
, data-test-id
and even text content.
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:
Selectors using the same or different engines can be combined using the >>
separator. For example,
#
Auto-waitingActions 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 visible: 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
You can explicitly wait for an element to appear in the DOM or to become visible:
... or to become hidden or detached
#
API reference- page.click(selector[, options])
- page.fill(selector, value[, options])
- page.waitForSelector(selector[, options])
#
Execution contexts: Node.js and BrowserPlaywright scripts run in your Node.js environment. You page scripts run in the browser page environment. Those environments don't intersect, they are running in different virtual machines in different processes and even 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. Browser globals like
window
and document
can be used in evaluate
.
If the result is a Promise or if the function is asynchronous evaluate will automatically wait until it's resolved:
#
EvaluationFunctions passed inside page.evaluate
can accept parameters. These 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.
Right:
Wrong:
#
API referencepage.evaluate(pageFunction[, arg])
frame.evaluate(pageFunction[, arg])
- Evaluation argument examples
#
Object & Element handlesPlaywright can 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.
There are two types of handles:
JSHandle
to reference any JavaScript objects in the pageElementHandle
to reference DOM elements in the page
Note that since any DOM element in the page is also a JavaScript object,
Playwright's ElementHandle
extends
JSHandle
.
#
Handles Lifecycle- Handles can be acquired using the page methods
page.evaluateHandle
,page.$
orpage.$$
or their frame counterpartsframe.evaluateHandle
,frame.$
orframe.$$
. - Once created, handles will retain object from garbage collection.
- 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.
#
Example: ElementHandleHandles can also be passed as arguments to page.evaluate
function: