diff --git a/docs/src/api-body.md b/docs/src/api-body.md deleted file mode 100644 index b0577962b0..0000000000 --- a/docs/src/api-body.md +++ /dev/null @@ -1,5701 +0,0 @@ -# class: Playwright - -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 page = await browser.newPage(); - await page.goto('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. - -## property: Playwright.chromium -- type: <[BrowserType]> - -This object can be used to launch or connect to Chromium, returning instances of [ChromiumBrowser]. - -## property: Playwright.devices -- type: <[Object]> - -Returns a list of devices to be used with [`method: Browser.newContext`] or [`method: Browser.newPage`]. Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts). - -```js -const { webkit, devices } = require('playwright'); -const iPhone = devices['iPhone 6']; - -(async () => { - const browser = await webkit.launch(); - const context = await browser.newContext({ - ...iPhone - }); - const page = await context.newPage(); - await page.goto('http://example.com'); - // other actions... - await browser.close(); -})(); -``` - -## property: Playwright.errors -- type: <[Object]> - - `TimeoutError` <[function]> A class of [TimeoutError]. - -Playwright methods might throw errors if they are unable to fulfill a request. For example, [`method: Page.waitForSelector`] -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. - } -} -``` - -## property: Playwright.firefox -- type: <[BrowserType]> - -This object can be used to launch or connect to Firefox, returning instances of [FirefoxBrowser]. - -## property: Playwright.selectors -- type: <[Selectors]> - -Selectors can be used to install custom selector engines. See [Working with selectors](./selectors.md#working-with-selectors) for more information. - -## property: Playwright.webkit -- type: <[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 [`method: BrowserType.launch`] or -[`method: BrowserType.connect`]. - -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 page = await browser.newPage(); - await page.goto('https://example.com'); - await browser.close(); -})(); -``` - -See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [`method: -BrowserType.connect`] and [`method: BrowserType.launch`] always return a specific browser instance, based on the -browser being connected to or launched. - -## event: Browser.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 [`method: Browser.close`] method was called. - -## async method: Browser.close - -In case this browser is obtained using [`method: BrowserType.launch`], closes the browser and all of its pages (if any -were opened). - -In case this browser is obtained using [`method: BrowserType.connect`], clears all created contexts belonging to this -browser and disconnects from the browser server. - -The [Browser] object itself is considered to be disposed and cannot be used anymore. - -## method: Browser.contexts -- returns: <[Array]<[BrowserContext]>> - -Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts. - -```js -const browser = await pw.webkit.launch(); -console.log(browser.contexts().length); // prints `0` - -const context = await browser.newContext(); -console.log(browser.contexts().length); // prints `1` -``` - -## method: Browser.isConnected -- returns: <[boolean]> - -Indicates that the browser is connected. - -## async method: Browser.newContext -- returns: <[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(); - await page.goto('https://example.com'); -})(); -``` - -### option: Browser.newContext.-inline- = %%-shared-context-params-list-%% - -### option: Browser.newContext.proxy = %%-context-option-proxy-%% - -### option: Browser.newContext.storageState = %%-context-option-storage-state-%% - -## async method: Browser.newPage -- returns: <[Page]> - -Creates a new page in a new browser context. Closing this page will close the context as well. - -This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and -testing frameworks should explicitly create [`method: Browser.newContext`] followed by the [`method: -BrowserContext.newPage`] to control their exact life times. - -### option: Browser.newPage.-inline- = %%-shared-context-params-list-%% - -### option: Browser.newPage.proxy = %%-context-option-proxy-%% - -### option: Browser.newPage.storageState = %%-context-option-storage-state-%% - -## method: Browser.version -- returns: <[string]> - -Returns the browser version. - -# 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(); -await page.goto('https://example.com'); -// Dispose context once it's no longer needed. -await context.close(); -``` - -## event: BrowserContext.close - -Emitted when Browser context gets closed. This might happen because of one of the following: -* Browser context is closed. -* Browser application is closed or crashed. -* The [`method: Browser.close`] method was called. - -## event: BrowserContext.page -- type: <[Page]> - -The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will -also fire for popup pages. See also [`event: Page.popup`] to receive events about popups relevant to a specific page. - -The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a -popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is -done and its response has started loading in the popup. - -```js -const [page] = await Promise.all([ - context.waitForEvent('page'), - page.click('a[target=_blank]'), -]); -console.log(await page.evaluate('location.href')); -``` - -> **NOTE** Use [`method: Page.waitForLoadState`] to wait until the page gets to a particular state (you should not -need it in most cases). - -## async method: BrowserContext.addCookies - -Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be -obtained via [`method: BrowserContext.cookies`]. - -```js -await browserContext.addCookies([cookieObject1, cookieObject2]); -``` - -### param: BrowserContext.addCookies.cookies -- `cookies` <[Array]<[Object]>> - - `name` <[string]> **required** - - `value` <[string]> **required** - - `url` <[string]> either url or domain / path are required. Optional. - - `domain` <[string]> either url or domain / path are required Optional. - - `path` <[string]> either url or domain / path are required Optional. - - `expires` <[float]> Unix time in seconds. Optional. - - `httpOnly` <[boolean]> Optional. - - `secure` <[boolean]> Optional. - - `sameSite` <"Strict"|"Lax"|"None"> Optional. - -## async method: BrowserContext.addInitScript - -Adds a script which would be evaluated in one of the following scenarios: -* Whenever a page is created in the browser context or is navigated. -* Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame. - -The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend -the JavaScript environment, e.g. to seed `Math.random`. - -An example of overriding `Math.random` before the page loads: - -```js -// preload.js -Math.random = () => 42; -``` - -```js -// In your playwright script, assuming the preload.js file is in same directory. -await browserContext.addInitScript({ - path: 'preload.js' -}); -``` - -> **NOTE** The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`] and -[`method: Page.addInitScript`] is not defined. - -### param: BrowserContext.addInitScript.script -- `script` <[function]|[string]|[Object]> - - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. - - `content` <[string]> Raw script content. Optional. - -Script to be evaluated in all pages in the browser context. - -### param: BrowserContext.addInitScript.arg -- `arg` <[Serializable]> - -Optional argument to pass to [`param: script`] (only supported when passing a function). - -## method: BrowserContext.browser -- returns: <[null]|[Browser]> - -Returns the browser instance of the context. If it was launched as a persistent context null gets returned. - -## async method: BrowserContext.clearCookies - -Clears context cookies. - -## async method: BrowserContext.clearPermissions - -Clears all permission overrides for the browser context. - -```js -const context = await browser.newContext(); -await context.grantPermissions(['clipboard-read']); -// do stuff .. -context.clearPermissions(); -``` - -## async method: BrowserContext.close - -Closes the browser context. All the pages that belong to the browser context will be closed. - -> **NOTE** the default browser context cannot be closed. - -## async method: BrowserContext.cookies -- returns: <[Array]<[Object]>> - - `name` <[string]> - - `value` <[string]> - - `domain` <[string]> - - `path` <[string]> - - `expires` <[float]> Unix time in seconds. - - `httpOnly` <[boolean]> - - `secure` <[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. - -### param: BrowserContext.cookies.urls -- `urls` <[string]|[Array]<[string]>> - -Optional list of URLs. - -## async method: BrowserContext.exposeBinding - -The method adds a function called [`param: name`] on the `window` object of every frame in every page in the context. -When called, the function executes [`param: callback`] and returns a [Promise] which resolves to the return -value of [`param: callback`]. If the [`param: callback`] returns a [Promise], it will be awaited. - -The first argument of the [`param: callback`] function contains information about the caller: `{ -browserContext: BrowserContext, page: Page, frame: Frame }`. - -See [`method: Page.exposeBinding`] for page-only version. - -An example of exposing page URL to all frames in all pages in the context: - -```js -const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. - -(async () => { - const browser = await webkit.launch({ headless: false }); - const context = await browser.newContext(); - await context.exposeBinding('pageURL', ({ page }) => page.url()); - const page = await context.newPage(); - await page.setContent(` - - -
- `); - await page.click('button'); -})(); -``` - -An example of passing an element handle: - -```js -await context.exposeBinding('clicked', async (source, element) => { - console.log(await element.textContent()); -}, { handle: true }); -await page.setContent(` - -
Click me
-
Or click me
-`); -``` - -### param: BrowserContext.exposeBinding.name -- `name` <[string]> - -Name of the function on the window object. - -### param: BrowserContext.exposeBinding.callback -- `callback` <[function]> - -Callback function that will be called in the Playwright's context. - -### option: BrowserContext.exposeBinding.handle -- `handle` <[boolean]> - -Whether to pass the argument as a handle, instead of passing by value. When passing a handle, only one argument is -supported. When passing by value, multiple arguments are supported. - -## async method: BrowserContext.exposeFunction - -The method adds a function called [`param: name`] on the `window` object of every frame in every page in the context. -When called, the function executes [`param: callback`] and returns a [Promise] which resolves to the return -value of [`param: callback`]. - -If the [`param: callback`] returns a [Promise], it will be awaited. - -See [`method: Page.exposeFunction`] for page-only version. - -An example of adding an `md5` function to all pages in the context: - -```js -const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. -const crypto = require('crypto'); - -(async () => { - const browser = await webkit.launch({ headless: false }); - const context = await browser.newContext(); - await context.exposeFunction('md5', text => crypto.createHash('md5').update(text).digest('hex')); - const page = await context.newPage(); - await page.setContent(` - - -
- `); - await page.click('button'); -})(); -``` - -### param: BrowserContext.exposeFunction.name -- `name` <[string]> - -Name of the function on the window object. - -### param: BrowserContext.exposeFunction.callback -- `callback` <[function]> - -Callback function that will be called in the Playwright's context. - -## async method: BrowserContext.grantPermissions - -Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if -specified. - -### param: BrowserContext.grantPermissions.permissions -- `permissions` <[Array]<[string]>> - -A permission or an array of permissions to grant. 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'` - -### option: BrowserContext.grantPermissions.origin -- `origin` <[string]> - -The [origin] to grant permissions to, e.g. "https://example.com". - -## async method: BrowserContext.newPage -- returns: <[Page]> - -Creates a new page in the browser context. - -## method: BrowserContext.pages -- returns: <[Array]<[Page]>> - -Returns all open pages in the context. Non visible pages, such as `"background_page"`, will not be listed here. You can -find them using [`method: ChromiumBrowserContext.backgroundPages`]. - -## async method: BrowserContext.route - -Routing provides the capability to modify network requests that are made by any page in the browser context. Once route -is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted. - -An example of a naïve handler that aborts all image requests: - -```js -const context = await browser.newContext(); -await context.route('**/*.{png,jpg,jpeg}', route => route.abort()); -const page = await context.newPage(); -await page.goto('https://example.com'); -await browser.close(); -``` - -or the same snippet using a regex pattern instead: - -```js -const context = await browser.newContext(); -await context.route(/(\.png$)|(\.jpg$)/, route => route.abort()); -const page = await context.newPage(); -await page.goto('https://example.com'); -await browser.close(); -``` - -Page routes (set up with [`method: Page.route`]) take precedence over browser context routes when request matches both -handlers. - -> **NOTE** Enabling routing disables http cache. - -### param: BrowserContext.route.url -- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> - -A glob pattern, regex pattern or predicate receiving [URL] to match while routing. - -### param: BrowserContext.route.handler -- `handler` <[function]\([Route], [Request]\)> - -handler function to route the request. - -## method: BrowserContext.setDefaultNavigationTimeout - -This setting will change the default maximum navigation time for the following methods and related shortcuts: -* [`method: Page.goBack`] -* [`method: Page.goForward`] -* [`method: Page.goto`] -* [`method: Page.reload`] -* [`method: Page.setContent`] -* [`method: Page.waitForNavigation`] - -> **NOTE** [`method: Page.setDefaultNavigationTimeout`] and [`method: Page.setDefaultTimeout`] take priority over -[`method: BrowserContext.setDefaultNavigationTimeout`]. - -### param: BrowserContext.setDefaultNavigationTimeout.timeout -- `timeout` <[float]> - -Maximum navigation time in milliseconds - -## method: BrowserContext.setDefaultTimeout - -This setting will change the default maximum time for all the methods accepting [`param: timeout`] option. - -> **NOTE** [`method: Page.setDefaultNavigationTimeout`], [`method: Page.setDefaultTimeout`] and [`method: -BrowserContext.setDefaultNavigationTimeout`] take priority over [`method: BrowserContext.setDefaultTimeout`]. - -### param: BrowserContext.setDefaultTimeout.timeout -- `timeout` <[float]> - -Maximum time in milliseconds - -## async method: BrowserContext.setExtraHTTPHeaders - -The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged -with page-specific extra HTTP headers set with [`method: Page.setExtraHTTPHeaders`]. If page overrides a particular -header, page-specific header value will be used instead of the browser context header value. - -> **NOTE** `browserContext.setExtraHTTPHeaders` does not guarantee the order of headers in the outgoing requests. - -### param: BrowserContext.setExtraHTTPHeaders.headers -- `headers` <[Object]<[string], [string]>> - -An object containing additional HTTP headers to be sent with every request. All header values must be strings. - -## async method: BrowserContext.setGeolocation - -Sets the context's geolocation. Passing `null` or `undefined` emulates position unavailable. - -```js -await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667}); -``` - -> **NOTE** Consider using [`method: BrowserContext.grantPermissions`] to grant permissions for the browser context -pages to read its geolocation. - -### param: BrowserContext.setGeolocation.geolocation -- `geolocation` <[null]|[Object]> - - `latitude` <[float]> Latitude between -90 and 90. **required** - - `longitude` <[float]> Longitude between -180 and 180. **required** - - `accuracy` <[float]> Non-negative accuracy value. Defaults to `0`. - -## async method: BrowserContext.setHTTPCredentials - -**DEPRECATED** Browsers may cache credentials after successful authentication. -Create a new browser context instead. - -### param: BrowserContext.setHTTPCredentials.httpCredentials -- `httpCredentials` <[null]|[Object]> - - `username` <[string]> **required** - - `password` <[string]> **required** - -## async method: BrowserContext.setOffline - -### param: BrowserContext.setOffline.offline -- `offline` <[boolean]> - -Whether to emulate network being offline for the browser context. - -## async method: BrowserContext.storageState -- returns: <[Object]> - - `cookies` <[Array]<[Object]>> - - `name` <[string]> - - `value` <[string]> - - `domain` <[string]> - - `path` <[string]> - - `expires` <[float]> Unix time in seconds. - - `httpOnly` <[boolean]> - - `secure` <[boolean]> - - `sameSite` <"Strict"|"Lax"|"None"> - - `origins` <[Array]<[Object]>> - - `origin` <[string]> - - `localStorage` <[Array]<[Object]>> - - `name` <[string]> - - `value` <[string]> - -Returns storage state for this browser context, contains current cookies and local storage snapshot. - -### option: BrowserContext.storageState.path -- `path` <[path]> - -The file path to save the storage state to. If [`option: path`] is a relative path, then it is resolved relative to -[current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, storage -state is still returned, but won't be saved to the disk. - -## async method: BrowserContext.unroute - -Removes a route created with [`method: BrowserContext.route`]. When [`param: handler`] is not specified, removes all -routes for the [`param: url`]. - -### param: BrowserContext.unroute.url -- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> - -A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [`method: -BrowserContext.route`]. - -### param: BrowserContext.unroute.handler -- `handler` <[function]\([Route], [Request]\)> - -Optional handler function used to register a routing with [`method: BrowserContext.route`]. - -## async method: BrowserContext.waitForEvent -- returns: <[any]> - -Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy -value. Will throw an error if the context closes before the event is fired. Returns the event data value. - -```js -const context = await browser.newContext(); -await context.grantPermissions(['geolocation']); -``` - -### param: BrowserContext.waitForEvent.event -- `event` <[string]> - -Event name, same one would pass into `browserContext.on(event)`. - -### param: BrowserContext.waitForEvent.optionsOrPredicate -- `optionsOrPredicate` <[Function]|[Object]> - - `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve. - - `timeout` <[float]> 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 [`method: BrowserContext.setDefaultTimeout`]. - -Either a predicate that receives an event or an options object. Optional. - -# 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(); - 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: Page.close - -Emitted when the page closes. - -## event: Page.console -- type: <[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: Page.crash - -Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page crashes, -ongoing and subsequent operations will throw. - -The most common way to deal with crashes is to catch an exception: - -```js -try { - // Crash might happen during a click. - await page.click('button'); - // Or while waiting for an event. - await page.waitForEvent('popup'); -} catch (e) { - // When the page crashes, exception message contains 'crash'. -} -``` - -However, when manually listening to events, it might be useful to avoid stalling when the page crashes. In this case, -handling `crash` event helps: - -```js -await new Promise((resolve, reject) => { - page.on('requestfinished', async request => { - if (await someProcessing(request)) - resolve(request); - }); - page.on('crash', error => reject(error)); -}); -``` - -## event: Page.dialog -- type: <[Dialog]> - -Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond -to the dialog via [`method: Dialog.accept`] or [`method: Dialog.dismiss`] methods. - -## event: Page.domcontentloaded - -Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) -event is dispatched. - -## event: Page.download -- type: <[Download]> - -Emitted when attachment download started. User can access basic file operations on downloaded content via the passed -[Download] instance. - -> **NOTE** Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the -downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual -download is not performed and user has no access to the downloaded files. - -## event: Page.filechooser -- type: <[FileChooser]> - -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 [`method: FileChooser.setFiles`] that can be uploaded after that. - -```js -page.on('filechooser', async (fileChooser) => { - await fileChooser.setFiles('/tmp/myfile.pdf'); -}); -``` - -## event: Page.frameattached -- type: <[Frame]> - -Emitted when a frame is attached. - -## event: Page.framedetached -- type: <[Frame]> - -Emitted when a frame is detached. - -## event: Page.framenavigated -- type: <[Frame]> - -Emitted when a frame is navigated to a new url. - -## event: Page.load - -Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. - -## event: Page.pageerror -- type: <[Error]> - -Emitted when an uncaught exception happens within the page. - -## event: Page.popup -- type: <[Page]> - -Emitted when the page opens a new tab or window. This event is emitted in addition to the [`event: -BrowserContext.page`], but only for popups relevant to this page. - -The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a -popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is -done and its response has started loading in the popup. - -```js -const [popup] = await Promise.all([ - page.waitForEvent('popup'), - page.evaluate(() => window.open('https://example.com')), -]); -console.log(await popup.evaluate('location.href')); -``` - -> **NOTE** Use [`method: Page.waitForLoadState`] to wait until the page gets to a particular state (you should not -need it in most cases). - -## event: Page.request -- type: <[Request]> - -Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see -[`method: Page.route`] or [`method: BrowserContext.route`]. - -## event: Page.requestfailed -- type: <[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 [`event: Page.requestfinished`] event and not with [`event: Page.requestfailed`]. - -## event: Page.requestfinished -- type: <[Request]> - -Emitted when a request finishes successfully after downloading the response body. For a successful response, the -sequence of events is `request`, `response` and `requestfinished`. - -## event: Page.response -- type: <[Response]> - -Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events -is `request`, `response` and `requestfinished`. - -## event: Page.websocket -- type: <[WebSocket]> - -Emitted when <[WebSocket]> request is sent. - -## event: Page.worker -- type: <[Worker]> - -Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the -page. - -## async method: Page.$ -- returns: <[null]|[ElementHandle]> - -The method finds an element matching the specified selector within the page. If no elements match the selector, the -return value resolves to `null`. - -Shortcut for main frame's [`method: Frame.$`]. - -### param: Page.$.selector = %%-query-selector-%% - -## async method: Page.$$ -- returns: <[Array]<[ElementHandle]>> - -The method finds all elements matching the specified selector within the page. If no elements match the selector, the -return value resolves to `[]`. - -Shortcut for main frame's [`method: Frame.$$`]. - -### param: Page.$$.selector = %%-query-selector-%% - -## async method: Page.$eval -- returns: <[Serializable]> - -The method finds an element matching the specified selector within the page and passes it as a first argument to -[`param: pageFunction`]. If no elements match the selector, the method throws an error. Returns the value of [`param: -pageFunction`]. - -If [`param: pageFunction`] returns a [Promise], then [`method: 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, suffix) => e.outerHTML + suffix, 'hello'); -``` - -Shortcut for main frame's [`method: Frame.$eval`]. - -### param: Page.$eval.selector = %%-query-selector-%% - -### param: Page.$eval.pageFunction -- `pageFunction` <[function]\([Element]\)> - -Function to be evaluated in browser context - -### param: Page.$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] - -## async method: Page.$$eval -- returns: <[Serializable]> - -The method finds all elements matching the specified selector within the page and passes an array of matched elements as -a first argument to [`param: pageFunction`]. Returns the result of [`param: pageFunction`] invocation. - -If [`param: pageFunction`] returns a [Promise], then [`method: Page.$$eval`] would wait for the promise to resolve and return -its value. - -Examples: - -```js -const divsCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); -``` - -### param: Page.$$eval.selector = %%-query-selector-%% - -### param: Page.$$eval.pageFunction -- `pageFunction` <[function]\([Array]<[Element]>\)> - -Function to be evaluated in browser context - -### param: Page.$$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] - -## property: Page.accessibility -- type: <[Accessibility]> - -## async method: Page.addInitScript - -Adds a script which would be evaluated in one of the following scenarios: -* Whenever the page is navigated. -* Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame. - -The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend -the JavaScript environment, e.g. to seed `Math.random`. - -An example of overriding `Math.random` before the page loads: - -```js -// preload.js -Math.random = () => 42; - -// In your playwright script, assuming the preload.js file is in same directory -const preloadFile = fs.readFileSync('./preload.js', 'utf8'); -await page.addInitScript(preloadFile); -``` - -> **NOTE** The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`] and -[`method: Page.addInitScript`] is not defined. - -### param: Page.addInitScript.script -- `script` <[function]|[string]|[Object]> - - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. - - `content` <[string]> Raw script content. Optional. - -Script to be evaluated in the page. - -### param: Page.addInitScript.arg -- `arg` <[Serializable]> - -Optional argument to pass to [`param: script`] (only supported when passing a function). - -## async method: Page.addScriptTag -- returns: <[ElementHandle]> - -Adds a ` - -
- `); - await page.click('button'); -})(); -``` - -An example of passing an element handle: - -```js -await page.exposeBinding('clicked', async (source, element) => { - console.log(await element.textContent()); -}, { handle: true }); -await page.setContent(` - -
Click me
-
Or click me
-`); -``` - -### param: Page.exposeBinding.name -- `name` <[string]> - -Name of the function on the window object. - -### param: Page.exposeBinding.callback -- `callback` <[function]> - -Callback function that will be called in the Playwright's context. - -### option: Page.exposeBinding.handle -- `handle` <[boolean]> - -Whether to pass the argument as a handle, instead of passing by value. When passing a handle, only one argument is -supported. When passing by value, multiple arguments are supported. - -## async method: Page.exposeFunction - -The method adds a function called [`param: name`] on the `window` object of every frame in the page. When called, the -function executes [`param: callback`] and returns a [Promise] which resolves to the return value of [`param: -callback`]. - -If the [`param: callback`] returns a [Promise], it will be awaited. - -See [`method: BrowserContext.exposeFunction`] for context-wide exposed function. - -> **NOTE** Functions installed via `page.exposeFunction` survive navigations. - -An example of adding an `md5` function to the page: - -```js -const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. -const crypto = require('crypto'); - -(async () => { - const browser = await webkit.launch({ headless: false }); - const page = await browser.newPage(); - await page.exposeFunction('md5', text => crypto.createHash('md5').update(text).digest('hex')); - await page.setContent(` - - -
- `); - await page.click('button'); -})(); -``` - -An example of adding a `window.readfile` function to the page: - -```js -const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. -const fs = require('fs'); - -(async () => { - const browser = await chromium.launch(); - const page = await browser.newPage(); - page.on('console', msg => console.log(msg.text())); - await page.exposeFunction('readfile', async filePath => { - return new Promise((resolve, reject) => { - fs.readFile(filePath, 'utf8', (err, text) => { - if (err) - reject(err); - else - resolve(text); - }); - }); - }); - await page.evaluate(async () => { - // use window.readfile to read contents of a file - const content = await window.readfile('/etc/hosts'); - console.log(content); - }); - await browser.close(); -})(); -``` - -### param: Page.exposeFunction.name -- `name` <[string]> - -Name of the function on the window object - -### param: Page.exposeFunction.callback -- `callback` <[function]> - -Callback function which will be called in Playwright's context. - -## async method: Page.fill - -This method waits for an element matching [`param: selector`], waits for [actionability](./actionability.md) checks, -focuses the element, fills it and triggers an `input` event after filling. If the element matching [`param: selector`] -is not an ``, `