Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

23.6 KB
Raw Blame
/**
 * Copyright 2017 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.
 */

import fs from 'fs';
import os from 'os';
import path from 'path';

import { ManualPromise } from '@isomorphic/manualPromise';
import { wrapInASCIIBox } from '@utils/ascii';
import { isChromiumChannelName, defaultUserDataDirForChannel } from '@utils/chromiumChannels';
import { RecentLogsCollector } from '@utils/debugLogger';
import { removeFolders } from '@utils/fileUtils';
import { gracefullyCloseSet } from '@utils/processLauncher';
import { debugMode } from '@utils/debug';
import { headersArrayToObject, headersObjectToArray } from '@isomorphic/headers';
import { fetchData } from '../utils';
import { getUserAgent } from '../userAgent';
import { chromiumSwitches } from './chromiumSwitches';
import { shouldProxyLoopback, CRBrowser } from './crBrowser';
import { ConnectionEvents, CRConnection, kBrowserCloseMessageId } from './crConnection';
import { validateBrowserContextOptions } from '../browserContext';
import { BrowserType, kNoXServerRunningError } from '../browserType';
import { helper } from '../helper';
import { registry } from '../registry';
import { WebSocketTransport } from '../transport';
import { CRDevTools } from './crDevTools';
import { Browser } from '../browser';
import { Worker } from '../page';
import { CRExecutionContext, createHandle } from './crExecutionContext';
import { ConsoleMessage } from '../console';
import { stackTraceToLocation } from './crProtocolHelper';

import type { HTTPRequestParams } from '@utils/network';
import type { BrowserOptions, BrowserProcess } from '../browser';
import type { SdkObject } from '../instrumentation';
import type { Progress } from '../progress';
import type { ConnectionTransport, ProtocolRequest } from '../transport';
import type { BrowserContext } from '../browserContext';
import type * as types from '../types';
import type * as channels from '../channels';
import type http from 'http';
import type stream from 'stream';

const ARTIFACTS_FOLDER = path.join(os.tmpdir(), 'playwright-artifacts-');

export class Chromium extends BrowserType {
  private _devtools: CRDevTools | undefined;
  private _bidiChromium: BrowserType;

  constructor(parent: SdkObject, bidiChromium: BrowserType) {
    super(parent, 'chromium');
    this._bidiChromium = bidiChromium;

    if (debugMode() === 'inspector')
      this._devtools = this._createDevTools();
  }

  override launch(progress: Progress, options: types.LaunchOptions, protocolLogger?: types.ProtocolLogger): Promise<Browser> {
    if (options.channel?.startsWith('bidi-'))
      return this._bidiChromium.launch(progress, options, protocolLogger);
    return super.launch(progress, options, protocolLogger);
  }

  override async launchPersistentContext(progress: Progress, userDataDir: string, options: channels.BrowserTypeLaunchPersistentContextOptions & { internalIgnoreHTTPSErrors?: boolean, socksProxyPort?: number }): Promise<BrowserContext> {
    if (options.channel?.startsWith('bidi-'))
      return this._bidiChromium.launchPersistentContext(progress, userDataDir, options);
    return super.launchPersistentContext(progress, userDataDir, options);
  }

  override async connectOverCDP(progress: Progress, params: channels.BrowserTypeConnectOverCDPParams) {
    if (params.transport)
      return this._connectOverCDPImpl(progress, params.transport as any, async () => (params.transport as any).close(), { ...params, isLocal: true });
    return await this._connectOverCDPInternal(progress, params.endpointURL!, params);
  }

