chore: include api.json into the Playwright package (#4003)

.gitignore

@@ -15,3 +15,4 @@ lib/
 /types/*
 jest-report.json
 drivers/
+/docs/api.json

package.json

@@ -21,11 +21,12 @@
     "lint": "npm run eslint && npm run tsc && npm run doc && npm run check-deps && npm run generate-channels && npm run test-types && npm run test-infra",
     "clean": "rimraf lib && rimraf types",
     "prepare": "node install-from-github.js",
-    "build": "node utils/runWebpack.js --mode='development' && tsc -p . && npm run generate-types",
+    "build": "node utils/runWebpack.js --mode='development' && tsc -p . && npm run generate-types && npm run generate-api-json",
     "watch": "node utils/watch.js",
     "test-types": "npm run generate-types && npx -p typescript@3.7.5 tsc -p utils/generate_types/test/tsconfig.json && npm run typecheck-tests",
     "generate-types": "node utils/generate_types/",
     "generate-channels": "node utils/generate_channels.js",
+    "generate-api-json": "node utils/doclint/generateApiJson.js > docs/api.json",
     "typecheck-tests": "tsc -p ./test/",
     "roll-browser": "node utils/roll_browser.js",
     "coverage": "node test/checkCoverage.js",
@@ -72,7 +73,6 @@
     "formidable": "^1.2.2",
     "ncp": "^2.0.0",
     "node-stream-zip": "^1.11.3",
-    "pkg": "^4.4.9",
     "socksv5": "0.0.6",
     "ts-loader": "^8.0.3",
     "typescript": "^4.0.2",

packages/common/.npmignore

@@ -31,7 +31,7 @@ lib/server/injected/
 !LICENSE
 !NOTICE
 # Include protocol and api docs, so that dependent packages can consume them.
-!api.md
+!api.json
 !protocol.yml
 # Include browser descriptors.
 !browsers.json

packages/playwright-driver/.gitignore

@@ -1 +0,0 @@
-api.json

packages/playwright-driver/main.js

@@ -1,71 +0,0 @@
-/**
- * Copyright Microsoft Corporation. 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.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-const util = require('util');
-
-const readFileAsync = util.promisify(fs.readFile);
-const writeFileAsync = util.promisify(fs.writeFile);
-
-(async () => {
-  if (process.argv.length === 2 || process.argv.some(arg => arg.includes('--help'))) {
-    console.log(`Usage:
-      './driver --print-api' - Prints the Playwright API to the stdout
-      './driver --print-readme'    - Prints the upstream Playwright README
-      './driver --install'   - Downloads the Playwright browsers
-      './driver --run'       - Executes the Playwright RPC server
-    `);
-    return;
-  }
-  // Playwright needs to launch the PrintDeps.exe which is embedded into the NPM package.
-  // Since it's packed with PKG, we have to move it out and set the new path as an environment
-  // variable so Playwright can use it.
-  if (os.platform() === 'win32') {
-    const printDepsPath = path.join(__dirname, '..', '..', 'bin', 'PrintDeps.exe');
-
-    const printDepsFile = await readFileAsync(printDepsPath);
-    const pwPrintDepsPath = path.join(os.tmpdir(), 'ms-playwright-print-deps.exe');
-    await writeFileAsync(pwPrintDepsPath, printDepsFile);
-
-    process.env.PW_PRINT_DEPS_WINDOWS_EXECUTABLE = pwPrintDepsPath;
-  }
-
-  if (process.argv[2] === '--print-api') {
-    console.log((await readFileAsync(path.join(__dirname, 'api.json'))).toString());
-    return;
-  }
-
-  if (process.argv[2] === '--print-readme') {
-    console.log((await readFileAsync(path.join(__dirname, '..', '..', 'README.md'))).toString());
-    return;
-  }
-
-  if (process.argv[2] === '--install') {
-    // Place the browsers.json file into the current working directory.
-    const browsersJSON = await readFileAsync(path.join(__dirname, '..', '..', 'browsers.json'));
-    const driverDir = path.dirname(process.argv[0]);
-    await writeFileAsync(path.join(driverDir, 'browsers.json'), browsersJSON);
-
-    await require('../../lib/install/installer').installBrowsersWithProgressBar(driverDir);
-    return;
-  }
-
-  if (process.argv[2] === '--run') {
-    require('../../lib/server');
-  }
-})();

packages/playwright-driver/package.json

@@ -1,11 +0,0 @@
-{
-  "name": "playwright-driver",
-  "private": true,
-  "version": "0.0.1",
-  "description": "Playwright driver",
-  "bin": "main.js",
-  "author": {
-    "name": "Microsoft Corporation"
-  },
-  "license": "Apache-2.0"
-}

src/driver.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+
+import * as fs from 'fs';
+import * as util from 'util';
+import { installDebugController } from './debug/debugController';
+import { DispatcherConnection } from './dispatchers/dispatcher';
+import { PlaywrightDispatcher } from './dispatchers/playwrightDispatcher';
+import { installBrowsersWithProgressBar } from './install/installer';
+import { Transport } from './protocol/transport';
+import { Electron } from './server/electron/electron';
+import { Playwright } from './server/playwright';
+import { gracefullyCloseAll } from './server/processLauncher';
+import { installTracer } from './trace/tracer';
+
+
+const readFileAsync = util.promisify(fs.readFile);
+const writeFileAsync = util.promisify(fs.writeFile);
+
+export async function copyPrintDeps(destination: string) {
+  const content = await readFileAsync(require.resolve('../bin/PrintDeps.exe'));
+  await writeFileAsync(destination, content);
+}
+
+export async function installWithProgressBar(location: string) {
+  await installBrowsersWithProgressBar(location);
+}
+
+export async function apiJson(): Promise<string> {
+  return (await readFileAsync(require.resolve('../docs/api.json'))).toString();
+}
+
+export function runServer() {
+  installDebugController();
+  installTracer();
+
+  const dispatcherConnection = new DispatcherConnection();
+  const transport = new Transport(process.stdout, process.stdin);
+  transport.onclose = async () => {
+    // Force exit after 30 seconds.
+    setTimeout(() => process.exit(0), 30000);
+    // Meanwhile, try to gracefully close all browsers.
+    await gracefullyCloseAll();
+    process.exit(0);
+  };
+  transport.onmessage = message => dispatcherConnection.dispatch(JSON.parse(message));
+  dispatcherConnection.onmessage = message => transport.send(JSON.stringify(message));
+
+  const playwright = new Playwright(__dirname, require('../browsers.json')['browsers']);
+  (playwright as any).electron = new Electron();
+  new PlaywrightDispatcher(dispatcherConnection.rootDispatcher(), playwright);
+}

src/server.ts

@@ -1,43 +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.
- */
-
-import { Transport } from './protocol/transport';
-import { DispatcherConnection } from './dispatchers/dispatcher';
-import { Playwright } from './server/playwright';
-import { PlaywrightDispatcher } from './dispatchers/playwrightDispatcher';
-import { Electron } from './server/electron/electron';
-import { gracefullyCloseAll } from './server/processLauncher';
-import { installDebugController } from './debug/debugController';
-import { installTracer } from './trace/tracer';
-
-installDebugController();
-installTracer();
-
-const dispatcherConnection = new DispatcherConnection();
-const transport = new Transport(process.stdout, process.stdin);
-transport.onclose = async () => {
-  // Force exit after 30 seconds.
-  setTimeout(() => process.exit(0), 30000);
-  // Meanwhile, try to gracefully close all browsers.
-  await gracefullyCloseAll();
-  process.exit(0);
-};
-transport.onmessage = message => dispatcherConnection.dispatch(JSON.parse(message));
-dispatcherConnection.onmessage = message => transport.send(JSON.stringify(message));
-
-const playwright = new Playwright(__dirname, require('../browsers.json')['browsers']);
-(playwright as any).electron = new Electron();
-new PlaywrightDispatcher(dispatcherConnection.rootDispatcher(), playwright);

utils/build_driver.sh

@@ -1,11 +0,0 @@
-#/bin/bash
-
-set -e
-
-echo "Generating API"
-node utils/doclint/dumpTypes.js > packages/playwright-driver/api.json
-echo "Generated API successfully"
-
-echo "Building RPC drivers"
-node_modules/.bin/pkg --public --targets node12-linux-x64,node12-macos-x64,node12-win-x64 --out-path=drivers -c packages/playwright-driver/package.json packages/playwright-driver/main.js
-echo "Built RPC drivers successfully"

utils/doclint/generateApiJson.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-const playwright = require('../../');
+const playwright = require('../..');
 const path = require('path');
 const Source = require('./Source');
 const mdBuilder = require('./check_public_api/MDBuilder');
@@ -26,7 +26,7 @@ const PROJECT_DIR = path.join(__dirname, '..', '..');
   const page = await browser.newPage();
   const { documentation } = await mdBuilder(page, [api]);
   const result = serialize(documentation);
-  console.log(JSON.stringify(result, undefined, 2));
+  console.log(JSON.stringify(result));
   await browser.close();
 })()
 
@@ -47,8 +47,7 @@ function serializeClass(clazz) {
 
 function serializeMember(member) {
   const result = { ...member };
-  delete result.args;
+  sanitize(result);
-  delete result.argsArray;
   result.args = {};
   for (const arg of member.argsArray)
     result.args[arg.name] = serializeProperty(arg);
@@ -59,19 +58,28 @@ function serializeMember(member) {
 
 function serializeProperty(arg) {
   const result = { ...arg };
-  delete result.args;
+  sanitize(result);
-  delete result.argsArray;
   if (arg.type)
     result.type = serializeType(arg.type)
   return result;
 }
 
+function sanitize(result) {
+  delete result.args;
+  delete result.argsArray;
+  delete result.templates;
+  if (result.properties && !Object.keys(result.properties).length)
+    delete result.properties;
+}
+
 function serializeType(type) {
   const result = { ...type };
-  if (type.properties) {
+  if (type.properties && type.properties.length) {
     result.properties = {};
     for (const prop of type.properties)
       result.properties[prop.name] = serializeProperty(prop);
+  } else {
+    delete result.properties;
   }
   return result;
 }