diff --git a/docs/api.md b/docs/api.md
index 61bb191d08..6877c633b1 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -26,8 +26,16 @@
* [browserFetcher.platform()](#browserfetcherplatform)
* [browserFetcher.remove(revision)](#browserfetcherremoverevision)
* [browserFetcher.revisionInfo(revision)](#browserfetcherrevisioninforevision)
+- [class: BrowserServer](#class-browserserver)
+ * [browserServer.close()](#browserserverclose)
+ * [browserServer.connect()](#browserserverconnect)
+ * [browserServer.process()](#browserserverprocess)
+ * [browserServer.wsEndpoint()](#browserserverwsendpoint)
- [class: ChromiumBrowser](#class-chromiumbrowser)
* [event: 'disconnected'](#event-disconnected)
+ * [event: 'targetchanged'](#event-targetchanged)
+ * [event: 'targetcreated'](#event-targetcreated)
+ * [event: 'targetdestroyed'](#event-targetdestroyed)
* [chromiumBrowser.browserContexts()](#chromiumbrowserbrowsercontexts)
* [chromiumBrowser.chromium](#chromiumbrowserchromium)
* [chromiumBrowser.close()](#chromiumbrowserclose)
@@ -36,15 +44,19 @@
* [chromiumBrowser.isConnected()](#chromiumbrowserisconnected)
* [chromiumBrowser.newContext(options)](#chromiumbrowsernewcontextoptions)
* [chromiumBrowser.process()](#chromiumbrowserprocess)
+ * [chromiumBrowser.browserTarget()](#chromiumbrowserbrowsertarget)
+ * [chromiumBrowser.pageTarget(page)](#chromiumbrowserpagetargetpage)
+ * [chromiumBrowser.serviceWorker(target)](#chromiumbrowserserviceworkertarget)
+ * [chromiumBrowser.startTracing(page, [options])](#chromiumbrowserstarttracingpage-options)
+ * [chromiumBrowser.stopTracing()](#chromiumbrowserstoptracing)
+ * [chromiumBrowser.targets(context)](#chromiumbrowsertargetscontext)
+ * [chromiumBrowser.waitForTarget(predicate[, options])](#chromiumbrowserwaitfortargetpredicate-options)
- [class: BrowserContext](#class-browsercontext)
- * [browserContext.browser()](#browsercontextbrowser)
* [browserContext.clearCookies()](#browsercontextclearcookies)
* [browserContext.close()](#browsercontextclose)
* [browserContext.cookies([...urls])](#browsercontextcookiesurls)
* [browserContext.newPage()](#browsercontextnewpage)
- * [browserContext.overrides](#browsercontextoverrides)
* [browserContext.pages()](#browsercontextpages)
- * [browserContext.permissions](#browsercontextpermissions)
* [browserContext.setCookies(cookies)](#browsercontextsetcookiescookies)
- [class: ChromiumOverrides](#class-chromiumoverrides)
* [chromiumOverrides.setGeolocation(options)](#chromiumoverridessetgeolocationoptions)
@@ -148,18 +160,6 @@
* [chromiumPDF.generate([options])](#chromiumpdfgenerateoptions)
- [class: FirefoxBrowser](#class-firefoxbrowser)
* [firefoxBrowser.wsEndpoint()](#firefoxbrowserwsendpoint)
-- [class: ChromiumBrowser](#class-chromiumbrowser-1)
- * [event: 'targetchanged'](#event-targetchanged)
- * [event: 'targetcreated'](#event-targetcreated)
- * [event: 'targetdestroyed'](#event-targetdestroyed)
- * [chromiumBrowser.browserTarget()](#chromiumbrowserbrowsertarget)
- * [chromiumBrowser.pageTarget(page)](#chromiumbrowserpagetargetpage)
- * [chromiumBrowser.serviceWorker(target)](#chromiumbrowserserviceworkertarget)
- * [chromiumBrowser.startTracing(page, [options])](#chromiumbrowserstarttracingpage-options)
- * [chromiumBrowser.stopTracing()](#chromiumbrowserstoptracing)
- * [chromiumBrowser.targets(context)](#chromiumbrowsertargetscontext)
- * [chromiumBrowser.waitForTarget(predicate[, options])](#chromiumbrowserwaitfortargetpredicate-options)
- * [chromiumBrowser.wsEndpoint()](#chromiumbrowserwsendpoint)
- [class: Dialog](#class-dialog)
* [dialog.accept([promptText])](#dialogacceptprompttext)
* [dialog.defaultValue()](#dialogdefaultvalue)
@@ -204,10 +204,6 @@
* [frame.waitForNavigation([options])](#framewaitfornavigationoptions)
* [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options)
* [frame.waitForXPath(xpath[, options])](#framewaitforxpathxpath-options)
-- [class: ExecutionContext](#class-executioncontext)
- * [executionContext.evaluate(pageFunction[, ...args])](#executioncontextevaluatepagefunction-args)
- * [executionContext.evaluateHandle(pageFunction[, ...args])](#executioncontextevaluatehandlepagefunction-args)
- * [executionContext.frame()](#executioncontextframe)
- [class: ChromiumInterception](#class-chromiuminterception)
* [chromiumInterception.abort(request, [errorCode])](#chromiuminterceptionabortrequest-errorcode)
* [chromiumInterception.authenticate(credentials)](#chromiuminterceptionauthenticatecredentials)
@@ -515,6 +511,28 @@ The method initiates a GET request to download the revision from the host.
- `url` <[string]> URL this revision can be downloaded from
- `local` <[boolean]> whether the revision is locally available on disk
+### class: BrowserServer
+
+#### browserServer.close()
+- returns: <[Promise]>
+
+Closes the browser gracefully and makes sure the process is terminated.
+
+#### browserServer.connect()
+- returns: <[Promise]<[Browser]>>
+
+Connects to the browser server and returns a <[Browser]> object.
+
+#### browserServer.process()
+- returns: [ChildProcess]> Spawned browser server process.
+
+#### browserServer.wsEndpoint()
+- returns: <[string]> Browser websocket url.
+
+Browser websocket endpoint which can be used as an argument to `playwright.connect`.
+
+Learn more about the [devtools protocol](https://chromedevtools.github.io/devtools-protocol) and the [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target).
+
### class: ChromiumBrowser
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
@@ -539,23 +557,51 @@ An example of disconnecting from and reconnecting to a [Browser]:
const playwright = require('playwright');
(async () => {
- const browser = await playwright.launch();
- // Store the endpoint to be able to reconnect to Chromium
- const browserWSEndpoint = browser.chromium.wsEndpoint();
- // Disconnect playwright from Chromium
- browser.disconnect();
-
- // Use the endpoint to reestablish a connection
- const browser2 = await playwright.connect({browserWSEndpoint});
+ const browserServer = await playwright.launchServer();
+ const browserWSEndpoint = browserServer.wsEndpoint();
+ // Use the endpoint to establish a connection
+ const browser = await playwright.connect({browserWSEndpoint});
// Close Chromium
- await browser2.close();
+ await browser.close();
})();
```
+
+Chromium-specific features including Tracing, service worker support, etc.
+You can use [`chromium.startTracing`](#chromiumstarttracingpage-options) and [`chromium.stopTracing`](#chromiumstoptracing) to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
+
+```js
+await browser.chromium.startTracing(page, {path: 'trace.json'});
+await page.goto('https://www.google.com');
+await browser.chromium.stopTracing();
+```
+
#### event: 'disconnected'
Emitted when Playwright gets disconnected from the Chromium instance. This might happen because of one of the following:
- Chromium is closed or crashed
- The [`browser.disconnect`](#browserdisconnect) method was called
+#### event: 'targetchanged'
+- <[Target]>
+
+Emitted when the url of a target changes.
+
+> **NOTE** This includes target changes in incognito browser contexts.
+
+
+#### event: 'targetcreated'
+- <[Target]>
+
+Emitted when a target is created, for example when a new page is opened by [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or [`browserContext.newPage`](#browsercontextnewpage).
+
+> **NOTE** This includes target creations in incognito browser contexts.
+
+#### event: 'targetdestroyed'
+- <[Target]>
+
+Emitted when a target is destroyed, for example when a page is closed.
+
+> **NOTE** This includes target destructions in incognito browser contexts.
+
#### chromiumBrowser.browserContexts()
- returns: <[Array]<[BrowserContext]>>
@@ -621,6 +667,55 @@ Creates a new browser context. It won't share cookies/cache with other browser c
#### chromiumBrowser.process()
- returns: [ChildProcess]> Spawned browser process. Returns `null` if the browser instance was created with [`playwright.connect`](#playwrightconnectoptions) method.
+#### chromiumBrowser.browserTarget()
+- returns: <[Target]>
+
+Returns browser target.
+
+#### chromiumBrowser.pageTarget(page)
+- `page` <[Page]> Page to return target for.
+- returns: <[Target]> a target given page was created from.
+
+#### chromiumBrowser.serviceWorker(target)
+- `target` <[Target]> Target to treat as a service worker
+- returns: <[Promise]<[Worker]>>
+
+Attaches to the service worker target.
+
+#### chromiumBrowser.startTracing(page, [options])
+- `page` <[Page]> Optional, if specified, tracing includes screenshots of the given page.
+- `options` <[Object]>
+ - `path` <[string]> A path to write the trace file to.
+ - `screenshots` <[boolean]> captures screenshots in the trace.
+ - `categories` <[Array]<[string]>> specify custom categories to use instead of default.
+- returns: <[Promise]>
+
+Only one trace can be active at a time per browser.
+
+#### chromiumBrowser.stopTracing()
+- returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with trace data.
+
+#### chromiumBrowser.targets(context)
+- `context` <[BrowserContext]> Optional, if specified, only targets from this context are returned.
+- returns: <[Array]<[Target]>>
+
+An array of all active targets inside the Browser. In case of multiple browser contexts,
+the method will return an array with all the targets in all browser contexts.
+
+#### chromiumBrowser.waitForTarget(predicate[, options])
+- `predicate` <[function]\([Target]\):[boolean]> A function to be run for every target
+- `options` <[Object]>
+ - `timeout` <[number]> Maximum wait time in milliseconds. Pass `0` to disable the timeout. Defaults to 30 seconds.
+- returns: <[Promise]<[Target]>> Promise which resolves to the first target found that matches the `predicate` function.
+
+This searches for a target in all browser contexts.
+
+An example of finding a target for a page opened via `window.open`:
+```js
+await page.evaluate(() => window.open('https://www.example.com/'));
+const newWindowTarget = await browser.chromium.waitForTarget(target => target.url() === 'https://www.example.com/');
+```
+
### class: BrowserContext
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
@@ -644,11 +739,6 @@ await page.goto('https://example.com');
await context.close();
```
-#### browserContext.browser()
-- returns: <[Browser]>
-
-The browser this browser context belongs to.
-
#### browserContext.clearCookies()
- returns: <[Promise]>
@@ -686,17 +776,11 @@ If URLs are specified, only cookies that affect those URLs are returned.
Creates a new page in the browser context.
-#### browserContext.overrides
-- returns: <[Overrides]>
-
#### browserContext.pages()
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [target.page()](#targetpage).
An array of all pages inside the browser context.
-#### browserContext.permissions
-- returns: <[Permissions]>
-
#### browserContext.setCookies(cookies)
- `cookies` <[Array]<[Object]>>
- `name` <[string]> **required**
@@ -919,7 +1003,7 @@ Emitted when a request finishes successfully.
Emitted when a [response] is received.
#### page.$(selector)
-- `selector` <[string]|[Selector]> A [selector] to query page for
+- `selector` <[string]> A selector to query page for
- returns: <[Promise][ElementHandle]>>
The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolves to `null`.
@@ -927,7 +1011,7 @@ The method runs `document.querySelector` within the page. If no element matches
Shortcut for [page.mainFrame().$(selector)](#frameselector).
#### page.$$(selector)
-- `selector` <[string]|[Selector]> A [selector] to query page for
+- `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 `[]`.
@@ -935,7 +1019,7 @@ The method runs `document.querySelectorAll` within the page. If no elements matc
Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).
#### page.$$eval(selector, pageFunction[, ...args])
-- `selector` <[string]|[Selector]> A [selector] to query page for
+- `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`
@@ -950,7 +1034,7 @@ const divsCounts = await page.$$eval('div', divs => divs.length);
```
#### page.$eval(selector, pageFunction[, ...args])
-- `selector` <[string]|[Selector]> A [selector] to query page for
+- `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`
@@ -1015,7 +1099,7 @@ Get the browser the page belongs to.
Get the browser context that the page belongs to.
#### page.click(selector[, options])
-- `selector` <[string]|[Selector]> A [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
+- `selector` <[string]> A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
- `options` <[Object]>
- `button` <"left"|"right"|"middle"> Defaults to `left`.
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
@@ -1062,7 +1146,7 @@ Gets the full HTML contents of the page, including the doctype.
- returns: <[Coverage]>
#### page.dblclick(selector[, options])
-- `selector` <[string]|[Selector]> A [selector] to search for element to double click. If there are multiple elements satisfying the selector, the first will be double clicked.
+- `selector` <[string]> A selector to search for element to double click. If there are multiple elements satisfying the selector, the first will be double clicked.
- `options` <[Object]>
- `button` <"left"|"right"|"middle"> Defaults to `left`.
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
@@ -1232,7 +1316,7 @@ const fs = require('fs');
```
#### page.fill(selector, value)
-- `selector` <[string]|[Selector]> A [selector] to query page for.
+- `selector` <[string]> A selector to query page for.
- `value` <[string]> Value to fill for the ``, `