  async _connectOverCDPInternal(progress: Progress, endpointURL: string, options: types.LaunchOptions & { headers?: types.HeadersArray, isLocal?: boolean, noDefaults?: boolean, isWebView?: boolean, artifactsDir?: string }, onClose?: () => Promise<void>) {
    let headersMap: { [key: string]: string; } | undefined;
    if (options.headers)
      headersMap = headersArrayToObject(options.headers, false);

    if (!headersMap)
      headersMap = { 'User-Agent': getUserAgent() };
    else if (headersMap && !Object.keys(headersMap).some(key => key.toLowerCase() === 'user-agent'))
      headersMap['User-Agent'] = getUserAgent();

    const channel = isChromiumChannelName(endpointURL) ? endpointURL : undefined;
    if (channel)
      endpointURL = await resolveChannelEndpoint(progress, endpointURL);

    let wsEndpoint: string;
    let chromeTransport: WebSocketTransport;
    try {
      wsEndpoint = await urlToWSEndpoint(progress, endpointURL, headersMap);
      chromeTransport = await WebSocketTransport.connect(progress, wsEndpoint, { headers: headersMap, followRedirects: true, debugLogHeader: 'x-playwright-debug-log' });
    } catch (e) {
      if (channel)
        throw new Error(`Could not connect to ${channel}.\n${remoteDebuggingHint(channel)}`);
      throw e;
    }
    const closeAndWait = async () => await chromeTransport.closeAndWait();
    return this._connectOverCDPImpl(progress, chromeTransport, closeAndWait, options, onClose);
  }

  private async _connectOverCDPImpl(progress: Progress, transport: ConnectionTransport, closeAndWait: () => Promise<void>, options: types.LaunchOptions & { isLocal?: boolean, noDefaults?: boolean, isWebView?: boolean, artifactsDir?: string }, onClose?: () => Promise<void>) {
    let artifactsDir: string;
    const tempDirectories: string[] = [];
    if (options.artifactsDir) {
      artifactsDir = options.artifactsDir;
    } else {
      artifactsDir = await progress.race(fs.promises.mkdtemp(ARTIFACTS_FOLDER));
      tempDirectories.push(artifactsDir);
    }
    const doCleanup = async () => {
      await removeFolders(tempDirectories);
      const cb = onClose;
      onClose = undefined; // Make sure to only call onClose once.
      await cb?.();
    };

    const doClose = async () => {
      await closeAndWait();
      await doCleanup();
    };

    try {
      const browserProcess: BrowserProcess = { close: doClose, kill: doClose };
      const persistent: types.BrowserContextOptions = {
        noDefaultViewport: true,
        ...(options.noDefaults ? { acceptDownloads: 'internal-browser-default' as const } : {}),
      };
      const browserOptions: BrowserOptions = {
        slowMo: options.slowMo,
        name: 'chromium',
        browserType: 'chromium',
        persistent,
        browserProcess,
        protocolLogger: helper.debugProtocolLogger(),
        browserLogsCollector: new RecentLogsCollector(),
        artifactsDir,
        downloadsPath: options.downloadsPath || artifactsDir,
        tracesDir: options.tracesDir || artifactsDir,
        originalLaunchOptions: {},
        noDefaults: options.noDefaults,
        isWebView: options.isWebView,
      };
      validateBrowserContextOptions(persistent, browserOptions);
      const browser = await progress.race(CRBrowser.connect(this.attribution.playwright, transport, browserOptions));
      if (!options.isLocal)
        browser._isBrowserCollocatedWithServer = false;
      browser.on(Browser.Events.Disconnected, doCleanup);
      return browser;
    } catch (error) {
      await progress.race(doClose().catch(() => {}));
      throw error;
    }
  }

