From f31ae5e2ed076866eb71d6946a4204adc88919e6 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Wed, 8 Jan 2020 14:02:53 -0800 Subject: [PATCH] docs: fix docs around server apis (#417) --- docs/api.md | 106 +++++++++++++++++++++++++++++------ src/api.ts | 14 +++-- src/browser.ts | 29 ---------- src/chromium/crApi.ts | 19 ------- src/firefox/ffApi.ts | 17 ------ src/server/browserFetcher.ts | 2 +- src/webkit/wkApi.ts | 17 ------ 7 files changed, 100 insertions(+), 104 deletions(-) delete mode 100644 src/chromium/crApi.ts delete mode 100644 src/firefox/ffApi.ts delete mode 100644 src/webkit/wkApi.ts diff --git a/docs/api.md b/docs/api.md index f7137e304c..aabd9bb36a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -29,11 +29,12 @@ * [browserFetcher.localRevisions()](#browserfetcherlocalrevisions) * [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: ChromiumBrowserServer](#class-chromiumbrowserserver) + * [chromiumBrowserServer.close()](#chromiumbrowserserverclose) + * [chromiumBrowserServer.connect()](#chromiumbrowserserverconnect) + * [chromiumBrowserServer.connectOptions()](#chromiumbrowserserverconnectoptions) + * [chromiumBrowserServer.process()](#chromiumbrowserserverprocess) + * [chromiumBrowserServer.wsEndpoint()](#chromiumbrowserserverwsendpoint) - [class: ConsoleMessage](#class-consolemessage) * [consoleMessage.args()](#consolemessageargs) * [consoleMessage.location()](#consolemessagelocation) @@ -263,6 +264,17 @@ * [chromiumTarget.page()](#chromiumtargetpage) * [chromiumTarget.type()](#chromiumtargettype) * [chromiumTarget.url()](#chromiumtargeturl) +- [class: FirefoxBrowserServer](#class-firefoxbrowserserver) + * [firefoxBrowserServer.close()](#firefoxbrowserserverclose) + * [firefoxBrowserServer.connect()](#firefoxbrowserserverconnect) + * [firefoxBrowserServer.connectOptions()](#firefoxbrowserserverconnectoptions) + * [firefoxBrowserServer.process()](#firefoxbrowserserverprocess) + * [firefoxBrowserServer.wsEndpoint()](#firefoxbrowserserverwsendpoint) +- [class: WebKitBrowserServer](#class-webkitbrowserserver) + * [webKitBrowserServer.close()](#webkitbrowserserverclose) + * [webKitBrowserServer.connect()](#webkitbrowserserverconnect) + * [webKitBrowserServer.connectOptions()](#webkitbrowserserverconnectoptions) + * [webKitBrowserServer.process()](#webkitbrowserserverprocess) - [class: Worker](#class-worker) * [worker.evaluate(pageFunction[, ...args])](#workerevaluatepagefunction-args) * [worker.evaluateHandle(pageFunction[, ...args])](#workerevaluatehandlepagefunction-args) @@ -307,8 +319,8 @@ const playwright = require('playwright'); ``` #### 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 +Emitted when Playwright gets disconnected from the browser instance. This might happen because of one of the following: +- Browser is closed or crashed - The [`browser.disconnect`](#browserdisconnect) method was called #### browser.browserContexts() @@ -320,7 +332,7 @@ a single instance of [BrowserContext]. #### browser.close() - returns: <[Promise]> -Closes Chromium and all of its pages (if any were opened). The [Browser] object itself is considered to be disposed and cannot be used anymore. +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]> @@ -329,7 +341,7 @@ Returns the default browser context. The default browser context can not be clos #### browser.disconnect() -Disconnects Playwright from the browser, but leaves the Chromium process running. After calling `disconnect`, the [Browser] object is considered disposed and cannot be used anymore. +Disconnects Playwright from the browser, but leaves the browser process running. After calling `disconnect`, the [Browser] object is considered disposed and cannot be used anymore. #### browser.isConnected() @@ -509,9 +521,9 @@ await context.setPermissions('https://html5demos.com', ['geolocation']); ### class: BrowserFetcher -BrowserFetcher can download and manage different versions of Chromium. +BrowserFetcher can download and manage different versions of Chromium/Firefox/WebKit. -BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/). +BrowserFetcher operates on revision strings that specify a precise version of the browser, e.g. `"533271"`. Chromium revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/). An example of using BrowserFetcher to download a specific version of Chromium and running Playwright against it: @@ -561,22 +573,31 @@ 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 +### class: ChromiumBrowserServer -#### browserServer.close() +#### chromiumBrowserServer.close() - returns: <[Promise]> Closes the browser gracefully and makes sure the process is terminated. -#### browserServer.connect() +#### chromiumBrowserServer.connect() - returns: <[Promise]<[Browser]>> Connects to the browser server and returns a <[Browser]> object. -#### browserServer.process() +#### chromiumBrowserServer.connectOptions() +- returns: <[Object]> + - `browserWSEndpoint` a [browser websocket endpoint](#browserwsendpoint) to connect to. + - `browserURL` a browser url to connect to, in format `http://${host}:${port}`. Use interchangeably with `browserWSEndpoint` to let Playwright fetch it from [metadata endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target). + - `slowMo` <[number]> + - `transport` <[ConnectionTransport]> **Experimental** A custom transport object which should be used to connect. + +This options object can be passed to [chromiumPlaywright.connect(options)](#chromiumplaywrightconnectoptions) to establish connection to the browser. + +#### chromiumBrowserServer.process() - returns: Spawned browser server process. -#### browserServer.wsEndpoint() +#### chromiumBrowserServer.wsEndpoint() - returns: Browser websocket url. Browser websocket endpoint which can be used as an argument to `playwright.connect`. @@ -3332,6 +3353,9 @@ const iPhone = playwright.devices['iPhone 6']; #### chromiumPlaywright.downloadBrowser([options]) - `options` <[Object]> + - `host` <[string]> A download host to be used. Defaults to `https://storage.googleapis.com`. + - `path` <[string]> A path for the downloads folder. Defaults to `/.local-chromium`, where `` is playwright's package root. + - `platform` <[string]> Possible values are: `mac`, `win32`, `win64`, `linux`. Defaults to the current platform. - `onProgress` <[function]([number], [number])> A function that will be called with two arguments: - `downloadedBytes` <[number]> how many bytes have been downloaded - `totalBytes` <[number]> how large is the total download. @@ -3487,6 +3511,56 @@ Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](h #### chromiumTarget.url() - returns: <[string]> +### class: FirefoxBrowserServer + +#### firefoxBrowserServer.close() +- returns: <[Promise]> + +Closes the browser gracefully and makes sure the process is terminated. + +#### firefoxBrowserServer.connect() +- returns: <[Promise]<[Browser]>> + +Connects to the browser server and returns a <[Browser]> object. + +#### firefoxBrowserServer.connectOptions() +- returns: <[Object]> + - `browserWSEndpoint` a [browser websocket endpoint](#browserwsendpoint) to connect to. + - `slowMo` <[number]> + - `transport` <[ConnectionTransport]> **Experimental** A custom transport object which should be used to connect. + +This options object can be passed to [firefoxPlaywright.connect(options)](#firefoxplaywrightconnectoptions) to establish connection to the browser. + +#### firefoxBrowserServer.process() +- returns: Spawned browser server process. + +#### firefoxBrowserServer.wsEndpoint() +- returns: Browser websocket url. + +Browser websocket endpoint which can be used as an argument to `playwright.connect`. + +### class: WebKitBrowserServer + +#### webKitBrowserServer.close() +- returns: <[Promise]> + +Closes the browser gracefully and makes sure the process is terminated. + +#### webKitBrowserServer.connect() +- returns: <[Promise]<[Browser]>> + +Connects to the browser server and returns a <[Browser]> object. + +#### webKitBrowserServer.connectOptions() +- returns: <[Object]> + - `slowMo` <[number]> + - `transport` <[ConnectionTransport]> **Experimental** A custom transport object which should be used to connect. + +This options object can be passed to [webKitPlaywright.connect(options)](#webkitplaywrightconnectoptions) to establish connection to the browser. + +#### webKitBrowserServer.process() +- returns: Spawned browser server process. + ### class: Worker The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). diff --git a/src/api.ts b/src/api.ts index ca959795d0..2b4d73d306 100644 --- a/src/api.ts +++ b/src/api.ts @@ -15,7 +15,7 @@ */ export { Accessibility } from './accessibility'; -export { Browser, BrowserServer } from './browser'; +export { Browser } from './browser'; export { BrowserContext } from './browserContext'; export { ConsoleMessage } from './console'; export { Dialog } from './dialog'; @@ -27,11 +27,15 @@ export { JSHandle } from './javascript'; export { Request, Response } from './network'; export { Coverage, FileChooser, Page, Worker } from './page'; +export { CRBrowser as ChromiumBrowser } from './chromium/crBrowser'; +export { CRSession as ChromiumSession } from './chromium/crConnection'; +export { CRTarget as ChromiumTarget } from './chromium/crTarget'; + +export { FFBrowser as FirefoxBrowser } from './firefox/ffBrowser'; + +export { WKBrowser as WebKitBrowser } from './webkit/wkBrowser'; + export { BrowserFetcher } from './server/browserFetcher'; export { CRPlaywright as ChromiumPlaywright, CRBrowserServer as ChromiumBrowserServer } from './server/crPlaywright'; export { FFPlaywright as FirefoxPlaywright, FFBrowserServer as FirefoxBrowserServer } from './server/ffPlaywright'; export { WKPlaywright as WebKitPlaywright, WKBrowserServer as WebKitBrowserServer } from './server/wkPlaywright'; - -export * from './chromium/crApi'; -export * from './firefox/ffApi'; -export * from './webkit/wkApi'; diff --git a/src/browser.ts b/src/browser.ts index 0291080b5e..87b36f4ba7 100644 --- a/src/browser.ts +++ b/src/browser.ts @@ -15,7 +15,6 @@ */ import { BrowserContext, BrowserContextOptions } from './browserContext'; -import { ChildProcess } from 'child_process'; import { EventEmitter } from './platform'; export class Browser extends EventEmitter { @@ -27,31 +26,3 @@ export class Browser extends EventEmitter { isConnected(): boolean { throw new Error('Not implemented'); } close(): Promise { throw new Error('Not implemented'); } } - -export class BrowserServer { - private _browser: T; - private _process: ChildProcess; - private _wsEndpoint: string; - - constructor(browser: T, process: ChildProcess, wsEndpoint: string) { - this._browser = browser; - this._process = process; - this._wsEndpoint = wsEndpoint; - } - - async connect(): Promise { - return this._browser; - } - - process(): ChildProcess { - return this._process; - } - - wsEndpoint(): string { - return this._wsEndpoint; - } - - async close(): Promise { - await this._browser.close(); - } -} diff --git a/src/chromium/crApi.ts b/src/chromium/crApi.ts deleted file mode 100644 index b6fbfea0c0..0000000000 --- a/src/chromium/crApi.ts +++ /dev/null @@ -1,19 +0,0 @@ -/** - * Copyright (c) Microsoft Corporation. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -export { CRBrowser as ChromiumBrowser } from './crBrowser'; -export { CRSession as ChromiumSession } from './crConnection'; -export { CRTarget as ChromiumTarget } from './crTarget'; diff --git a/src/firefox/ffApi.ts b/src/firefox/ffApi.ts deleted file mode 100644 index c4274c95a5..0000000000 --- a/src/firefox/ffApi.ts +++ /dev/null @@ -1,17 +0,0 @@ -/** - * Copyright (c) Microsoft Corporation. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -export { FFBrowser as FirefoxBrowser } from './ffBrowser'; diff --git a/src/server/browserFetcher.ts b/src/server/browserFetcher.ts index a141dc909c..322b8e155d 100644 --- a/src/server/browserFetcher.ts +++ b/src/server/browserFetcher.ts @@ -200,7 +200,7 @@ function httpRequest(url: string, method: string, response: (r: any) => void) { export type BrowserFetcherOptions = { platform?: string, path?: string, - host ?: string, + host?: string, }; export type BrowserFetcherRevisionInfo = { diff --git a/src/webkit/wkApi.ts b/src/webkit/wkApi.ts deleted file mode 100644 index 9eab7adf3f..0000000000 --- a/src/webkit/wkApi.ts +++ /dev/null @@ -1,17 +0,0 @@ -/** - * Copyright (c) Microsoft Corporation. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -export { WKBrowser as WebKitBrowser } from './wkBrowser';