From 2e0f3e3e01fa8b72a912b5bfddd169cd867527a9 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Wed, 5 Feb 2020 07:29:06 -0800 Subject: [PATCH] docs: split docs to npm version and latest (#846) --- README.md | 2 +- docs/api-0.10.0.md | 3879 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 3880 insertions(+), 1 deletion(-) create mode 100644 docs/api-0.10.0.md diff --git a/README.md b/README.md index 721ae8b917..d847760be3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Playwright [![npm version](https://img.shields.io/npm/v/playwright.svg?style=flat)](https://www.npmjs.com/package/playwright) [![Chromium version](https://img.shields.io/badge/chromium-81.0.4044-blue.svg)](https://www.chromium.org/Home) [![Firefox version](https://img.shields.io/badge/firefox-73.0b3-blue.svg)](https://www.mozilla.org/en-US/firefox/new/) [![WebKit version](https://img.shields.io/badge/webkit-13.0.4-blue.svg)](https://webkit.org/) [![Join Slack](https://img.shields.io/badge/join-slack-infomational)](https://join.slack.com/t/playwright/shared_invite/enQtOTEyMTUxMzgxMjIwLThjMDUxZmIyNTRiMTJjNjIyMzdmZDA3MTQxZWUwZTFjZjQwNGYxZGM5MzRmNzZlMWI5ZWUyOTkzMjE5Njg1NDg) -###### [API](https://github.com/microsoft/playwright/blob/master/docs/api.md) | [FAQ](#faq) | [Contributing](#contributing) +###### [API v0.10.0](https://github.com/microsoft/playwright/blob/master/docs/api-0.10.0.md) | [API latest](https://github.com/microsoft/playwright/blob/master/docs/api.md) | [FAQ](#faq) | [Contributing](#contributing) Playwright is a Node library to automate the [Chromium](https://www.chromium.org/Home), [WebKit](https://webkit.org/) and [Firefox](https://www.mozilla.org/en-US/firefox/new/) browsers with a single API. It enables **cross-browser** web automation that is **ever-green**, **capable**, **reliable** and **fast**. diff --git a/docs/api-0.10.0.md b/docs/api-0.10.0.md new file mode 100644 index 0000000000..ca720ce2fe --- /dev/null +++ b/docs/api-0.10.0.md @@ -0,0 +1,3879 @@ + +# Playwright API v0.10.0 + + +##### Table of Contents + + +- [Playwright module](#playwright-module) +- [class: Browser](#class-browser) +- [class: BrowserContext](#class-browsercontext) +- [class: Page](#class-page) +- [class: Frame](#class-frame) +- [class: ElementHandle](#class-elementhandle) +- [class: JSHandle](#class-jshandle) +- [class: ConsoleMessage](#class-consolemessage) +- [class: Dialog](#class-dialog) +- [class: Keyboard](#class-keyboard) +- [class: Mouse](#class-mouse) +- [class: Request](#class-request) +- [class: Response](#class-response) +- [class: Selectors](#class-selectors) +- [class: WebSocket](#class-websocket) +- [class: TimeoutError](#class-timeouterror) +- [class: Accessibility](#class-accessibility) +- [class: Coverage](#class-coverage) +- [class: Worker](#class-worker) +- [class: BrowserApp](#class-browserapp) +- [class: BrowserType](#class-browsertype) +- [class: ChromiumBrowser](#class-chromiumbrowser) +- [class: ChromiumSession](#class-chromiumsession) +- [class: ChromiumTarget](#class-chromiumtarget) +- [class: FirefoxBrowser](#class-firefoxbrowser) +- [class: WebKitBrowser](#class-webkitbrowser) +- [Working with selectors](#working-with-selectors) +- [Working with Chrome Extensions](#working-with-chrome-extensions) + + +### Playwright module + +Playwright module provides a method to launch a browser instance. +The following is a typical example of using Playwright to drive automation: +```js +const { chromium, firefox, webkit } = require('playwright'); + +(async () => { + const browser = await chromium.launch(); // Or 'firefox' or 'webkit'. + const context = await browser.newContext(); + const page = await context.newPage('http://example.com'); + // other actions... + await browser.close(); +})(); +``` + +By default, the `playwright` NPM package automatically downloads browser executables during installation. The `playwright-core` NPM package can be used to skip automatic downloads. + + +- [playwright.chromium](#playwrightchromium) +- [playwright.devices](#playwrightdevices) +- [playwright.errors](#playwrighterrors) +- [playwright.firefox](#playwrightfirefox) +- [playwright.selectors](#playwrightselectors) +- [playwright.webkit](#playwrightwebkit) + + +#### playwright.chromium +- returns: <[BrowserType]> + +This object can be used to launch or connect to Chromium, returning instances of [ChromiumBrowser]. + +#### playwright.devices +- returns: <[Object]> + +Returns a list of devices to be used with [`browser.newContext(options)`](#browsernewcontextoptions). Actual list of +devices can be found in [src/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/deviceDescriptors.ts). + +```js +const { webkit, devices } = require('playwright'); +const iPhone = devices['iPhone 6']; + +(async () => { + const browser = await webkit.launch(); + const context = await browser.newContext({ + viewport: iPhone.viewport, + userAgent: iPhone.userAgent + }); + const page = await context.newPage('http://example.com'); + // other actions... + await browser.close(); +})(); +``` + +#### 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 [`browserType.errors`](#browsertypeerrors) or [`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. + } +} +``` + +#### playwright.firefox +- returns: <[BrowserType]> + +This object can be used to launch or connect to Firefox, returning instances of [FirefoxBrowser]. + +#### playwright.selectors +- returns: <[Selectors]> + +Selectors can be used to install custom selector engines. See [Working with selectors](#working-with-selectors) for more information. + +#### playwright.webkit +- returns: <[BrowserType]> + +This object can be used to launch or connect to WebKit, returning instances of [WebKitBrowser]. + + +### class: Browser + +* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) + +A Browser is created when Playwright connects to a browser instance, either through [`browserType.launch`](#browsertypelaunchoptions) or [`browserType.connect`](#browsertypeconnectoptions). + +An example of using a [Browser] to create a [Page]: +```js +const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'. + +(async () => { + const browser = await firefox.launch(); + const context = await browser.newContext(); + const page = await context.newPage('https://example.com'); + await browser.close(); +})(); +``` + +An example of launching a browser executable and connecting to a [Browser] later: +```js +const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. + +(async () => { + const browserApp = await webkit.launchBrowserApp({ webSocket: true }); + const connectOptions = browserApp.connectOptions(); + // Use connect options later to establish a connection. + const browser = await webkit.connect(connectOptions); + // Close browser instance. + await browserApp.close(); +})(); +``` + +See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [browserType.connect(options)](#browsertypeconnectoptions) and [browserType.launch(options)](#browsertypelaunchoptions) always return a specific browser instance, based on the browser being connected to or launched. + + +- [event: 'disconnected'](#event-disconnected) +- [browser.browserContexts()](#browserbrowsercontexts) +- [browser.close()](#browserclose) +- [browser.defaultContext()](#browserdefaultcontext) +- [browser.disconnect()](#browserdisconnect) +- [browser.isConnected()](#browserisconnected) +- [browser.newContext(options)](#browsernewcontextoptions) + + +#### event: 'disconnected' +Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following: +- Browser application 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.close() +- returns: <[Promise]> + +Closes browser 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() +- returns: <[Promise]> + +Disconnects Browser from the browser application, but leaves the application 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`. + - `userAgent` Specific user agent to use in this context. + - `javaScriptEnabled` Whether or not to enable or disable JavaScript in the context. Defaults to true. + - `timezoneId` Changes the timezone of the context. 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. + - `geolocation` <[Object]> + - `latitude` <[number]> Latitude between -90 and 90. + - `longitude` <[number]> Longitude between -180 and 180. + - `accuracy` <[number]> Optional non-negative accuracy value. + - `permissions` <[Object]> A map from origin keys to permissions values. See [browserContext.setPermissions]((#browsercontextsetpermissionsorigin-permissions)) for more details. +- returns: <[Promise]<[BrowserContext]>> + +Creates a new browser context. It won't share cookies/cache with other browser contexts. + +```js +(async () => { + const browser = await playwright.firefox.launch(); // Or 'chromium' or 'webkit'. + // Create a new incognito browser context. + const context = await browser.newContext(); + // Create a new page in a pristine context. + const page = await context.newPage('https://example.com'); +})(); +``` + +### class: BrowserContext + +* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) + +BrowserContexts provide a way to operate multiple independent browser sessions. + +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('https://example.com'); +// Dispose context once it's no longer needed. +await context.close(); +``` + + +- [browserContext.clearCookies()](#browsercontextclearcookies) +- [browserContext.clearPermissions()](#browsercontextclearpermissions) +- [browserContext.close()](#browsercontextclose) +- [browserContext.cookies([...urls])](#browsercontextcookiesurls) +- [browserContext.newPage(url)](#browsercontextnewpageurl) +- [browserContext.pages()](#browsercontextpages) +- [browserContext.setCookies(cookies)](#browsercontextsetcookiescookies) +- [browserContext.setGeolocation(geolocation)](#browsercontextsetgeolocationgeolocation) +- [browserContext.setPermissions(origin, permissions[])](#browsercontextsetpermissionsorigin-permissions) + + +#### browserContext.clearCookies() +- returns: <[Promise]> + +Clears context bookies. + +#### browserContext.clearPermissions() +- returns: <[Promise]> + +Clears all permission overrides for the browser context. + +```js +const context = browser.defaultContext(); +context.setPermissions('https://example.com', ['clipboard-read']); +// do stuff .. +context.clearPermissions(); +``` + +#### 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. + +> **NOTE** the default browser context cannot be closed. + +#### browserContext.newPage(url) +- `url` Optional url to navigate the page to. +- returns: <[Promise]<[Page]>> + +Creates a new page in the browser context and optionally navigates it to the specified URL. + +#### 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.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]); +``` + +#### browserContext.setGeolocation(geolocation) +- `geolocation` <[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. Passing null or undefined emulates position unavailable. + +```js +await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667}); +``` + +> **NOTE** Consider using [browserContext.setPermissions](#browsercontextsetpermissions-permissions) to grant permissions for the page to read its geolocation. + +#### browserContext.setPermissions(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.setPermissions('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 in a [Browser], or an [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 { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. + +(async () => { + const browser = await webkit.launch(); + const context = await browser.newContext(); + const page = await context.newPage('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'](#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) +- [event: 'websocket'](#event-websocket) +- [event: 'workercreated'](#event-workercreated) +- [event: 'workerdestroyed'](#event-workerdestroyed) +- [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.$wait(selector, pageFunction[, options[, ...args]])](#pagewaitselector-pagefunction-options-args) +- [page.accessibility](#pageaccessibility) +- [page.addScriptTag(options)](#pageaddscripttagoptions) +- [page.addStyleTag(options)](#pageaddstyletagoptions) +- [page.authenticate(credentials)](#pageauthenticatecredentials) +- [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.emulateMedia(options)](#pageemulatemediaoptions) +- [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, options)](#pagefillselector-value-options) +- [page.focus(selector, options)](#pagefocusselector-options) +- [page.frames()](#pageframes) +- [page.goBack([options])](#pagegobackoptions) +- [page.goForward([options])](#pagegoforwardoptions) +- [page.goto(url[, options])](#pagegotourl-options) +- [page.hover(selector[, options])](#pagehoverselector-options) +- [page.isClosed()](#pageisclosed) +- [page.keyboard](#pagekeyboard) +- [page.mainFrame()](#pagemainframe) +- [page.mouse](#pagemouse) +- [page.opener()](#pageopener) +- [page.pdf([options])](#pagepdfoptions) +- [page.reload([options])](#pagereloadoptions) +- [page.screenshot([options])](#pagescreenshotoptions) +- [page.select(selector, value, options)](#pageselectselector-value-options) +- [page.setCacheEnabled([enabled])](#pagesetcacheenabledenabled) +- [page.setContent(html[, options])](#pagesetcontenthtml-options) +- [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) +- [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) +- [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders) +- [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled) +- [page.setRequestInterception(enabled)](#pagesetrequestinterceptionenabled) +- [page.setViewport(viewport)](#pagesetviewportviewport) +- [page.title()](#pagetitle) +- [page.tripleclick(selector[, options])](#pagetripleclickselector-options) +- [page.type(selector, text[, options])](#pagetypeselector-text-options) +- [page.url()](#pageurl) +- [page.viewport()](#pageviewport) +- [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args) +- [page.waitForEvent(event[, optionsOrPredicate])](#pagewaitforeventevent-optionsorpredicate) +- [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args) +- [page.waitForLoadState([options])](#pagewaitforloadstateoptions) +- [page.waitForNavigation([options])](#pagewaitfornavigationoptions) +- [page.waitForRequest(urlOrPredicate[, options])](#pagewaitforrequesturlorpredicate-options) +- [page.waitForResponse(urlOrPredicate[, options])](#pagewaitforresponseurlorpredicate-options) +- [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) +- [page.workers()](#pageworkers) + + +#### 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.setRequestInterception(true)`. + +#### 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. + +#### event: 'websocket' +- <[WebSocket]> websocket + +Emitted when a <[WebSocket]> is opened. + +#### event: 'workercreated' +- <[Worker]> + +Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page. + +#### event: 'workerdestroyed' +- <[Worker]> + +Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is terminated. + +#### page.$(selector) +- `selector` <[string]> 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]> 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]> 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]> 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.$wait(selector, pageFunction[, options[, ...args]]) +- `selector` <[string]> A selector to query page for +- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context +- `options` <[Object]> Optional waiting parameters + - `polling` <[number]|"raf"|"mutation"> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values: + - `'raf'` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes. + - `'mutation'` - to execute `pageFunction` on every DOM mutation. + - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method. +- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` +- returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value + +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.$wait` would wait for the promise to resolve and return its value. The function +is being called on the element periodically until either timeout expires or the function returns the truthy value. + +Shortcut for [page.mainFrame().$wait(selector, pageFunction[, options[, ...args]])](#framewaitselector-pagefunction-options-args). + +#### 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 `