  override async connectToWorker(progress: Progress, endpoint: string) {
    const wsEndpoint = await urlToWSEndpoint(progress, endpoint, {});
    const transport = await WebSocketTransport.connect(progress, wsEndpoint);
    try {
      const connection = new CRConnection(this, transport, helper.debugProtocolLogger(), new RecentLogsCollector());
      const session = connection.rootSession;
      const worker = new Worker(this, '', () => transport.closeAndWait());
      session.on('Runtime.executionContextCreated', event => {
        const isDefault = event.context.auxData?.isDefault as boolean | undefined;
        if (isDefault === false) {
          // Node.js sometimes creates internal contexts we are not interested in.
          return;
        }
        worker.workerScriptLoaded();
        worker.createExecutionContext(new CRExecutionContext(session, event.context));
      });
      session.on('Runtime.executionContextDestroyed', () => worker.destroyExecutionContext('Execution context was destroyed'));
      session.on('Runtime.consoleAPICalled', event => {
        if (!worker.existingExecutionContext)
          return;
        const args = event.args.map(o => createHandle(worker.existingExecutionContext!, o));
        const message = new ConsoleMessage(null, worker, event.type, undefined, args, stackTraceToLocation(event.stackTrace), event.timestamp);
        worker.emit(Worker.Events.Console, message);
      });
      connection.on(ConnectionEvents.Disconnected, () => worker.didClose());
      session._sendMayFail('Runtime.enable');
      session._sendMayFail('Runtime.runIfWaitingForDebugger');
      return worker;
    } catch (error) {
      await progress.race(transport.closeAndWait().catch(() => {}));
      throw error;
    }
  }

  private _createDevTools() {
    // TODO: this is totally wrong when using channels.
    const directory = registry.findExecutable('chromium').directory;
    return directory ? new CRDevTools(path.join(directory, 'devtools-preferences.json')) : undefined;
  }

  override async connectToTransport(transport: ConnectionTransport, options: BrowserOptions, browserLogsCollector: RecentLogsCollector): Promise<CRBrowser> {
    try {
      return await CRBrowser.connect(this.attribution.playwright, transport, options, this._devtools);
    } catch (e) {
      const error = profileInUseError(browserLogsCollector.recentLogs());
      if (error)
        throw error;
      throw e;
    }
  }

  override doRewriteStartupLog(logs: string): string {
    if (logs.includes('Missing X server'))
      logs = '\n' + wrapInASCIIBox(kNoXServerRunningError, 1);
    // These error messages are taken from Chromium source code as of July, 2020:
    // https://github.com/chromium/chromium/blob/70565f67e79f79e17663ad1337dc6e63ee207ce9/content/browser/zygote_host/zygote_host_impl_linux.cc
    if (!logs.includes('crbug.com/357670') && !logs.includes('No usable sandbox!') && !logs.includes('crbug.com/638180'))
      return logs;
    return [
      `Chromium sandboxing failed!`,
      `================================`,
      `To avoid the sandboxing issue, do either of the following:`,
      `  - (preferred): Configure your environment to support sandboxing`,
      `  - (alternative): Launch Chromium without sandbox using 'chromiumSandbox: false' option`,
      `================================`,
      ``,
    ].join('\n');
  }

