api: introduce Browser.version() (microsoft#3177)

docs/api.md

@@ -155,6 +155,7 @@ See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific
 - [browser.isConnected()](#browserisconnected)
 - [browser.newContext([options])](#browsernewcontextoptions)
 - [browser.newPage([options])](#browsernewpageoptions)
+- [browser.version()](#browserversion)
 <!-- GEN:stop -->
 
 #### event: 'disconnected'
@@ -266,6 +267,12 @@ Creates a new page in a new browser context. Closing this page will close the co
 
 This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and testing frameworks should explicitly create [browser.newContext](#browsernewcontextoptions) followed by the [browserContext.newPage](#browsercontextnewpage) to control their exact life times.
 
+#### browser.version()
+
+- returns: <[string]>
+
+Returns the browser version.
+
 ### class: BrowserContext
 
 * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
@@ -4180,6 +4187,7 @@ await browser.stopTracing();
 - [browser.isConnected()](#browserisconnected)
 - [browser.newContext([options])](#browsernewcontextoptions)
 - [browser.newPage([options])](#browsernewpageoptions)
+- [browser.version()](#browserversion)
 <!-- GEN:stop -->
 
 #### chromiumBrowser.newBrowserCDPSession()
@@ -4387,6 +4395,7 @@ Firefox browser instance does not expose Firefox-specific features.
 - [browser.isConnected()](#browserisconnected)
 - [browser.newContext([options])](#browsernewcontextoptions)
 - [browser.newPage([options])](#browsernewpageoptions)
+- [browser.version()](#browserversion)
 <!-- GEN:stop -->
 
 ### class: WebKitBrowser
@@ -4402,6 +4411,7 @@ WebKit browser instance does not expose WebKit-specific features.
 - [browser.isConnected()](#browserisconnected)
 - [browser.newContext([options])](#browsernewcontextoptions)
 - [browser.newPage([options])](#browsernewpageoptions)
+- [browser.version()](#browserversion)
 <!-- GEN:stop -->
 
 ### Environment Variables

src/browser.ts

@@ -44,6 +44,7 @@ export interface Browser extends EventEmitter {
   newPage(options?: BrowserContextOptions): Promise<Page>;
   isConnected(): boolean;
   close(): Promise<void>;
+  version(): string;
 }
 
 export abstract class BrowserBase extends EventEmitter implements Browser {
@@ -61,6 +62,7 @@ export abstract class BrowserBase extends EventEmitter implements Browser {
   abstract contexts(): BrowserContext[];
   abstract isConnected(): boolean;
   abstract _disconnect(): void;
+  abstract version(): string;
 
   async newPage(options?: BrowserContextOptions): Promise<Page> {
     const context = await this.newContext(options);

src/chromium/crBrowser.ts

@@ -41,6 +41,7 @@ export class CRBrowser extends BrowserBase {
   _serviceWorkers = new Map<string, CRServiceWorker>();
   _devtools?: CRDevTools;
   _isMac = false;
+  private _version = '';
 
   private _tracingRecording = false;
   private _tracingPath: string | null = '';
@@ -53,6 +54,7 @@ export class CRBrowser extends BrowserBase {
     const session = connection.rootSession;
     const version = await session.send('Browser.getVersion');
     browser._isMac = version.userAgent.includes('Macintosh');
+    browser._version = version.product.substring(version.product.indexOf('/') + 1);
     if (!options.persistent) {
       await session.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
       return browser;
@@ -110,6 +112,10 @@ export class CRBrowser extends BrowserBase {
     return Array.from(this._contexts.values());
   }
 
+  version(): string {
+    return this._version;
+  }
+
   _onAttachedToTarget({targetInfo, sessionId, waitingForDebugger}: Protocol.Target.attachedToTargetPayload) {
     if (targetInfo.type === 'browser')
       return;

src/firefox/ffBrowser.ts

@@ -33,12 +33,14 @@ export class FFBrowser extends BrowserBase {
   readonly _ffPages: Map<string, FFPage>;
   readonly _contexts: Map<string, FFBrowserContext>;
   private _eventListeners: RegisteredListener[];
+  private _version = '';
 
   static async connect(transport: ConnectionTransport, options: BrowserOptions): Promise<FFBrowser> {
     const connection = new FFConnection(SlowMoTransport.wrap(transport, options.slowMo), options.loggers);
     const browser = new FFBrowser(connection, options);
     const promises: Promise<any>[] = [
       connection.send('Browser.enable', { attachToDefaultContext: !!options.persistent }),
+      browser._initVersion(),
     ];
     if (options.persistent) {
       browser._defaultContext = new FFBrowserContext(browser, null, options.persistent);
@@ -62,6 +64,11 @@ export class FFBrowser extends BrowserBase {
     ];
   }
 
+  async _initVersion() {
+    const result = await this._connection.send('Browser.getInfo');
+    this._version = result.version.substring(result.version.indexOf('/') + 1);
+  }
+
   isConnected(): boolean {
     return !this._connection._closed;
   }
@@ -81,6 +88,10 @@ export class FFBrowser extends BrowserBase {
     return Array.from(this._contexts.values());
   }
 
+  version(): string {
+    return this._version;
+  }
+
   _onDetachedFromTarget(payload: Protocol.Browser.detachedFromTargetPayload) {
     const ffPage = this._ffPages.get(payload.targetId)!;
     this._ffPages.delete(payload.targetId);

src/rpc/channels.ts

@@ -284,7 +284,9 @@ export type BrowserServerKillParams = {};
 export type BrowserServerKillResult = void;
 
 // ----------- Browser -----------
-export type BrowserInitializer = {};
+export type BrowserInitializer = {
+  version: string,
+};
 export interface BrowserChannel extends Channel {
   on(event: 'close', callback: (params: BrowserCloseEvent) => void): this;
   close(params?: BrowserCloseParams): Promise<BrowserCloseResult>;

src/rpc/client/browser.ts

@@ -71,6 +71,10 @@ export class Browser extends ChannelOwner<BrowserChannel, BrowserInitializer> {
     return [...this._contexts];
   }
 
+  version(): string {
+    return this._initializer.version;
+  }
+
   async newPage(options: types.BrowserContextOptions & { logger?: LoggerSink } = {}): Promise<Page> {
     const context = await this.newContext(options);
     const page = await context.newPage();

src/rpc/protocol.yml

@@ -362,6 +362,9 @@ BrowserServer:
 Browser:
   type: interface
 
+  initializer:
+    version: string
+
   commands:
 
     close:

src/rpc/server/browserDispatcher.ts

@@ -27,7 +27,7 @@ import { headersArrayToObject } from '../serializers';
 
 export class BrowserDispatcher extends Dispatcher<Browser, BrowserInitializer> implements BrowserChannel {
   constructor(scope: DispatcherScope, browser: BrowserBase) {
-    super(scope, browser, 'Browser', {}, true);
+    super(scope, browser, 'Browser', { version: browser.version() }, true);
     browser.on(Events.Browser.Disconnected, () => {
       this._dispatchEvent('close');
       this._dispose();

src/webkit/wkBrowser.ts

@@ -28,6 +28,7 @@ import { kPageProxyMessageReceived, PageProxyMessageReceivedPayload, WKConnectio
 import { WKPage } from './wkPage';
 
 const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Safari/605.1.15';
+const BROWSER_VERSION = '14.0';
 
 export class WKBrowser extends BrowserBase {
   private readonly _connection: WKConnection;
@@ -85,6 +86,10 @@ export class WKBrowser extends BrowserBase {
     return Array.from(this._contexts.values());
   }
 
+  version(): string {
+    return BROWSER_VERSION;
+  }
+
   _onDownloadCreated(payload: Protocol.Playwright.downloadCreatedPayload) {
     const page = this._wkPages.get(payload.pageProxyId);
     if (!page)

test/browser.jest.js

@@ -38,3 +38,13 @@ describe('Browser.newPage', function() {
     expect(error.message).toContain('Please use browser.newContext()');
   });
 });
+
+describe('Browser.version', function() {
+  it('should work', async function({browser}) {
+    const version = browser.version();
+    if (CHROMIUM)
+      expect(version.match(/^\d+\.\d+\.\d+\.\d+$/)).toBeTruthy();
+    else
+      expect(version.match(/^\d+\.\d+$/)).toBeTruthy();
+  });
+});