From 536c50db78b7e9f149fdb2c5b7479cd6a422388c Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Thu, 19 Dec 2019 20:14:19 -0800 Subject: [PATCH] docs: started working on the api.md (2) --- docs/api.md | 390 +++++++++++++++++-------------------------- src/firefox/ffApi.ts | 1 - 2 files changed, 153 insertions(+), 238 deletions(-) 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: 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: 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]> 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 ``, `