  override amendEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
    return env;
  }

  override attemptToGracefullyCloseBrowser(transport: ConnectionTransport): void {
    // Note that it's fine to reuse the transport, since our connection ignores kBrowserCloseMessageId.
    const message: ProtocolRequest = { method: 'Browser.close', id: kBrowserCloseMessageId, params: {} };
    transport.send(message);
  }

  override async launchWithSeleniumHub(progress: Progress, hubUrl: string, options: types.LaunchOptions): Promise<CRBrowser> {
    if (!hubUrl.endsWith('/'))
      hubUrl = hubUrl + '/';

    const args = this._innerDefaultArgs(options);
    args.push('--remote-debugging-port=0');
    const isEdge = options.channel && options.channel.startsWith('msedge');
    let desiredCapabilities = {
      'browserName': isEdge ? 'MicrosoftEdge' : 'chrome',
      [isEdge ? 'ms:edgeOptions' : 'goog:chromeOptions']: { args }
    };

    if (process.env.SELENIUM_REMOTE_CAPABILITIES) {
      const remoteCapabilities = parseSeleniumRemoteParams({ name: 'capabilities', value: process.env.SELENIUM_REMOTE_CAPABILITIES }, progress);
      if (remoteCapabilities)
        desiredCapabilities = { ...desiredCapabilities, ...remoteCapabilities };
    }

    let headers: { [key: string]: string } = {};
    if (process.env.SELENIUM_REMOTE_HEADERS) {
      const remoteHeaders = parseSeleniumRemoteParams({ name: 'headers', value: process.env.SELENIUM_REMOTE_HEADERS }, progress);
      if (remoteHeaders)
        headers = remoteHeaders;
    }

    progress.log(`<selenium> connecting to ${hubUrl}`);
    const response = await fetchData(progress, {
      url: hubUrl + 'session',
      method: 'POST',
      headers: {
        'Content-Type': 'application/json; charset=utf-8',
        ...headers,
      },
      data: JSON.stringify({
        capabilities: { alwaysMatch: desiredCapabilities }
      }),
    }, seleniumErrorHandler);
    const value = JSON.parse(response).value;
    const sessionId = value.sessionId;
    progress.log(`<selenium> connected to sessionId=${sessionId}`);

    const disconnectFromSelenium = async () => {
      progress.log(`<selenium> disconnecting from sessionId=${sessionId}`);
      // Do not pass "progress" to disconnect even after the progress has aborted.
      await fetchData(undefined, {
        url: hubUrl + 'session/' + sessionId,
        method: 'DELETE',
        headers,
      }).catch(error => progress.log(`<error disconnecting from selenium>: ${error}`));
      progress.log(`<selenium> disconnected from sessionId=${sessionId}`);
      gracefullyCloseSet.delete(disconnectFromSelenium);
    };
    gracefullyCloseSet.add(disconnectFromSelenium);

    try {
      const capabilities = value.capabilities;
      let endpointURL: URL;

      if (capabilities['se:cdp']) {
        // Selenium 4 - use built-in CDP websocket proxy.
        progress.log(`<selenium> using selenium v4`);
        const endpointURLString = addProtocol(capabilities['se:cdp']);
        endpointURL = new URL(endpointURLString);
        if (endpointURL.hostname === 'localhost' || endpointURL.hostname === '127.0.0.1')
          endpointURL.hostname = new URL(hubUrl).hostname;
        progress.log(`<selenium> retrieved endpoint ${endpointURL.toString()} for sessionId=${sessionId}`);
      } else {
        // Selenium 3 - resolve target node IP to use instead of localhost ws url.
        progress.log(`<selenium> using selenium v3`);
        const maybeChromeOptions = capabilities['goog:chromeOptions'];
        const chromeOptions = maybeChromeOptions && typeof maybeChromeOptions === 'object' ? maybeChromeOptions : undefined;
        const debuggerAddress = chromeOptions && typeof chromeOptions.debuggerAddress === 'string' ? chromeOptions.debuggerAddress : undefined;
        const chromeOptionsURL = typeof maybeChromeOptions === 'string' ? maybeChromeOptions : undefined;
        // TODO(dgozman): figure out if we can make ChromeDriver to return 127.0.0.1 instead of localhost.
        const endpointURLString = addProtocol(debuggerAddress || chromeOptionsURL).replace('localhost', '127.0.0.1');
        progress.log(`<selenium> retrieved endpoint ${endpointURLString} for sessionId=${sessionId}`);
        endpointURL = new URL(endpointURLString);
        if (endpointURL.hostname === 'localhost' || endpointURL.hostname === '127.0.0.1') {
          const sessionInfoUrl = new URL(hubUrl).origin + '/grid/api/testsession?session=' + sessionId;
          try {
            const sessionResponse = await fetchData(progress, {
              url: sessionInfoUrl,
              method: 'GET',
              headers,
            }, seleniumErrorHandler);
            const proxyId = JSON.parse(sessionResponse).proxyId;
            endpointURL.hostname = new URL(proxyId).hostname;
            progress.log(`<selenium> resolved endpoint ip ${endpointURL.toString()} for sessionId=${sessionId}`);
          } catch (e) {
            progress.log(`<selenium> unable to resolve endpoint ip for sessionId=${sessionId}, running in standalone?`);
          }
        }
      }

      return await this._connectOverCDPInternal(progress, endpointURL.toString(), {
        ...options,
        headers: headersObjectToArray(headers),
      }, disconnectFromSelenium);
    } catch (e) {
      await progress.race(disconnectFromSelenium());
      throw e;
    }
  }

  override async defaultArgs(options: types.LaunchOptions, isPersistent: boolean, userDataDir: string) {
    const chromeArguments = this._innerDefaultArgs(options);
    chromeArguments.push(`--user-data-dir=${userDataDir}`);
    chromeArguments.push('--remote-debugging-pipe');
    if (isPersistent)
      chromeArguments.push('about:blank');
    else
      chromeArguments.push('--no-startup-window');
    return chromeArguments;
  }

  private _innerDefaultArgs(options: types.LaunchOptions): string[] {
    const { args = [] } = options;
    const userDataDirArg = args.find(arg => arg.startsWith('--user-data-dir'));
    if (userDataDirArg)
      throw this._createUserDataDirArgMisuseError('--user-data-dir');
    if (args.find(arg => arg.startsWith('--remote-debugging-pipe')))
      throw new Error('Playwright manages remote debugging connection itself.');
    if (args.find(arg => !arg.startsWith('-')))
      throw new Error('Arguments can not specify page to be opened');
    const chromeArguments = [...chromiumSwitches()];

    // See https://issues.chromium.org/issues/40277080
    chromeArguments.push('--enable-unsafe-swiftshader');

    if (options.headless) {
      chromeArguments.push('--headless');

      chromeArguments.push(
          '--hide-scrollbars',
          '--mute-audio',
          '--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4',
      );
    }
    if (options.chromiumSandbox !== true)
      chromeArguments.push('--no-sandbox');
    const proxy = options.proxyOverride || options.proxy;
    if (proxy) {
      const proxyURL = new URL(proxy.server);
      const isSocks = proxyURL.protocol === 'socks5:';
      // https://www.chromium.org/developers/design-documents/network-settings
      if (isSocks && !options.socksProxyPort) {
        // https://www.chromium.org/developers/design-documents/network-stack/socks-proxy
        chromeArguments.push(`--host-resolver-rules="MAP * ~NOTFOUND , EXCLUDE ${proxyURL.hostname}"`);
      }
      chromeArguments.push(`--proxy-server=${proxy.server}`);
      const proxyBypassRules = [];
      // https://source.chromium.org/chromium/chromium/src/+/master:net/docs/proxy.md;l=548;drc=71698e610121078e0d1a811054dcf9fd89b49578
      if (proxy.bypass)
        proxyBypassRules.push(...proxy.bypass.split(',').map(t => t.trim()).map(t => t.startsWith('.') ? '*' + t : t));
      if (options.socksProxyPort || shouldProxyLoopback(proxy.bypass))
        proxyBypassRules.push('<-loopback>');
      if (proxyBypassRules.length > 0)
        chromeArguments.push(`--proxy-bypass-list=${proxyBypassRules.join(';')}`);
    }
    chromeArguments.push(...args);
    return chromeArguments;
  }

  override async waitForReadyState(options: types.LaunchOptions, browserLogsCollector: RecentLogsCollector): Promise<{ wsEndpoint?: string }> {
    return waitForReadyState(options, browserLogsCollector);
  }

  override getExecutableName(options: types.LaunchOptions): string {
    if (options.channel && registry.isChromiumAlias(options.channel))
      return 'chromium';
    if (options.channel)
      return options.channel;
    return options.headless ? 'chromium-headless-shell' : 'chromium';
  }
}

