feat(rpc): introduce protocol.pdl (#3054)

We now generate channels.ts from the protocol definition. There are still some shortcomings,
like union types - these will be addressed in follow ups.

Author: dgozman

src/rpc/channels.ts

@@ -29,6 +29,6 @@ export class Accessibility {
   async snapshot(options: { interestingOnly?: boolean; root?: ElementHandle } = {}): Promise<types.SerializedAXNode | null> {
     const root = options.root ? options.root._elementChannel : undefined;
     const result = await this._channel.accessibilitySnapshot({ interestingOnly: options.interestingOnly, root });
-    return result.rootAXNode;
+    return result.rootAXNode || null;
   }
 }

src/rpc/client/accessibility.ts

@@ -15,7 +15,7 @@
  */
 
 import * as types from '../../types';
-import { BrowserChannel, BrowserInitializer, BrowserContextOptions } from '../channels';
+import { BrowserChannel, BrowserInitializer, BrowserNewContextParams } from '../channels';
 import { BrowserContext } from './browserContext';
 import { Page } from './page';
 import { ChannelOwner } from './channelOwner';
@@ -55,7 +55,7 @@ export class Browser extends ChannelOwner<BrowserChannel, BrowserInitializer> {
     const logger = options.logger;
     options = { ...options, logger: undefined };
     return this._wrapApiCall('browser.newContext', async () => {
-      const contextOptions: BrowserContextOptions = {
+      const contextOptions: BrowserNewContextParams = {
         ...options,
         extraHTTPHeaders: options.extraHTTPHeaders ? headersObjectToArray(options.extraHTTPHeaders) : undefined,
       };

src/rpc/client/browser.ts

@@ -141,7 +141,7 @@ export class BrowserContext extends ChannelOwner<BrowserContextChannel, BrowserC
 
   async setGeolocation(geolocation: types.Geolocation | null): Promise<void> {
     return this._wrapApiCall('browserContext.setGeolocation', async () => {
-      await this._channel.setGeolocation({ geolocation });
+      await this._channel.setGeolocation({ geolocation: geolocation || undefined });
     });
   }
 
@@ -159,7 +159,7 @@ export class BrowserContext extends ChannelOwner<BrowserContextChannel, BrowserC
 
   async setHTTPCredentials(httpCredentials: types.Credentials | null): Promise<void> {
     return this._wrapApiCall('browserContext.setHTTPCredentials', async () => {
-      await this._channel.setHTTPCredentials({ httpCredentials });
+      await this._channel.setHTTPCredentials({ httpCredentials: httpCredentials || undefined });
     });
   }
 

src/rpc/client/browserContext.ts

@@ -15,7 +15,7 @@
  */
 
 import * as types from '../../types';
-import { BrowserTypeChannel, BrowserTypeInitializer, LaunchPersistentContextOptions, LaunchOptions, LaunchServerOptions } from '../channels';
+import { BrowserTypeChannel, BrowserTypeInitializer, BrowserTypeLaunchParams, BrowserTypeLaunchServerParams, BrowserTypeLaunchPersistentContextParams } from '../channels';
 import { Browser } from './browser';
 import { BrowserContext } from './browserContext';
 import { ChannelOwner } from './channelOwner';
@@ -45,7 +45,7 @@ export class BrowserType extends ChannelOwner<BrowserTypeChannel, BrowserTypeIni
     const logger = options.logger;
     options = { ...options, logger: undefined };
     return this._wrapApiCall('browserType.launch', async () => {
-      const launchOptions: LaunchOptions = {
+      const launchOptions: BrowserTypeLaunchParams = {
         ...options,
         ignoreDefaultArgs: Array.isArray(options.ignoreDefaultArgs) ? options.ignoreDefaultArgs : undefined,
         ignoreAllDefaultArgs: !!options.ignoreDefaultArgs && !Array.isArray(options.ignoreDefaultArgs),
@@ -61,7 +61,7 @@ export class BrowserType extends ChannelOwner<BrowserTypeChannel, BrowserTypeIni
     const logger = options.logger;
     options = { ...options, logger: undefined };
     return this._wrapApiCall('browserType.launchServer', async () => {
-      const launchServerOptions: LaunchServerOptions = {
+      const launchServerOptions: BrowserTypeLaunchServerParams = {
         ...options,
         ignoreDefaultArgs: Array.isArray(options.ignoreDefaultArgs) ? options.ignoreDefaultArgs : undefined,
         ignoreAllDefaultArgs: !!options.ignoreDefaultArgs && !Array.isArray(options.ignoreDefaultArgs),
@@ -75,7 +75,7 @@ export class BrowserType extends ChannelOwner<BrowserTypeChannel, BrowserTypeIni
     const logger = options.logger;
     options = { ...options, logger: undefined };
     return this._wrapApiCall('browserType.launchPersistentContext', async () => {
-      const persistentOptions: LaunchPersistentContextOptions = {
+      const persistentOptions: BrowserTypeLaunchPersistentContextParams = {
         ...options,
         ignoreDefaultArgs: Array.isArray(options.ignoreDefaultArgs) ? options.ignoreDefaultArgs : undefined,
         ignoreAllDefaultArgs: !!options.ignoreDefaultArgs && !Array.isArray(options.ignoreDefaultArgs),

src/rpc/client/browserType.ts

@@ -37,11 +37,11 @@ export class Download extends ChannelOwner<DownloadChannel, DownloadInitializer>
   }
 
   async path(): Promise<string | null> {
-    return (await this._channel.path()).value;
+    return (await this._channel.path()).value || null;
   }
 
   async failure(): Promise<string | null> {
-    return (await this._channel.failure()).error;
+    return (await this._channel.failure()).error || null;
   }
 
   async createReadStream(): Promise<Readable | null> {

src/rpc/client/download.ts

@@ -15,17 +15,18 @@
  */
 
 import * as types from '../../types';
-import { ElectronChannel, ElectronInitializer, ElectronLaunchOptions, ElectronApplicationChannel, ElectronApplicationInitializer } from '../channels';
+import { ElectronChannel, ElectronInitializer, ElectronApplicationChannel, ElectronApplicationInitializer, ElectronLaunchParams } from '../channels';
 import { BrowserContext } from './browserContext';
 import { ChannelOwner } from './channelOwner';
 import { Page } from './page';
 import { serializeArgument, FuncOn, parseResult, SmartHandle, JSHandle } from './jsHandle';
-import { ElectronEvents } from '../../server/electron';
+import { ElectronEvents, ElectronLaunchOptionsBase } from '../../server/electron';
 import { TimeoutSettings } from '../../timeoutSettings';
 import { Waiter } from './waiter';
 import { TimeoutError } from '../../errors';
 import { Events } from '../../events';
 import { LoggerSink } from '../../loggerSink';
+import { envObjectToArray } from '../serializers';
 
 export class Electron extends ChannelOwner<ElectronChannel, ElectronInitializer> {
   static from(electron: ElectronChannel): Electron {
@@ -36,11 +37,16 @@ export class Electron extends ChannelOwner<ElectronChannel, ElectronInitializer>
     super(parent, type, guid, initializer, true);
   }
 
-  async launch(executablePath: string, options: ElectronLaunchOptions & { logger?: LoggerSink } = {}): Promise<ElectronApplication> {
+  async launch(executablePath: string, options: ElectronLaunchOptionsBase & { logger?: LoggerSink } = {}): Promise<ElectronApplication> {
     const logger = options.logger;
     options = { ...options, logger: undefined };
     return this._wrapApiCall('electron.launch', async () => {
-      return ElectronApplication.from((await this._channel.launch({ executablePath, ...options })).electronApplication);
+      const params: ElectronLaunchParams = {
+        ...options,
+        env: options.env ? envObjectToArray(options.env) : undefined,
+        executablePath,
+      };
+      return ElectronApplication.from((await this._channel.launch(params)).electronApplication);
     }, logger);
   }
 }

src/rpc/client/electron.ts

@@ -29,7 +29,7 @@ export class ElementHandle<T extends Node = Node> extends JSHandle<T> {
     return (handle as any)._object;
   }
 
-  static fromNullable(handle: ElementHandleChannel | null): ElementHandle | null {
+  static fromNullable(handle: ElementHandleChannel | undefined): ElementHandle | null {
     return handle ? ElementHandle.from(handle) : null;
   }
 
@@ -56,13 +56,15 @@ export class ElementHandle<T extends Node = Node> extends JSHandle<T> {
 
   async getAttribute(name: string): Promise<string | null> {
     return this._wrapApiCall('elementHandle.getAttribute', async () => {
-      return (await this._elementChannel.getAttribute({ name })).value;
+      const value = (await this._elementChannel.getAttribute({ name })).value;
+      return value === undefined ? null : value;
     });
   }
 
   async textContent(): Promise<string | null> {
     return this._wrapApiCall('elementHandle.textContent', async () => {
-      return (await this._elementChannel.textContent()).value;
+      const value = (await this._elementChannel.textContent()).value;
+      return value === undefined ? null : value;
     });
   }
 
@@ -165,7 +167,8 @@ export class ElementHandle<T extends Node = Node> extends JSHandle<T> {
 
   async boundingBox(): Promise<types.Rect | null> {
     return this._wrapApiCall('elementHandle.boundingBox', async () => {
-      return (await this._elementChannel.boundingBox()).value;
+      const value = (await this._elementChannel.boundingBox()).value;
+      return value === undefined ? null : value;
     });
   }
 

src/rpc/client/elementHandle.ts

@@ -53,7 +53,7 @@ export class Frame extends ChannelOwner<FrameChannel, FrameInitializer> {
     return (frame as any)._object;
   }
 
-  static fromNullable(frame: FrameChannel | null): Frame | null {
+  static fromNullable(frame: FrameChannel | undefined): Frame | null {
     return frame ? Frame.from(frame) : null;
   }
 
@@ -132,7 +132,7 @@ export class Frame extends ChannelOwner<FrameChannel, FrameInitializer> {
         });
       }
 
-      const request = navigatedEvent.newDocument ? network.Request.fromNullable(navigatedEvent.newDocument.request || null) : null;
+      const request = navigatedEvent.newDocument ? network.Request.fromNullable(navigatedEvent.newDocument.request) : null;
       const response = request ? await waiter.waitForPromise(request._finalRequest().response()) : null;
       waiter.dispose();
       return response;
@@ -306,7 +306,8 @@ export class Frame extends ChannelOwner<FrameChannel, FrameInitializer> {
 
   async textContent(selector: string, options: types.TimeoutOptions = {}): Promise<null|string> {
     return this._wrapApiCall(this._apiName('textContent'), async () => {
-      return (await this._channel.textContent({ selector, ...options })).value;
+      const value = (await this._channel.textContent({ selector, ...options })).value;
+      return value === undefined ? null : value;
     });
   }
 
@@ -324,7 +325,8 @@ export class Frame extends ChannelOwner<FrameChannel, FrameInitializer> {
 
   async getAttribute(selector: string, name: string, options: types.TimeoutOptions = {}): Promise<string | null> {
     return this._wrapApiCall(this._apiName('getAttribute'), async () => {
-      return (await this._channel.getAttribute({ selector, name, ...options })).value;
+      const value = (await this._channel.getAttribute({ selector, name, ...options })).value;
+      return value === undefined ? null : value;
     });
   }
 

src/rpc/client/frame.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { JSHandleChannel, JSHandleInitializer, SerializedArgument, Channel } from '../channels';
+import { JSHandleChannel, JSHandleInitializer, SerializedArgument, SerializedValue, Channel } from '../channels';
 import { ElementHandle } from './elementHandle';
 import { ChannelOwner } from './channelOwner';
-import { serializeAsCallArgument, parseEvaluationResultValue, SerializedValue } from '../../common/utilityScriptSerializers';
+import { serializeAsCallArgument, parseEvaluationResultValue } from '../../common/utilityScriptSerializers';
 
 type NoHandles<Arg> = Arg extends JSHandle ? never : (Arg extends object ? { [Key in keyof Arg]: NoHandles<Arg[Key]> } : Arg);
 type Unboxed<Arg> =
@@ -42,10 +42,6 @@ export class JSHandle<T = any> extends ChannelOwner<JSHandleChannel, JSHandleIni
     return (handle as any)._object;
   }
 
-  static fromNullable(handle: JSHandleChannel | null): JSHandle | null {
-    return handle ? JSHandle.from(handle) : null;
-  }
-
   constructor(parent: ChannelOwner, type: string, guid: string, initializer: JSHandleInitializer) {
     super(parent, type, guid, initializer);
     this._preview = this._initializer.preview;
@@ -112,5 +108,5 @@ export function serializeArgument(arg: any): SerializedArgument {
 }
 
 export function parseResult(arg: SerializedValue): any {
-  return parseEvaluationResultValue(arg, []);
+  return parseEvaluationResultValue(arg as any, []);
 }