playwright/src/server/browserType.ts

/**
 * 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 os from 'os';
import * as path from 'path';
import * as util from 'util';
import { BrowserContext, PersistentContextOptions, validatePersistentContextOptions } from '../browserContext';
import { BrowserServer, WebSocketWrapper } from './browserServer';
import * as browserPaths from '../install/browserPaths';
import { Logger, RootLogger, InnerLogger } from '../logger';
import { ConnectionTransport, WebSocketTransport } from '../transport';
import { BrowserBase, BrowserOptions, Browser } from '../browser';
import { assert, helper } from '../helper';
import { TimeoutSettings } from '../timeoutSettings';
import { launchProcess, Env, waitForLine } from './processLauncher';
import { Events } from '../events';
import { TimeoutError } from '../errors';
import { PipeTransport } from './pipeTransport';

export type BrowserArgOptions = {
  headless?: boolean,
  args?: string[],
  devtools?: boolean,
};

type LaunchOptionsBase = BrowserArgOptions & {
  executablePath?: string,
  ignoreDefaultArgs?: boolean | string[],
  handleSIGINT?: boolean,
  handleSIGTERM?: boolean,
  handleSIGHUP?: boolean,
  timeout?: number,
  logger?: Logger,
  env?: Env,
};

export function processBrowserArgOptions(options: LaunchOptionsBase): { devtools: boolean, headless: boolean } {
  const { devtools = false, headless = !devtools } = options;
  return { devtools, headless };
}

type ConnectOptions = {
  wsEndpoint: string,
  slowMo?: number,
  logger?: Logger,
  timeout?: number,
};
export type LaunchType = 'local' | 'server' | 'persistent';
export type LaunchOptions = LaunchOptionsBase & { slowMo?: number };
type LaunchServerOptions = LaunchOptionsBase & { port?: number };

export interface BrowserType {
  executablePath(): string;
  name(): string;
  launch(options?: LaunchOptions): Promise<Browser>;
  launchServer(options?: LaunchServerOptions): Promise<BrowserServer>;
  launchPersistentContext(userDataDir: string, options?: LaunchOptions & PersistentContextOptions): Promise<BrowserContext>;
  connect(options: ConnectOptions): Promise<Browser>;
}

const mkdtempAsync = util.promisify(fs.mkdtemp);

export abstract class BrowserTypeBase implements BrowserType {
  private _name: string;
  private _executablePath: string | undefined;
  private _webSocketRegexNotPipe: RegExp | null;
  readonly _browserPath: string;

  constructor(packagePath: string, browser: browserPaths.BrowserDescriptor, webSocketRegexNotPipe: RegExp | null) {
    this._name = browser.name;
    const browsersPath = browserPaths.browsersPath(packagePath);
    this._browserPath = browserPaths.browserDirectory(browsersPath, browser);
    this._executablePath = browserPaths.executablePath(this._browserPath, browser);
    this._webSocketRegexNotPipe = webSocketRegexNotPipe;
  }

  executablePath(): string {
    if (!this._executablePath)
      throw new Error('Browser is not supported on current platform');
    return this._executablePath;
  }

  name(): string {
    return this._name;
  }

  async launch(options: LaunchOptions = {}): Promise<Browser> {
    assert(!(options as any).userDataDir, 'userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistentContext` instead');
    return this._innerLaunch('local', options, undefined);
  }

  async launchPersistentContext(userDataDir: string, options: LaunchOptions & PersistentContextOptions = {}): Promise<BrowserContext> {
    const persistent = validatePersistentContextOptions(options);
    const browser = await this._innerLaunch('persistent', options, persistent, userDataDir);
    return browser._defaultContext!;
  }

  async _innerLaunch(launchType: LaunchType, options: LaunchOptions, persistent: PersistentContextOptions | undefined, userDataDir?: string): Promise<BrowserBase> {
    const deadline = TimeoutSettings.computeDeadline(options.timeout, 30000);
    const logger = new RootLogger(options.logger);
    logger.startLaunchRecording();

    let browserServer: BrowserServer | undefined;
    try {
      browserServer = await this._launchServer(options, launchType, logger, deadline, userDataDir);
      const promise = this._innerLaunchPromise(browserServer, options, persistent);
      const browser = await helper.waitWithDeadline(promise, 'the browser to launch', deadline, 'pw:browser*');
      return browser;
    } catch (e) {
      e.message += '\n=============== Process output during launch: ===============\n' +
          logger.launchRecording() +
          '\n=============================================================';
      if (browserServer)
        await browserServer._closeOrKill(deadline);
      throw e;
    } finally {
      logger.stopLaunchRecording();
    }
  }

  async _innerLaunchPromise(browserServer: BrowserServer, options: LaunchOptions, persistent: PersistentContextOptions | undefined): Promise<BrowserBase> {
    if ((options as any).__testHookBeforeCreateBrowser)
      await (options as any).__testHookBeforeCreateBrowser();

    const browserOptions: BrowserOptions = {
      slowMo: options.slowMo,
      persistent,
      headful: browserServer._headful,
      logger: browserServer._logger,
      downloadsPath: browserServer._downloadsPath,
      ownedServer: browserServer,
    };
    for (const [key, value] of Object.entries(options)) {
      if (key.startsWith('__testHook'))
        (browserOptions as any)[key] = value;
    }

    const browser = await this._connectToTransport(browserServer._transport, browserOptions);
    if (persistent && (!options.ignoreDefaultArgs || Array.isArray(options.ignoreDefaultArgs))) {
      const context = browser._defaultContext!;
      await context._loadDefaultContext();
    }
    return browser;
  }

  async launchServer(options: LaunchServerOptions = {}): Promise<BrowserServer> {
    const logger = new RootLogger(options.logger);
    return this._launchServer(options, 'server', logger, TimeoutSettings.computeDeadline(options.timeout, 30000));
  }

  async connect(options: ConnectOptions): Promise<Browser> {
    const deadline = TimeoutSettings.computeDeadline(options.timeout, 30000);
    const logger = new RootLogger(options.logger);
    logger.startLaunchRecording();

    let transport: ConnectionTransport | undefined;
    try {
      transport = await WebSocketTransport.connect(options.wsEndpoint, logger, deadline);
      const promise = this._innerConnectPromise(transport, options, logger);
      const browser = await helper.waitWithDeadline(promise, 'connect to browser', deadline, 'pw:browser*');
      logger.stopLaunchRecording();
      return browser;
    } catch (e) {
      e.message += '\n=============== Process output during connect: ===============\n' +
          logger.launchRecording() +
          '\n=============================================================';
      try {
        if (transport)
          transport.close();
      } catch (e) {
      }
      throw e;
    } finally {
      logger.stopLaunchRecording();
    }
  }

  async _innerConnectPromise(transport: ConnectionTransport, options: ConnectOptions, logger: RootLogger): Promise<Browser> {
    if ((options as any).__testHookBeforeCreateBrowser)
      await (options as any).__testHookBeforeCreateBrowser();
    return this._connectToTransport(transport, { slowMo: options.slowMo, logger });
  }

  private async _launchServer(options: LaunchServerOptions, launchType: LaunchType, logger: RootLogger, deadline: number, userDataDir?: string): Promise<BrowserServer> {
    const {
      ignoreDefaultArgs = false,
      args = [],
      executablePath = null,
      env = process.env,
      handleSIGINT = true,
      handleSIGTERM = true,
      handleSIGHUP = true,
      port = 0,
    } = options;
    assert(!port || launchType === 'server', 'Cannot specify a port without launching as a server.');

    let temporaryUserDataDir: string | null = null;
    if (!userDataDir) {
      userDataDir = await mkdtempAsync(path.join(os.tmpdir(), `playwright_${this._name}dev_profile-`));
      temporaryUserDataDir = userDataDir;
    }

    const browserArguments = [];
    if (!ignoreDefaultArgs)
      browserArguments.push(...this._defaultArgs(options, launchType, userDataDir));
    else if (Array.isArray(ignoreDefaultArgs))
      browserArguments.push(...this._defaultArgs(options, launchType, userDataDir).filter(arg => ignoreDefaultArgs.indexOf(arg) === -1));
    else
      browserArguments.push(...args);

    const executable = executablePath || this.executablePath();
    if (!executable)
      throw new Error(`No executable path is specified. Pass "executablePath" option directly.`);

    // Note: it is important to define these variables before launchProcess, so that we don't get
    // "Cannot access 'browserServer' before initialization" if something went wrong.
    let transport: ConnectionTransport | undefined = undefined;
    let browserServer: BrowserServer | undefined = undefined;
    const { launchedProcess, gracefullyClose, downloadsPath } = await launchProcess({
      executablePath: executable,
      args: browserArguments,
      env: this._amendEnvironment(env, userDataDir, executable, browserArguments),
      handleSIGINT,
      handleSIGTERM,
      handleSIGHUP,
      logger,
      pipe: !this._webSocketRegexNotPipe,
      tempDir: temporaryUserDataDir || undefined,
      attemptToGracefullyClose: async () => {
        if ((options as any).__testHookGracefullyClose)
          await (options as any).__testHookGracefullyClose();
        // We try to gracefully close to prevent crash reporting and core dumps.
        // Note that it's fine to reuse the pipe transport, since
        // our connection ignores kBrowserCloseMessageId.
        this._attemptToGracefullyCloseBrowser(transport!);
      },
      onkill: (exitCode, signal) => {
        if (browserServer)
          browserServer.emit(Events.BrowserServer.Close, exitCode, signal);
      },
    });

    try {
      if (this._webSocketRegexNotPipe) {
        const timeoutError = new TimeoutError(`Timed out while trying to connect to the browser!`);
        const match = await waitForLine(launchedProcess, launchedProcess.stdout, this._webSocketRegexNotPipe, helper.timeUntilDeadline(deadline), timeoutError);
        const innerEndpoint = match[1];
        transport = await WebSocketTransport.connect(innerEndpoint, logger, deadline);
      } else {
        const stdio = launchedProcess.stdio as unknown as [NodeJS.ReadableStream, NodeJS.WritableStream, NodeJS.WritableStream, NodeJS.WritableStream, NodeJS.ReadableStream];
        transport = new PipeTransport(stdio[3], stdio[4], logger);
      }
    } catch (e) {
      // If we can't establish a connection, kill the process and exit.
      helper.killProcess(launchedProcess);
      throw e;
    }
    browserServer = new BrowserServer(options, launchedProcess, gracefullyClose, transport, downloadsPath,
        launchType === 'server' ? this._wrapTransportWithWebSocket(transport, logger, port) : null);
    return browserServer;
  }

  abstract _defaultArgs(options: BrowserArgOptions, launchType: LaunchType, userDataDir: string): string[];
  abstract _connectToTransport(transport: ConnectionTransport, options: BrowserOptions): Promise<BrowserBase>;
  abstract _wrapTransportWithWebSocket(transport: ConnectionTransport, logger: InnerLogger, port: number): WebSocketWrapper;
  abstract _amendEnvironment(env: Env, userDataDir: string, executable: string, browserArguments: string[]): Env;
  abstract _attemptToGracefullyCloseBrowser(transport: ConnectionTransport): void;
}