diff --git a/README.md b/README.md index d847760be3..beb35fa237 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 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) +###### [API](https://github.com/microsoft/playwright/blob/v0.10.0/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 deleted file mode 100644 index ca720ce2fe..0000000000 --- a/docs/api-0.10.0.md +++ /dev/null @@ -1,3879 +0,0 @@ - -# 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 `