chore: update top-level api (#479)

```
require('playwright').chromium.launch(...)
window.playwrightweb.chromium.connect(...)
```

.gitignore

@@ -18,7 +18,6 @@ yarn.lock
 /src/chromium/protocol.ts
 /src/firefox/protocol.ts
 /src/webkit/protocol.ts
-/utils/browser/playwright-web.js
 lib/
 playwright-*.tgz
 /web.js

.npmignore

@@ -9,7 +9,7 @@ lib/injected/
 #types
 !lib/**/*.d.ts
 !index.d.ts
-!web.d.ts
+
 # Install
 !install.js
 
@@ -18,12 +18,3 @@ lib/injected/
 
 # root for "playwright/web"
 !web.js
-
-# specific browsers
-!chromium.js
-!firefox.js
-!webkit.js
-
-# dgozman says to remove these
-!DeviceDescriptors.js
-!Errors.js

DeviceDescriptors.js

@@ -1,20 +0,0 @@
-/**
- * Copyright 2019 Google Inc. All rights reserved.
- * Modifications 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.
- */
-
-const {DeviceDescriptors} = require('./lib/deviceDescriptors');
-
-module.exports = DeviceDescriptors;

Errors.js

@@ -1,17 +0,0 @@
-/**
- * Copyright 2018 Google Inc. All rights reserved.
- *
- * 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.
- */
-
-module.exports = require('./lib/errors');

README.md

@@ -31,7 +31,7 @@ This code snippet navigates to example.com in WebKit, and saves a screenshot.
 const pw = require('playwright');
 
 (async () => {
-  const browser = await pw.playwright('webkit').launch(); // or 'chromium', 'firefox'
+  const browser = await pw.webkit.launch(); // or 'chromium', 'firefox'
   const context = await browser.newContext();
   const page = await context.newPage();
 
@@ -50,7 +50,7 @@ This code snippet navigates to example.com in Firefox, and executes a script in
 const pw = require('playwright');
 
 (async () => {
-  const browser = await pw.playwright('firefox').launch(); // or 'chromium', 'webkit'
+  const browser = await pw.firefox.launch(); // or 'chromium', 'webkit'
   const context = await browser.newContext();
   const page = await context.newPage();
 

chromium.js

@@ -1,17 +0,0 @@
-/**
- * Copyright 2017 Google Inc. All rights reserved.
- *
- * 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.
- */
-
-module.exports = require('./index').playwright('chromium');

docs/api.md

@@ -300,7 +300,7 @@
 Playwright module provides a method to launch a browser instance.
 The following is a typical example of using Playwright to drive automation:
 ```js
-const playwright = require('playwright')('chromium');  // Or 'firefox' or 'webkit'.
+const playwright = require('playwright').chromium;  // Or 'firefox' or 'webkit'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -329,7 +329,7 @@ Returns a list of devices to be used with [`page.emulate(options)`](#pageemulate
 devices can be found in [lib/deviceDescriptors.js](https://github.com/Microsoft/playwright/blob/master/src/deviceDescriptors.ts).
 
 ```js
-const playwright = require('playwright')('firefox');  // Or 'chromium' or 'webkit'.
+const playwright = require('playwright').firefox;  // Or 'chromium' or 'webkit'.
 const iPhone = playwright.devices['iPhone 6'];
 
 (async () => {
@@ -376,7 +376,7 @@ A Browser is created when Playwright connects to a browser instance, either thro
 
 An example of using a [Browser] to create a [Page]:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').firefox;  // Or 'chromium' or 'webkit'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -388,7 +388,7 @@ const playwright = require('playwright');
 
 An example of disconnecting from and reconnecting to a [Browser]:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').webkit;  // Or 'chromium' or 'firefox'.
 
 (async () => {
   const browserServer = await playwright.launchServer();
@@ -678,7 +678,7 @@ One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'
 
 An example of using `Dialog` class:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').chromium;  // Or 'firefox' or 'webkit'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -715,7 +715,7 @@ const playwright = require('playwright');
 ElementHandle represents an in-page DOM element. ElementHandles can be created with the [page.$](#pageselector) method.
 
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').chromium;  // Or 'firefox' or 'webkit'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -982,7 +982,7 @@ At every point of time, page exposes its current frame tree via the [page.mainFr
 An example of dumping frame tree:
 
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').firefox;  // Or 'chromium' or 'webkit'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -1413,7 +1413,7 @@ await page.waitFor(selector => !!document.querySelector(selector), {}, selector)
 
 The `waitForFunction` can be used to observe viewport size change:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').firefox;  // Or 'chromium' or 'webkit'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -1488,7 +1488,7 @@ immediately. If the selector doesn't appear after the `timeout` milliseconds of
 
 This method works across navigations:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').webkit;  // Or 'chromium' or 'firefox'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -1770,7 +1770,7 @@ Page provides methods to interact with a single tab or [extension background pag
 
 This example creates a page, navigates it to a URL, and then saves a screenshot:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').webkit;  // Or 'chromium' or 'firefox'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -2238,7 +2238,7 @@ If the `playwrightFunction` returns a [Promise], it will be awaited.
 
 An example of adding an `md5` function into the page:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').firefox;  // Or 'chromium' or 'webkit'.
 const crypto = require('crypto');
 
 (async () => {
@@ -2262,7 +2262,7 @@ const crypto = require('crypto');
 An example of adding a `window.readfile` function into the page:
 
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').chromium;  // Or 'firefox' or 'webkit'.
 const fs = require('fs');
 
 (async () => {
@@ -2758,7 +2758,7 @@ Waits for event to fire and passes its value into the predicate function. Resolv
 
 The `waitForFunction` can be used to observe viewport size change:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').webkit;  // Or 'chromium' or 'firefox'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -2866,7 +2866,7 @@ immediately. If the selector doesn't appear after the `timeout` milliseconds of
 
 This method works across navigations:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').chromium;  // Or 'firefox' or 'webkit'.
 
 (async () => {
   const browser = await playwright.launch();
@@ -3749,7 +3749,7 @@ Playwright can be used for testing Chrome Extensions.
 
 The following is code for getting a handle to the [background page](https://developer.chrome.com/extensions/background_pages) of an extension whose source is located in `./my-extension`:
 ```js
-const playwright = require('playwright');
+const playwright = require('playwright').chromium;
 
 (async () => {
   const pathToExtension = require('path').join(__dirname, 'my-extension');

docs/web.md

@@ -10,11 +10,10 @@ API consists of a single `connect` function, similar to
 [webkitPlaywright.connect(options)](api.md#webkitplaywrightconnectoptions).
 
 ```html
-<script src='../playwright/web.js'></script>
+<script src='playwright/web.js'></script>
 <script>
 async function usePlaywright() {
-  const connect = window.playwrightweb('chromium'); // or 'firefox', 'webkit'
+  const browser = await window.playwrightweb.chromium.connect(options); // or 'firefox', 'webkit'
-  const browser = await connect(options);
   // ... drive automation ...
   await browser.disconnect();
 }

firefox.js

@@ -1,17 +0,0 @@
-/**
- * Copyright 2017 Google Inc. All rights reserved.
- *
- * 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.
- */
-
-module.exports = require('./index').playwright('firefox');

index.d.ts

@@ -15,6 +15,7 @@
  */
 
 export * from './lib/api';
-export function playwright(browser: 'chromium'): import('./lib/api').ChromiumPlaywright;
+export const chromium: import('./lib/api').ChromiumPlaywright;
-export function playwright(browser: 'firefox'): import('./lib/api').FirefoxPlaywright;
+export const firefox: import('./lib/api').FirefoxPlaywright;
-export function playwright(browser: 'webkit'): import('./lib/api').WebKitPlaywright;
+export const webkit: import('./lib/api').WebKitPlaywright;
+export type PlaywrightWeb = typeof import('./lib/web');

index.js

@@ -19,17 +19,12 @@ const api = require('./lib/api');
 const packageJson = require('./package.json');
 
 for (const className in api) {
-  // Playwright-web excludes certain classes from bundle, e.g. BrowserFetcher.
   if (typeof api[className] === 'function')
     helper.installAsyncStackHooks(api[className]);
 }
 
-module.exports.playwright = browser => {
+module.exports = {
-  if (browser === 'chromium')
+  chromium: new api.ChromiumPlaywright(__dirname, packageJson.playwright.chromium_revision),
-    return new api.ChromiumPlaywright(__dirname, packageJson.playwright.chromium_revision);
+  firefox: new api.FirefoxPlaywright(__dirname, packageJson.playwright.firefox_revision),
-  if (browser === 'firefox')
+  webkit: new api.WebKitPlaywright(__dirname, packageJson.playwright.webkit_revision),
-    return new api.FirefoxPlaywright(__dirname, packageJson.playwright.firefox_revision);
-  if (browser === 'webkit')
-    return new api.WebKitPlaywright(__dirname, packageJson.playwright.webkit_revision);
-  throw new Error(`Unsupported browser "${browser}"`);
 };

src/web.ts

@@ -18,14 +18,9 @@ import { CRBrowser as ChromiumBrowser } from './chromium/crBrowser';
 import { FFBrowser as FirefoxBrowser } from './firefox/ffBrowser';
 import { WKBrowser as WebKitBrowser } from './webkit/wkBrowser';
 
-function connect(browser: 'chromium' | 'firefox' | 'webkit') {
+const connect = {
-  if (browser === 'chromium')
+  chromium: { connect: ChromiumBrowser.connect },
-    return ChromiumBrowser.connect;
+  firefox: { connect: FirefoxBrowser.connect },
-  if (browser === 'firefox')
+  webkit: { connect: WebKitBrowser.connect },
-    return FirefoxBrowser.connect;
+};
-  if (browser === 'webkit')
-    return WebKitBrowser.connect;
-  throw new Error(`Unsupported browser "${browser}"`);
-}
-
 export = connect;

test/assets/playwrightweb.html

@@ -1,8 +1,7 @@
 <script src='../../web.js'></script>
 <script>
 async function setup(product, connectOptions) {
-  window.connect = window.playwrightweb(product);
+  window.browser = await window.playwrightweb[product].connect(connectOptions);
-  window.browser = await window.connect(connectOptions);
   window.context = await window.browser.newContext();
   window.page = await window.context.newPage();
 }

test/chromium/browser.spec.js

@@ -17,7 +17,7 @@
 const path = require('path');
 const {spawn, execSync} = require('child_process');
 
-module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, playwrightPath}) {
+module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, playwrightPath, product}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;
   const {beforeAll, beforeEach, afterAll, afterEach} = testRunner;
@@ -40,7 +40,7 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
         // Disable DUMPIO to cleanly read stdout.
         dumpio: false,
       });
-      const res = spawn('node', [path.join(__dirname, '..', 'fixtures', 'closeme.js'), playwrightPath, JSON.stringify(options)]);
+      const res = spawn('node', [path.join(__dirname, '..', 'fixtures', 'closeme.js'), playwrightPath, product, JSON.stringify(options)]);
       let wsEndPointCallback;
       const wsEndPointPromise = new Promise(x => wsEndPointCallback = x);
       let output = '';

test/firefox/browser.spec.js

@@ -17,7 +17,7 @@
 const path = require('path');
 const {spawn, execSync} = require('child_process');
 
-module.exports.describe = function({testRunner, defaultBrowserOptions, playwright, playwrightPath}) {
+module.exports.describe = function({testRunner, defaultBrowserOptions, playwright, playwrightPath, product}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;
   const {beforeAll, beforeEach, afterAll, afterEach} = testRunner;
@@ -28,7 +28,7 @@ module.exports.describe = function({testRunner, defaultBrowserOptions, playwrigh
         // Disable DUMPIO to cleanly read stdout.
         dumpio: false,
       });
-      const res = spawn('node', [path.join(__dirname, '..', 'fixtures', 'closeme.js'), playwrightPath, JSON.stringify(options)]);
+      const res = spawn('node', [path.join(__dirname, '..', 'fixtures', 'closeme.js'), playwrightPath, product, JSON.stringify(options)]);
       let wsEndPointCallback;
       const wsEndPointPromise = new Promise(x => wsEndPointCallback = x);
       let output = '';

test/fixtures.spec.js

@@ -18,7 +18,7 @@
 const path = require('path');
 const {spawn} = require('child_process');
 
-module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, playwrightPath, FFOX, CHROMIUM, WEBKIT}) {
+module.exports.describe = function({testRunner, expect, product, playwrightPath, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;
   const {beforeAll, beforeEach, afterAll, afterEach} = testRunner;
@@ -26,14 +26,14 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
   describe('Fixtures', function() {
     it('dumpio option should work with pipe option ', async({server}) => {
       let dumpioData = '';
-      const res = spawn('node', [path.join(__dirname, 'fixtures', 'dumpio.js'), playwrightPath, 'use-pipe']);
+      const res = spawn('node', [path.join(__dirname, 'fixtures', 'dumpio.js'), playwrightPath, product, 'use-pipe']);
       res.stderr.on('data', data => dumpioData += data.toString('utf8'));
       await new Promise(resolve => res.on('close', resolve));
       expect(dumpioData).toContain('message from dumpio');
     });
     it('should dump browser process stderr', async({server}) => {
       let dumpioData = '';
-      const res = spawn('node', [path.join(__dirname, 'fixtures', 'dumpio.js'), playwrightPath]);
+      const res = spawn('node', [path.join(__dirname, 'fixtures', 'dumpio.js'), playwrightPath, product]);
       res.stderr.on('data', data => dumpioData += data.toString('utf8'));
       await new Promise(resolve => res.on('close', resolve));
       expect(dumpioData).toContain('message from dumpio');

test/fixtures/closeme.js

@@ -1,5 +1,5 @@
 (async() => {
-  const [, , playwrightRoot, options] = process.argv;
+  const [, , playwrightRoot, product, options] = process.argv;
-  const browserServer = await require(playwrightRoot).launchServer(JSON.parse(options));
+  const browserServer = await require(playwrightRoot)[product.toLowerCase()].launchServer(JSON.parse(options));
   console.log(browserServer.wsEndpoint());
 })();

test/fixtures/dumpio.js

@@ -4,7 +4,7 @@
     console.log('unhandledRejection', error.message);
   });
 
-  const [, , playwrightRoot, usePipe] = process.argv;
+  const [, , playwrightRoot, product, usePipe] = process.argv;
   const options = {
     pipe: usePipe === 'use-pipe',
     ignoreDefaultArgs: true,
@@ -14,10 +14,10 @@
     args: ['-e', 'console.error("message from dumpio")', '--']
   }
   console.error('using pipe: ' + options.pipe);
-  if (playwrightRoot.includes('firefox'))
+  if (product.toLowerCase() === 'firefox')
     options.args.push('-juggler', '-profile');
   try {
-    await require(playwrightRoot).launchServer(options);
+    await require(playwrightRoot)[product.toLowerCase()].launchServer(options);
     console.error('Browser launch unexpectedly succeeded.');
   } catch (e) {
   }

test/launcher.spec.js

@@ -72,11 +72,11 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
 
   describe('Top-level requires', function() {
     it('should require top-level Errors', async() => {
-      const Errors = require(path.join(utils.projectRoot(), '/Errors'));
+      const Errors = require(path.join(utils.projectRoot(), '/lib/errors.js'));
       expect(Errors.TimeoutError).toBe(playwright.errors.TimeoutError);
     });
     it('should require top-level DeviceDescriptors', async() => {
-      const Devices = require(path.join(utils.projectRoot(), '/DeviceDescriptors'));
+      const Devices = require(path.join(utils.projectRoot(), '/lib/deviceDescriptors.js')).DeviceDescriptors;
       expect(Devices['iPhone 6']).toBe(playwright.devices['iPhone 6']);
     });
   });

test/playwright.spec.js

@@ -36,7 +36,7 @@ module.exports.describe = ({testRunner, product, playwrightPath}) => {
   const LINUX = os.platform() === 'linux';
   const WIN = os.platform() === 'win32';
 
-  const playwright = require(playwrightPath);
+  const playwright = require(playwrightPath)[product.toLowerCase()];
 
   const headless = (process.env.HEADLESS || 'true').trim().toLowerCase() === 'true';
   const slowMo = parseInt((process.env.SLOW_MO || '0').trim(), 10);

test/test.js

@@ -81,7 +81,7 @@ if (process.env.BROWSER === 'firefox') {
   describe('Firefox', () => {
     testRunner.loadTests(require('./playwright.spec.js'), {
       product: 'Firefox',
-      playwrightPath: path.join(utils.projectRoot(), 'firefox.js'),
+      playwrightPath: utils.projectRoot(),
       testRunner,
     });
   });
@@ -89,7 +89,7 @@ if (process.env.BROWSER === 'firefox') {
   describe('WebKit', () => {
     testRunner.loadTests(require('./playwright.spec.js'), {
       product: 'WebKit',
-      playwrightPath: path.join(utils.projectRoot(), 'webkit.js'),
+      playwrightPath: utils.projectRoot(),
       testRunner,
     });
   });
@@ -97,7 +97,7 @@ if (process.env.BROWSER === 'firefox') {
   describe('Chromium', () => {
     testRunner.loadTests(require('./playwright.spec.js'), {
       product: 'Chromium',
-      playwrightPath: path.join(utils.projectRoot(), 'chromium.js'),
+      playwrightPath: utils.projectRoot(),
       testRunner,
     });
     if (process.env.COVERAGE)

utils/doclint/cli.js

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-const playwright = require('../../chromium');
+const playwright = require('../../index.js').chromium;
 const path = require('path');
 const Source = require('./Source');
 

web.d.ts

@@ -1,20 +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.
- */
-
-function connect(browser: 'chromium'): import('./lib/api').ChromiumBrowser.connect;
-function connect(browser: 'firefox'): import('./lib/api').FirefoxBrowser.connect;
-function connect(browser: 'webkit'): import('./lib/api').WebKitBrowser.connect;
-export = connect;

webkit.js

@@ -1,17 +0,0 @@
-/**
- * Copyright 2017 Google Inc. All rights reserved.
- *
- * 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.
- */
-
-module.exports = require('./index').playwright('webkit');