export function profileInUseError(logs: string[]): Error | undefined {
  const markers = [
    'Failed to create a ProcessSingleton for your profile directory.',
    'Opening in existing browser session.',
  ];
  for (const log of logs) {
    const marker = markers.find(m => log.includes(m));
    if (marker) {
      return new Error(
          `${marker} ` +
          'This usually means that the profile is already in use by another instance of Chromium.'
      );
    }
  }
}

export async function waitForReadyState(options: types.LaunchOptions, browserLogsCollector: RecentLogsCollector): Promise<{ wsEndpoint?: string }> {
  if (!options.args?.some(a => a.startsWith('--remote-debugging-port')))
    return {};

  const result = new ManualPromise<{ wsEndpoint?: string }>();
  browserLogsCollector.onMessage(message => {
    const error = profileInUseError([message]);
    if (error)
      result.reject(error);
    const match = message.match(/DevTools listening on (.*)/);
    if (match)
      result.resolve({ wsEndpoint: match[1] });
  });
  return result;
}

async function urlToWSEndpoint(progress: Progress, endpointURL: string, headers: { [key: string]: string; }) {
  if (endpointURL.startsWith('ws'))
    return endpointURL;
  progress.log(`<ws preparing> retrieving websocket url from ${endpointURL}`);
  const url = new URL(endpointURL);
  if (!url.pathname.endsWith('/'))
    url.pathname += '/';
  url.pathname += 'json/version/';
  const httpURL = url.toString();

  const json = await fetchData(progress, {
    url: httpURL,
    headers,
  }, async (_, resp) => new Error(`Unexpected status ${resp.statusCode} when connecting to ${httpURL}.\n` +
    `This does not look like a DevTools server, try connecting via ws://.`)
  );
  return JSON.parse(json).webSocketDebuggerUrl;
}

