# Playwright API Tip-Of-Tree - API Translations: [中文|Chinese](https://zhaoqize.github.io/playwright-api-zh_CN/#/) - Troubleshooting: [troubleshooting.md](https://github.com/Microsoft/playwright/blob/master/docs/troubleshooting.md) ##### Table of Contents - [Overview](#overview) - [Working with Chrome Extensions](#working-with-chrome-extensions) - [class: Playwright](#class-playwright) * [playwright.connect(options)](#playwrightconnectoptions) * [playwright.createBrowserFetcher([options])](#playwrightcreatebrowserfetcheroptions) * [playwright.defaultArgs([options])](#playwrightdefaultargsoptions) * [playwright.devices](#playwrightdevices) * [playwright.downloadBrowser([options])](#playwrightdownloadbrowseroptions) * [playwright.errors](#playwrighterrors) * [playwright.executablePath()](#playwrightexecutablepath) * [playwright.launch([options])](#playwrightlaunchoptions) - [class: BrowserFetcher](#class-browserfetcher) * [browserFetcher.canDownload(revision)](#browserfetchercandownloadrevision) * [browserFetcher.download(revision[, progressCallback])](#browserfetcherdownloadrevision-progresscallback) * [browserFetcher.localRevisions()](#browserfetcherlocalrevisions) * [browserFetcher.platform()](#browserfetcherplatform) * [browserFetcher.remove(revision)](#browserfetcherremoverevision) * [browserFetcher.revisionInfo(revision)](#browserfetcherrevisioninforevision) - [class: Browser](#class-browser) * [event: 'disconnected'](#event-disconnected) * [browser.browserContexts()](#browserbrowsercontexts) * [browser.chromium](#browserchromium) * [browser.close()](#browserclose) * [browser.defaultContext()](#browserdefaultContext()) * [browser.disconnect()](#browserdisconnect) * [browser.isConnected()](#browserisconnected) * [browser.newContext(options)](#browsernewcontextoptions) * [browser.newPage(options)](#browsernewpageoptions) * [browser.pages()](#browserpages) * [browser.process()](#browserprocess) - [class: BrowserContext](#class-browsercontext) * [browserContext.browser()](#browsercontextbrowser) * [browserContext.clearCookies()](#browsercontextclearcookies) * [browserContext.close()](#browsercontextclose) * [browserContext.cookies([...urls])](#browsercontextcookiesurls) * [browserContext.isIncognito()](#browsercontextisincognito) * [browserContext.newPage()](#browsercontextnewpage) * [browserContext.overrides](#browsercontextoverrides) * [browserContext.pages()](#browsercontextpages) * [browserContext.permissions](#browsercontextpermissions) * [browserContext.setCookies(cookies)](#browsercontextsetcookiescookies) - [class: Overrides](#class-overrides) * [overrides.setGeolocation(options)](#overridessetgeolocationoptions) - [class: Permissions](#class-permissions) * [permissions.clearOverrides()](#permissionsclearoverrides) * [permissions.override(origin, permissions)](#permissionsoverrideorigin-permissions) - [class: Page](#class-page) * [event: 'close'](#event-close) * [event: 'console'](#event-console) * [event: 'dialog'](#event-dialog) * [event: 'domcontentloaded'](#event-domcontentloaded) * [event: 'filechooser'](#event-filechooser) * [event: 'frameattached'](#event-frameattached) * [event: 'framedetached'](#event-framedetached) * [event: 'framenavigated'](#event-framenavigated) * [event: 'load'](#event-load) * [event: 'pageerror'](#event-pageerror) * [event: 'popup'](#event-popup) * [event: 'request'](#event-request) * [event: 'requestfailed'](#event-requestfailed) * [event: 'requestfinished'](#event-requestfinished) * [event: 'response'](#event-response) * [page.$(selector)](#pageselector) * [page.$$(selector)](#pageselector-1) * [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) * [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args-1) * [page.$x(expression)](#pagexexpression) * [page.accessibility](#pageaccessibility) * [page.addScriptTag(options)](#pageaddscripttagoptions) * [page.addStyleTag(options)](#pageaddstyletagoptions) * [page.browser()](#pagebrowser) * [page.browserContext()](#pagebrowsercontext) * [page.click(selector[, options])](#pageclickselector-options) * [page.close([options])](#pagecloseoptions) * [page.content()](#pagecontent) * [page.coverage](#pagecoverage) * [page.dblclick(selector[, options])](#pagedblclickselector-options) * [page.evaluate(pageFunction[, ...args])](#pageevaluatepagefunction-args) * [page.evaluateHandle(pageFunction[, ...args])](#pageevaluatehandlepagefunction-args) * [page.evaluateOnNewDocument(pageFunction[, ...args])](#pageevaluateonnewdocumentpagefunction-args) * [page.exposeFunction(name, playwrightFunction)](#pageexposefunctionname-playwrightfunction) * [page.fill(selector, value)](#pagefillselector-value) * [page.focus(selector)](#pagefocusselector) * [page.frames()](#pageframes) * [page.goBack([options])](#pagegobackoptions) * [page.goForward([options])](#pagegoforwardoptions) * [page.goto(url[, options])](#pagegotourl-options) * [page.hover(selector[, options])](#pagehoverselector-options) * [page.interception](#pageinterception) * [page.isClosed()](#pageisclosed) * [page.keyboard](#pagekeyboard) * [page.mainFrame()](#pagemainframe) * [page.mouse](#pagemouse) * [page.pdf](#pagepdf) * [page.reload([options])](#pagereloadoptions) * [page.screenshot([options])](#pagescreenshotoptions) * [page.select(selector, ...values)](#pageselectselector-values) * [page.setCacheEnabled([enabled])](#pagesetcacheenabledenabled) * [page.setContent(html[, options])](#pagesetcontenthtml-options) * [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) * [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) * [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders) * [page.title()](#pagetitle) * [page.tripleclick(selector[, options])](#pagetripleclickselector-options) * [page.type(selector, text[, options])](#pagetypeselector-text-options) * [page.url()](#pageurl) * [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args) * [page.waitForFileChooser([options])](#pagewaitforfilechooseroptions) * [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args) * [page.waitForNavigation([options])](#pagewaitfornavigationoptions) * [page.waitForRequest(urlOrPredicate[, options])](#pagewaitforrequesturlorpredicate-options) * [page.waitForResponse(urlOrPredicate[, options])](#pagewaitforresponseurlorpredicate-options) * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) * [page.waitForXPath(xpath[, options])](#pagewaitforxpathxpath-options) * [page.workers](#pageworkers) - [class: Worker](#class-worker) * [worker.evaluate(pageFunction[, ...args])](#workerevaluatepagefunction-args) * [worker.evaluateHandle(pageFunction[, ...args])](#workerevaluatehandlepagefunction-args) * [worker.executionContext()](#workerexecutioncontext) * [worker.url()](#workerurl) - [class: Workers](#class-workers) * [event: 'workercreated'](#event-workercreated) * [event: 'workerdestroyed'](#event-workerdestroyed) * [workers.list()](#workerslist) - [class: Accessibility](#class-accessibility) * [accessibility.snapshot([options])](#accessibilitysnapshotoptions) - [class: Keyboard](#class-keyboard) * [keyboard.down(key[, options])](#keyboarddownkey-options) * [keyboard.press(key[, options])](#keyboardpresskey-options) * [keyboard.sendCharacters(text)](#keyboardsendcharacterstext) * [keyboard.type(text[, options])](#keyboardtypetext-options) * [keyboard.up(key)](#keyboardupkey) - [class: Mouse](#class-mouse) * [mouse.click(x, y[, options])](#mouseclickx-y-options) * [mouse.dblclick(x, y[, options])](#mousedblclickx-y-options) * [mouse.down([options])](#mousedownoptions) * [mouse.move(x, y[, options])](#mousemovex-y-options) * [mouse.tripleclick(x, y[, options])](#mousetripleclickx-y-options) * [mouse.up([options])](#mouseupoptions) - [class: PDF](#class-pdf) * [pdf.generate([options])](#pdfgenerateoptions) - [class: Firefox](#class-firefox) * [firefox.wsEndpoint()](#firefoxwsendpoint) - [class: Chromium](#class-chromium) * [event: 'targetchanged'](#event-targetchanged) * [event: 'targetcreated'](#event-targetcreated) * [event: 'targetdestroyed'](#event-targetdestroyed) * [chromium.browserTarget()](#chromiumbrowsertarget) * [chromium.pageTarget(page)](#chromiumpagetargetpage) * [chromium.serviceWorker(target)](#chromiumserviceworkertarget) * [chromium.startTracing(page, [options])](#chromiumstarttracingpage-options) * [chromium.stopTracing()](#chromiumstoptracing) * [chromium.targets(context)](#chromiumtargetscontext) * [chromium.waitForTarget(predicate[, options])](#chromiumwaitfortargetpredicate-options) * [chromium.wsEndpoint()](#chromiumwsendpoint) - [class: Dialog](#class-dialog) * [dialog.accept([promptText])](#dialogacceptprompttext) * [dialog.defaultValue()](#dialogdefaultvalue) * [dialog.dismiss()](#dialogdismiss) * [dialog.message()](#dialogmessage) * [dialog.type()](#dialogtype) - [class: ConsoleMessage](#class-consolemessage) * [consoleMessage.args()](#consolemessageargs) * [consoleMessage.location()](#consolemessagelocation) * [consoleMessage.text()](#consolemessagetext) * [consoleMessage.type()](#consolemessagetype) - [class: Frame](#class-frame) * [frame.$(selector)](#frameselector) * [frame.$$(selector)](#frameselector-1) * [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) * [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args-1) * [frame.$x(expression)](#framexexpression) * [frame.addScriptTag(options)](#frameaddscripttagoptions) * [frame.addStyleTag(options)](#frameaddstyletagoptions) * [frame.childFrames()](#framechildframes) * [frame.click(selector[, options])](#frameclickselector-options) * [frame.content()](#framecontent) * [frame.dblclick(selector[, options])](#framedblclickselector-options) * [frame.evaluate(pageFunction[, ...args])](#frameevaluatepagefunction-args) * [frame.evaluateHandle(pageFunction[, ...args])](#frameevaluatehandlepagefunction-args) * [frame.executionContext()](#frameexecutioncontext) * [frame.fill(selector, value)](#framefillselector-value) * [frame.focus(selector)](#framefocusselector) * [frame.goto(url[, options])](#framegotourl-options) * [frame.hover(selector[, options])](#framehoverselector-options) * [frame.isDetached()](#frameisdetached) * [frame.name()](#framename) * [frame.parentFrame()](#frameparentframe) * [frame.select(selector, ...values)](#frameselectselector-values) * [frame.setContent(html[, options])](#framesetcontenthtml-options) * [frame.title()](#frametitle) * [frame.tripleclick(selector[, options])](#frametripleclickselector-options) * [frame.type(selector, text[, options])](#frametypeselector-text-options) * [frame.url()](#frameurl) * [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args) * [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args) * [frame.waitForNavigation([options])](#framewaitfornavigationoptions) * [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options) * [frame.waitForXPath(xpath[, options])](#framewaitforxpathxpath-options) - [class: ExecutionContext](#class-executioncontext) * [executionContext.evaluate(pageFunction[, ...args])](#executioncontextevaluatepagefunction-args) * [executionContext.evaluateHandle(pageFunction[, ...args])](#executioncontextevaluatehandlepagefunction-args) * [executionContext.frame()](#executioncontextframe) - [class: Interception](#class-interception) * [interception.abort(request, [errorCode])](#interceptionabortrequest-errorcode) * [interception.authenticate(credentials)](#interceptionauthenticatecredentials) * [interception.continue(request, [overrides])](#interceptioncontinuerequest-overrides) * [interception.disable()](#interceptiondisable) * [interception.enable()](#interceptionenable) * [interception.fulfill(request, response)](#interceptionfulfillrequest-response) * [interception.setOfflineMode(enabled)](#interceptionsetofflinemodeenabled) - [class: JSHandle](#class-jshandle) * [jsHandle.asElement()](#jshandleaselement) * [jsHandle.dispose()](#jshandledispose) * [jsHandle.evaluate(pageFunction[, ...args])](#jshandleevaluatepagefunction-args) * [jsHandle.evaluateHandle(pageFunction[, ...args])](#jshandleevaluatehandlepagefunction-args) * [jsHandle.executionContext()](#jshandleexecutioncontext) * [jsHandle.getProperties()](#jshandlegetproperties) * [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname) * [jsHandle.jsonValue()](#jshandlejsonvalue) - [class: ElementHandle](#class-elementhandle) * [elementHandle.$(selector)](#elementhandleselector) * [elementHandle.$$(selector)](#elementhandleselector-1) * [elementHandle.$$eval(selector, pageFunction[, ...args])](#elementhandleevalselector-pagefunction-args) * [elementHandle.$eval(selector, pageFunction[, ...args])](#elementhandleevalselector-pagefunction-args-1) * [elementHandle.$x(expression)](#elementhandlexexpression) * [elementHandle.asElement()](#elementhandleaselement) * [elementHandle.boundingBox()](#elementhandleboundingbox) * [elementHandle.click([options])](#elementhandleclickoptions) * [elementHandle.contentFrame()](#elementhandlecontentframe) * [elementHandle.dblclick([options])](#elementhandledblclickoptions) * [elementHandle.dispose()](#elementhandledispose) * [elementHandle.evaluate(pageFunction[, ...args])](#elementhandleevaluatepagefunction-args) * [elementHandle.evaluateHandle(pageFunction[, ...args])](#elementhandleevaluatehandlepagefunction-args) * [elementHandle.executionContext()](#elementhandleexecutioncontext) * [elementHandle.fill(value)](#elementhandlefillvalue) * [elementHandle.focus()](#elementhandlefocus) * [elementHandle.getProperties()](#elementhandlegetproperties) * [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname) * [elementHandle.hover([options])](#elementhandlehoveroptions) * [elementHandle.isIntersectingViewport()](#elementhandleisintersectingviewport) * [elementHandle.jsonValue()](#elementhandlejsonvalue) * [elementHandle.press(key[, options])](#elementhandlepresskey-options) * [elementHandle.screenshot([options])](#elementhandlescreenshotoptions) * [elementHandle.select(...values)](#elementhandleselectvalues) * [elementHandle.setInputFiles(...files)](#elementhandlesetinputfilesfiles) * [elementHandle.toString()](#elementhandletostring) * [elementHandle.tripleclick([options])](#elementhandletripleclickoptions) * [elementHandle.type(text[, options])](#elementhandletypetext-options) - [class: Request](#class-request) * [request.failure()](#requestfailure) * [request.frame()](#requestframe) * [request.headers()](#requestheaders) * [request.isNavigationRequest()](#requestisnavigationrequest) * [request.method()](#requestmethod) * [request.postData()](#requestpostdata) * [request.redirectChain()](#requestredirectchain) * [request.resourceType()](#requestresourcetype) * [request.response()](#requestresponse) * [request.url()](#requesturl) - [class: Response](#class-response) * [response.buffer()](#responsebuffer) * [response.frame()](#responseframe) * [response.headers()](#responseheaders) * [response.json()](#responsejson) * [response.ok()](#responseok) * [response.remoteAddress()](#responseremoteaddress) * [response.request()](#responserequest) * [response.status()](#responsestatus) * [response.statusText()](#responsestatustext) * [response.text()](#responsetext) * [response.url()](#responseurl) - [class: Target](#class-target) * [target.browser()](#targetbrowser) * [target.browserContext()](#targetbrowsercontext) * [target.createCDPSession()](#targetcreatecdpsession) * [target.opener()](#targetopener) * [target.page()](#targetpage) * [target.type()](#targettype) * [target.url()](#targeturl) - [class: CDPSession](#class-cdpsession) * [cdpSession.detach()](#cdpsessiondetach) * [cdpSession.send(method[, params])](#cdpsessionsendmethod-params) - [class: Coverage](#class-coverage) * [coverage.startCSSCoverage([options])](#coveragestartcsscoverageoptions) * [coverage.startJSCoverage([options])](#coveragestartjscoverageoptions) * [coverage.stopCSSCoverage()](#coveragestopcsscoverage) * [coverage.stopJSCoverage()](#coveragestopjscoverage) - [class: TimeoutError](#class-timeouterror) - [class: Selector](#class-selector) * [selector.selector](#selectorselector) * [selector.visibility](#selectorvisibility) ### Overview Playwright is a Node library which provides a high-level API to control Chromium or Chrome over the DevTools Protocol. The Playwright API is hierarchical and mirrors the browser structure. > **NOTE** On the following diagram, faded entities are not currently represented in Playwright. ![playwright overview](https://user-images.githubusercontent.com/746130/40333229-5df5480c-5d0c-11e8-83cb-c3e371de7374.png) - [`Playwright`](#class-playwright) communicates with the browser using [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). - [`Browser`](#class-browser) instance can own multiple browser contexts. - [`BrowserContext`](#class-browsercontext) instance defines a browsing session and can own multiple pages. - [`Page`](#class-page) has at least one frame: main frame. There might be other frames created by [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) or [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) tags. - [`Frame`](#class-frame) has at least one execution context - the default execution context - where the frame's JavaScript is executed. A Frame might have additional execution contexts that are associated with [extensions](https://developer.chrome.com/extensions). - [`Worker`](#class-worker) has a single execution context and facilitates interacting with [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). (Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing)) ### Working with Chrome Extensions Playwright can be used for testing Chrome Extensions. > **NOTE** Extensions in Chrome / Chromium currently only work in non-headless mode. The following is code for getting a handle to the [background page](https://developer.chrome.com/extensions/background_pages) of an extension whose source is located in `./my-extension`: ```js const playwright = require('playwright'); (async () => { const pathToExtension = require('path').join(__dirname, 'my-extension'); const browser = await playwright.launch({ headless: false, args: [ `--disable-extensions-except=${pathToExtension}`, `--load-extension=${pathToExtension}` ] }); const targets = await browser.chromium.targets(); const backgroundPageTarget = targets.find(target => target.type() === 'background_page'); const backgroundPage = await backgroundPageTarget.page(); // Test the background page as you would any other page. await browser.close(); })(); ``` > **NOTE** It is not yet possible to test extension popups or content scripts. ### class: Playwright Playwright module provides a method to launch a Chromium instance. The following is a typical example of using Playwright to drive automation: ```js const playwright = require('playwright'); (async () => { const browser = await playwright.launch(); const page = await browser.newPage(); await page.goto('https://www.google.com'); // other actions... await browser.close(); })(); ``` #### playwright.connect(options) - `options` <[Object]> - `browserWSEndpoint` a [browser websocket endpoint](#browserwsendpoint) to connect to. - `browserURL` a browser url to connect to, in format `http://${host}:${port}`. Use interchangeably with `browserWSEndpoint` to let Playwright fetch it from [metadata endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target). - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - `transport` <[ConnectionTransport]> **Experimental** Specify a custom transport object for Playwright to use. - returns: <[Promise]<[Browser]>> This methods attaches Playwright to an existing Chromium instance. #### playwright.createBrowserFetcher([options]) - `options` <[Object]> - `host` <[string]> A download host to be used. Defaults to `https://storage.googleapis.com`. - `path` <[string]> A path for the downloads folder. Defaults to `/.local-chromium`, where `` is playwright's package root. - `platform` <[string]> Possible values are: `mac`, `win32`, `win64`, `linux`. Defaults to the current platform. - returns: <[BrowserFetcher]> #### playwright.defaultArgs([options]) - `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - `headless` <[boolean]> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/). - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. - returns: <[Array]<[string]>> The default flags that Chromium will be launched with. #### playwright.devices - returns: <[Object]> Returns a list of devices to be used with [`page.emulate(options)`](#pageemulateoptions). Actual list of devices can be found in [lib/DeviceDescriptors.js](https://github.com/Microsoft/playwright/blob/master/lib/DeviceDescriptors.js). ```js const playwright = require('playwright'); const iPhone = playwright.devices['iPhone 6']; (async () => { const browser = await playwright.launch(); const page = await browser.newPage(); await page.emulate(iPhone); await page.goto('https://www.google.com'); // other actions... await browser.close(); })(); ``` > **NOTE** The old way (Playwright versions <= v1.14.0) devices can be obtained with `require('playwright/DeviceDescriptors')`. #### playwright.downloadBrowser([options]) - `options` <[Object]> - `onProgress` <[function]([number], [number])> A function that will be called with two arguments: - `downloadedBytes` <[number]> how many bytes have been downloaded - `totalBytes` <[number]> how large is the total download. - returns: <[Promise]<[Object]>> Resolves with revision information when the revision is downloaded and extracted - `revision` <[string]> the revision the info was created from - `folderPath` <[string]> path to the extracted revision folder - `executablePath` <[string]> path to the revision executable - `url` <[string]> URL this revision can be downloaded from - `local` <[boolean]> whether the revision is locally available on disk Downloads the default browser that Playwright controls. The browser is usually around 100mb. #### playwright.errors - returns: <[Object]> - `TimeoutError` <[function]> A class of [TimeoutError]. Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) might fail if the selector doesn't match any nodes during the given timeframe. For certain types of errors Playwright uses specific error classes. These classes are available via [`playwright.errors`](#playwrighterrors) An example of handling a timeout error: ```js try { await page.waitForSelector('.foo'); } catch (e) { if (e instanceof playwright.errors.TimeoutError) { // Do something if this is a timeout. } } ``` > **NOTE** The old way (Playwright versions <= v1.14.0) errors can be obtained with `require('playwright/Errors')`. #### playwright.executablePath() - returns: <[string]> A path where Playwright expects to find bundled Chromium. #### playwright.launch([options]) - `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - `headless` <[boolean]> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. - `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of the bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only [guaranteed to work](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, use at your own risk. - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/). - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`playwright.defaultArgs()`](#playwrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. - `pipe` <[boolean]> Connects to the browser over a pipe instead of a WebSocket. Defaults to `false`. - returns: <[Promise]<[Browser]>> Promise which resolves to browser instance. You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments: ```js const browser = await playwright.launch({ ignoreDefaultArgs: ['--mute-audio'] }); ``` > **NOTE** Playwright can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. > > If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. > > In [playwright.launch([options])](#playwrightlaunchoptions) above, any mention of Chromium also applies to Chrome. > > See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. ### class: BrowserFetcher BrowserFetcher can download and manage different versions of Chromium. BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/). An example of using BrowserFetcher to download a specific version of Chromium and running Playwright against it: ```js const browserFetcher = playwright.createBrowserFetcher(); const revisionInfo = await browserFetcher.download('533271'); const browser = await playwright.launch({executablePath: revisionInfo.executablePath}) ``` > **NOTE** BrowserFetcher is not designed to work concurrently with other > instances of BrowserFetcher that share the same downloads directory. #### browserFetcher.canDownload(revision) - `revision` <[string]> a revision to check availability. - returns: <[Promise]<[boolean]>> returns `true` if the revision could be downloaded from the host. The method initiates a HEAD request to check if the revision is available. #### browserFetcher.download(revision[, progressCallback]) - `revision` <[string]> a revision to download. - `progressCallback` <[function]([number], [number])> A function that will be called with two arguments: - `downloadedBytes` <[number]> how many bytes have been downloaded - `totalBytes` <[number]> how large is the total download. - returns: <[Promise]<[Object]>> Resolves with revision information when the revision is downloaded and extracted - `revision` <[string]> the revision the info was created from - `folderPath` <[string]> path to the extracted revision folder - `executablePath` <[string]> path to the revision executable - `url` <[string]> URL this revision can be downloaded from - `local` <[boolean]> whether the revision is locally available on disk The method initiates a GET request to download the revision from the host. #### browserFetcher.localRevisions() - returns: <[Promise]<[Array]<[string]>>> A list of all revisions available locally on disk. #### browserFetcher.platform() - returns: <[string]> One of `mac`, `linux`, `win32` or `win64`. #### browserFetcher.remove(revision) - `revision` <[string]> a revision to remove. The method will throw if the revision has not been downloaded. - returns: <[Promise]> Resolves when the revision has been removed. #### browserFetcher.revisionInfo(revision) - `revision` <[string]> a revision to get info for. - returns: <[Object]> - `revision` <[string]> the revision the info was created from - `folderPath` <[string]> path to the extracted revision folder - `executablePath` <[string]> path to the revision executable - `url` <[string]> URL this revision can be downloaded from - `local` <[boolean]> whether the revision is locally available on disk ### class: Browser * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) A Browser is created when Playwright connects to a Chromium instance, either through [`playwright.launch`](#playwrightlaunchoptions) or [`playwright.connect`](#playwrightconnectoptions). An example of using a [Browser] to create a [Page]: ```js const playwright = require('playwright'); (async () => { const browser = await playwright.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); await browser.close(); })(); ``` An example of disconnecting from and reconnecting to a [Browser]: ```js const playwright = require('playwright'); (async () => { const browser = await playwright.launch(); // Store the endpoint to be able to reconnect to Chromium const browserWSEndpoint = browser.chromium.wsEndpoint(); // Disconnect playwright from Chromium browser.disconnect(); // Use the endpoint to reestablish a connection const browser2 = await playwright.connect({browserWSEndpoint}); // Close Chromium await browser2.close(); })(); ``` #### event: 'disconnected' Emitted when Playwright gets disconnected from the Chromium instance. This might happen because of one of the following: - Chromium is closed or crashed - The [`browser.disconnect`](#browserdisconnect) method was called #### browser.browserContexts() - returns: <[Array]<[BrowserContext]>> Returns an array of all open browser contexts. In a newly created browser, this will return a single instance of [BrowserContext]. #### browser.chromium - returns: <[Chromium]> #### browser.close() - returns: <[Promise]> Closes Chromium and all of its pages (if any were opened). The [Browser] object itself is considered to be disposed and cannot be used anymore. #### browser.defaultContext() - returns: <[BrowserContext]> Returns the default browser context. The default browser context can not be closed. #### browser.disconnect() Disconnects Playwright from the browser, but leaves the Chromium process running. After calling `disconnect`, the [Browser] object is considered disposed and cannot be used anymore. #### browser.isConnected() - returns: <[boolean]> Indicates that the browser is connected. #### browser.newContext(options) - `options` <[Object]> - `ignoreHTTPSErrors` Whether to ignore HTTPS errors during navigation. Defaults to `false`. - `bypassCSP` Toggles bypassing page's Content-Security-Policy. - `viewport` Sets a consistent viewport for each page. Defaults to an 800x600 viewport. `null` disables the default viewport. - `width` <[number]> page width in pixels. - `height` <[number]> page height in pixels. - `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`. - `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`. - `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false` - `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`. - `userAgent` Specific user agent to use in this page - `mediaType` Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. - `colorScheme` Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. - `javaScriptEnabled` Whether or not to enable or disable JavaScript in the page. Defaults to true. - `timezoneId` Changes the timezone of the page. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. - returns: <[Promise]<[BrowserContext]>> Creates a new browser context. It won't share cookies/cache with other browser contexts. ```js (async () => { const browser = await playwright.launch(); // Create a new incognito browser context. const context = await browser.newContext(); // Create a new page in a pristine context. const page = await context.newPage(); // Do stuff await page.goto('https://example.com'); })(); ``` #### browser.newPage(options) - `options` <[Object]> - `ignoreHTTPSErrors` Whether to ignore HTTPS errors during navigation. Defaults to `false`. - `bypassCSP` Toggles bypassing page's Content-Security-Policy. - `viewport` Sets a consistent viewport for each page. Defaults to an 800x600 viewport. `null` disables the default viewport. - `width` <[number]> page width in pixels. - `height` <[number]> page height in pixels. - `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`. - `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`. - `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false` - `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`. - `userAgent` Specific user agent to use in this page - `mediaType` Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. - `colorScheme` Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. - `javaScriptEnabled` Whether or not to enable or disable JavaScript in the page. Defaults to true. - `timezoneId` Changes the timezone of the page. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. Promise which resolves to a new [Page] object. The [Page] is created in a new browser context that it will own. Closing this page will close the context. #### browser.pages() - returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [target.page()](#targetpage). An array of all pages inside the Browser. In case of multiple browser contexts, the method will return an array with all the pages in all browser contexts. #### browser.process() - returns: Spawned browser process. Returns `null` if the browser instance was created with [`playwright.connect`](#playwrightconnectoptions) method. ### class: BrowserContext * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method `browser.newPage()` creates a page in the default browser context. If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser context. Playwright allows creation of "incognito" browser contexts with `browser.newContext()` method. "Incognito" browser contexts don't write any browsing data to disk. ```js // Create a new incognito browser context const context = await browser.newContext(); // Create a new page inside context. const page = await context.newPage(); // ... do stuff with page ... await page.goto('https://example.com'); // Dispose context once it's no longer needed. await context.close(); ``` #### browserContext.browser() - returns: <[Browser]> The browser this browser context belongs to. #### browserContext.clearCookies() - returns: <[Promise]> Clears context bookies. #### browserContext.close() - returns: <[Promise]> Closes the browser context. All the targets that belong to the browser context will be closed. > **NOTE** only incognito browser contexts can be closed. #### browserContext.cookies([...urls]) - `...urls` <...[string]> - returns: <[Promise]<[Array]<[Object]>>> - `name` <[string]> - `value` <[string]> - `domain` <[string]> - `path` <[string]> - `expires` <[number]> Unix time in seconds. - `size` <[number]> - `httpOnly` <[boolean]> - `secure` <[boolean]> - `session` <[boolean]> - `sameSite` <"Strict"|"Lax"|"None"> If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs are returned. #### browserContext.isIncognito() - returns: <[boolean]> Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context. > **NOTE** the default browser context cannot be closed. #### browserContext.newPage() - returns: <[Promise]<[Page]>> Creates a new page in the browser context. #### browserContext.overrides - returns: <[Overrides]> #### browserContext.pages() - returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [target.page()](#targetpage). An array of all pages inside the browser context. #### browserContext.permissions - returns: <[Permissions]> #### browserContext.setCookies(cookies) - `cookies` <[Array]<[Object]>> - `name` <[string]> **required** - `value` <[string]> **required** - `url` <[string]> either url or domain / path are **required** - `domain` <[string]> either url or domain / path are **required** - `path` <[string]> either url or domain / path are **required** - `expires` <[number]> Unix time in seconds. - `httpOnly` <[boolean]> - `secure` <[boolean]> - `sameSite` <"Strict"|"Lax"|"None"> - returns: <[Promise]> ```js await browserContext.setCookies([cookieObject1, cookieObject2]); ``` ### class: Overrides #### overrides.setGeolocation(options) - `options` <[Object]> - `latitude` <[number]> Latitude between -90 and 90. - `longitude` <[number]> Longitude between -180 and 180. - `accuracy` <[number]> Optional non-negative accuracy value. - returns: <[Promise]> Sets the page's geolocation. ```js await browserContext.overrides.setGeolocation({latitude: 59.95, longitude: 30.31667}); ``` > **NOTE** Consider using [browserContext.permissions.override](#permissionsoverrideorigin-permissions) to grant permissions for the page to read its geolocation. ### class: Permissions #### permissions.clearOverrides() - returns: <[Promise]> Clears all permission overrides for the browser context. ```js const context = browser.defaultContext(); context.permissions.override('https://example.com', ['clipboard-read']); // do stuff .. context.permissions.clearOverrides(); ``` #### permissions.override(origin, permissions) - `origin` <[string]> The [origin] to grant permissions to, e.g. "https://example.com". - `permissions` <[Array]<[string]>> An array of permissions to grant. All permissions that are not listed here will be automatically denied. Permissions can be one of the following values: - `'geolocation'` - `'midi'` - `'midi-sysex'` (system-exclusive midi) - `'notifications'` - `'push'` - `'camera'` - `'microphone'` - `'background-sync'` - `'ambient-light-sensor'` - `'accelerometer'` - `'gyroscope'` - `'magnetometer'` - `'accessibility-events'` - `'clipboard-read'` - `'clipboard-write'` - `'payment-handler'` - returns: <[Promise]> ```js const context = browser.defaultContext(); await context.permissions.override('https://html5demos.com', ['geolocation']); ``` ### class: Page * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] instance might have multiple [Page] instances. This example creates a page, navigates it to a URL, and then saves a screenshot: ```js const playwright = require('playwright'); (async () => { const browser = await playwright.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); await page.screenshot({path: 'screenshot.png'}); await browser.close(); })(); ``` The Page class emits various events (described below) which can be handled using any of Node's native [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or `removeListener`. This example logs a message for a single page `load` event: ```js page.once('load', () => console.log('Page loaded!')); ``` To unsubscribe from events use the `removeListener` method: ```js function logRequest(interceptedRequest) { console.log('A request was made:', interceptedRequest.url()); } page.on('request', logRequest); // Sometime later... page.removeListener('request', logRequest); ``` #### event: 'close' Emitted when the page closes. #### event: 'console' - <[ConsoleMessage]> 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: ```js page.on('console', msg => { for (let i = 0; i < msg.args().length; ++i) console.log(`${i}: ${msg.args()[i]}`); }); page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); ``` #### event: 'dialog' - <[Dialog]> Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [Dialog]'s [accept](#dialogacceptprompttext) or [dismiss](#dialogdismiss) methods. #### event: 'domcontentloaded' Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. #### event: 'filechooser' - <[Object]> - `element` <[ElementHandle]> handle to the input element that was clicked - `multiple` <[boolean]> Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection. Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can respond to it via setting the input files using [`elementHandle.setInputFiles`](#elementhandlesetinputfilesfiles). ```js page.on('filechooser', async ({element, multiple}) => { await element.setInputFiles('/tmp/myfile.pdf'); }); ``` #### event: 'frameattached' - <[Frame]> Emitted when a frame is attached. #### event: 'framedetached' - <[Frame]> Emitted when a frame is detached. #### event: 'framenavigated' - <[Frame]> Emitted when a frame is navigated to a new url. #### event: 'load' Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. #### event: 'pageerror' - <[Error]> The exception message Emitted when an uncaught exception happens within the page. #### event: 'popup' - <[Page]> Page corresponding to "popup" window Emitted when the page opens a new tab or window. ```js const [popup] = await Promise.all([ new Promise(resolve => page.once('popup', resolve)), page.click('a[target=_blank]'), ]); ``` ```js const [popup] = await Promise.all([ new Promise(resolve => page.once('popup', resolve)), page.evaluate(() => window.open('https://example.com')), ]); ``` #### event: 'request' - <[Request]> Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see `page.interception.enable()`. #### event: 'requestfailed' - <[Request]> Emitted when a request fails, for example by timing out. > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`'requestfinished'`](#event-requestfinished) event and not with [`'requestfailed'`](#event-requestfailed). #### event: 'requestfinished' - <[Request]> Emitted when a request finishes successfully. #### event: 'response' - <[Response]> Emitted when a [response] is received. #### page.$(selector) - `selector` <[string]|[Selector]> A [selector] to query page for - returns: <[Promise]> The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolves to `null`. Shortcut for [page.mainFrame().$(selector)](#frameselector). #### page.$$(selector) - `selector` <[string]|[Selector]> A [selector] to query page for - returns: <[Promise]<[Array]<[ElementHandle]>>> The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`. Shortcut for [page.mainFrame().$$(selector)](#frameselector-1). #### page.$$eval(selector, pageFunction[, ...args]) - `selector` <[string]|[Selector]> A [selector] to query page for - `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes it as the first argument to `pageFunction`. If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value. Examples: ```js const divsCounts = await page.$$eval('div', divs => divs.length); ``` #### page.$eval(selector, pageFunction[, ...args]) - `selector` <[string]|[Selector]> A [selector] to query page for - `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` This method runs `document.querySelector` within the page and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error. If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return its value. Examples: ```js 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 => e.outerHTML); ``` Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector-pagefunction-args). #### page.$x(expression) - `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate). - returns: <[Promise]<[Array]<[ElementHandle]>>> The method evaluates the XPath expression. Shortcut for [page.mainFrame().$x(expression)](#framexexpression) #### page.accessibility - returns: <[Accessibility]> #### page.addScriptTag(options) - `options` <[Object]> - `url` <[string]> URL of a script to be added. - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `content` <[string]> Raw JavaScript content to be injected into frame. - `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. - returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame. Adds a `