docs: fix docs around server apis (#417)

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` <?[string]> a [browser websocket endpoint](#browserwsendpoint) to connect to.
+  - `browserURL` <?[string]> 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: <?[ChildProcess]> Spawned browser server process.
 
-#### browserServer.wsEndpoint()
+#### chromiumBrowserServer.wsEndpoint()
 - returns: <?[string]> 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 `<root>/.local-chromium`, where `<root>` 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` <?[string]> 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: <?[ChildProcess]> Spawned browser server process.
+
+#### firefoxBrowserServer.wsEndpoint()
+- returns: <?[string]> 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: <?[ChildProcess]> Spawned browser server process.
+
 ### class: Worker
 
 The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).

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';

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<void> { throw new Error('Not implemented'); }
 }
-
-export class BrowserServer<T extends Browser> {
-  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<T> {
-    return this._browser;
-  }
-
-  process(): ChildProcess {
-    return this._process;
-  }
-
-  wsEndpoint(): string {
-    return this._wsEndpoint;
-  }
-
-  async close(): Promise<void> {
-    await this._browser.close();
-  }
-}

src/chromium/crApi.ts

@@ -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';

src/firefox/ffApi.ts

@@ -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';

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 = {

src/webkit/wkApi.ts

@@ -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';