async function resolveChannelEndpoint(progress: Progress, channel: string): Promise<string> {
  const userDataDir = defaultUserDataDirForChannel(channel);
  if (!userDataDir)
    throw new Error(`Connecting to ${channel} by channel name is not supported on ${process.platform}.`);

  const devToolsActivePortPath = path.join(userDataDir, 'DevToolsActivePort');
  progress.log(`<ws preparing> reading ${devToolsActivePortPath}`);

  const contents = await progress.race(fs.promises.readFile(devToolsActivePortPath, 'utf-8').catch(() => undefined));
  if (!contents) {
    throw new Error(
        `Could not connect to ${channel}: DevToolsActivePort file not found at ${devToolsActivePortPath}.\n` +
        remoteDebuggingHint(channel));
  }

  const port = parseInt(contents.trim(), 10);
  if (isNaN(port))
    throw new Error(`Could not connect to ${channel}: invalid DevToolsActivePort file at ${devToolsActivePortPath}.`);

  const endpoint = `ws://localhost:${port}/devtools/browser`;
  progress.log(`<ws preparing> resolved channel "${channel}" to ${endpoint}`);
  return endpoint;
}

async function seleniumErrorHandler(params: HTTPRequestParams, response: http.IncomingMessage) {
  const body = await streamToString(response);
  let message = body;
  try {
    const json = JSON.parse(body);
    message = json.value.localizedMessage || json.value.message;
  } catch (e) {
  }
  return new Error(`Error connecting to Selenium at ${params.url}: ${message}`);
}

function addProtocol(url: string) {
  if (!['ws://', 'wss://', 'http://', 'https://'].some(protocol => url.startsWith(protocol)))
    return 'http://' + url;
  return url;
}

function streamToString(stream: stream.Readable): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on('data', chunk => chunks.push(Buffer.from(chunk)));
    stream.on('error', reject);
    stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
  });
}

function parseSeleniumRemoteParams(env: {name: string, value: string}, progress: Progress) {
  try {
    const parsed = JSON.parse(env.value);
    progress.log(`<selenium> using additional ${env.name} "${env.value}"`);
    return parsed;
  } catch (e) {
    progress.log(`<selenium> ignoring additional ${env.name} "${env.value}": ${e}`);
  }
}

function remoteDebuggingHint(channel: string): string {
  return `Make sure ${channel} is running with remote debugging enabled. Navigate to

        chrome://inspect/#remote-debugging

and check "Allow remote debugging for this browser instance".
`;
}