Skip to content

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

17.1 KB
Raw Blame
/**
 * 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 { execSync, spawn } from 'child_process';

import crypto from 'crypto';
import os from 'os';
import path from 'path';

import { isKnownChannel, listChannelSessions } from './channelSessions';
import { JsonOutput, TextOutput } from './output';
import { clientKey, createClientInfo, explicitSessionName, Registry, resolveSessionName } from './registry';
import { Session } from './session';
import { libPath } from '../../package';
import { serverRegistry } from '../../serverRegistry';
import { minimist } from './minimist';
import { processExit } from '../../bootstrap';

import type { ListData, ListedBrowser, Output } from './output';
import type { ClientInfo, SessionFile } from './registry';
import type { MinimistArgs } from './minimist';

type GlobalOptions = {
  help?: boolean;
  json?: boolean;
  raw?: boolean;
  session?: string;
  version?: boolean;
};

type AttachOptions = {
  config?: string;
  cdp?: string;
  endpoint?: string;
  extension?: boolean | string;
};

type OpenOptions = {
  browser?: string;
  config?: string;
  device?: string;
  headed?: boolean;
  mobile?: boolean;
  persistent?: boolean;
  profile?: string;
};

const globalOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions))[] = [
  'json',
  'raw',
  'session',
];

const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { all?: boolean, g?: boolean }))[] = [
  'all',
  'g',
  'help',
  'json',
  'raw',
  'version',
];

export async function program(options?: { embedderVersion?: string}) {
  const clientInfo = createClientInfo();
  const help = require(libPath('tools', 'cli-client', 'help.json'));

  const argv = process.argv.slice(2);
  const boolean = [...help.booleanOptions, ...booleanOptions];
  const args: MinimistArgs = minimist(argv, { boolean, string: ['_'] });
  // Normalize -s alias to --session
  if (args.s) {
    args.session = args.s;
    delete args.s;
  }
  // Normalize -g alias to --global
  if (args.g) {
    args.global = true;
    delete args.g;
  }

  const output: Output = args.json ? new JsonOutput() : new TextOutput();
  const commandName = args._?.[0];

  if (args.version || args.v) {
    output.version(options?.embedderVersion ?? clientInfo.version);
    // eslint-disable-next-line no-restricted-syntax
    processExit(0);
  }

  const command = commandName && help.commands[commandName];
  if (args.help || args.h || !commandName) {
    if (command) {
      output.help(command.help);
    } else {
      const lines = ['playwright-cli - run playwright mcp commands from terminal'];
      if (process.env.CLAUDECODE || process.env.COPILOT_CLI)
        lines.push(`Agent skill: ${path.relative(process.cwd(), libPath('tools', 'skills', 'playwright-cli', 'SKILL.md'))}`);
      lines.push(help.global);
      output.help(lines.join('\n\n'));
    }
    // eslint-disable-next-line no-restricted-syntax
    processExit(0);
  }

  if (!command)
    output.errorUnknownCommand(commandName, help.global);

  validateFlags(args, command, output);
  validateArgs(args, command, output);

  const registry = await Registry.load();
  const sessionName = resolveSessionName(args.session as string);

  switch (commandName) {
    case 'list': {
      const data = await collectList(registry, clientInfo, !!args.all);
      output.list(data);
      return;
    }
    case 'close-all': {
      const entries = registry.entries(clientInfo);
      const closed: string[] = [];
      for (const entry of entries) {
        await new Session(entry).stop();
        closed.push(entry.config.name);
      }
      output.closeAll(closed);
      return;
    }
    case 'delete-data': {
      const entry = registry.entry(clientInfo, sessionName);
      if (!entry) {
        output.deleteData(sessionName, { existed: false, deletedUserDataDir: false });
        return;
      }
      const result = await new Session(entry).deleteData();
      output.deleteData(sessionName, result);
      return;
    }
    case 'kill-all': {
      const pids = await killAllDaemons();
      output.killAll(pids);
      return;
    }
    case 'open': {
      const { pid } = await startSession(sessionName, registry, clientInfo, args, 'open');
      const newEntry = await registry.loadEntry(clientInfo, sessionName);
      const params = args._.slice(1);
      const toolText = await runInSessionOrStop(newEntry, clientInfo, { _: ['goto', ...(params.length ? params : ['about:blank'])] }, output);
      output.open(sessionName, pid, toolText);
      return;
    }
    case 'attach': {
      const attachTarget = args._[1] as string | undefined;
      const targetCount = (attachTarget ? 1 : 0) + (args.cdp ? 1 : 0) + (args.endpoint ? 1 : 0) + (args.extension ? 1 : 0);
      if (targetCount > 1)
        output.errorAttachConflict();
      if (attachTarget)
        args.endpoint = attachTarget;
      const extensionChannel = typeof args.extension === 'string' ? args.extension : undefined;
      if (extensionChannel) {
        args.browser = extensionChannel;
        args.extension = true;
      }

      const cdpChannel = typeof args.cdp === 'string' && isKnownChannel(args.cdp) ? args.cdp : undefined;
      const targetName = attachTarget ?? cdpChannel ?? extensionChannel ?? args.endpoint as string ?? args.cdp as string;
      if (!targetName)
        output.errorAttachNoTarget();
      const attachSessionName = explicitSessionName(args.session as string) ?? attachTarget ?? cdpChannel ?? extensionChannel ?? sessionName;
      args.session = attachSessionName;
      const { pid } = await startSession(attachSessionName, registry, clientInfo, args, 'attach');
      const newEntry = await registry.loadEntry(clientInfo, attachSessionName);
      const toolText = await runInSessionOrStop(newEntry, clientInfo, { _: ['snapshot'], filename: '<auto>' }, output);
      output.attach(attachSessionName, pid, targetName, toolText);
      return;
    }
    case 'close': {
      const closeEntry = registry.entry(clientInfo, sessionName);
      const { wasOpen } = closeEntry ? await new Session(closeEntry).stop() : { wasOpen: false };
      output.close(sessionName, wasOpen);
      return;
    }
    case 'detach': {
      const detachEntry = registry.entry(clientInfo, sessionName);
      if (detachEntry && !detachEntry.config.attached)
        output.errorDetachNotAttached(sessionName);
      const { wasOpen } = detachEntry ? await new Session(detachEntry).stop() : { wasOpen: false };
      output.detach(sessionName, wasOpen);
      return;
    }
    case 'install':
      if (args.global && !args.skills)
        output.errorInstallGlobalRequiresSkills();
      await runInitWorkspace(args, output);
      output.installed();
      return;
    case 'install-browser':
      await installBrowser();
      output.installed();
      return;
    case 'show': {
      const daemonScript = libPath('entry', 'dashboardApp.js');
      const daemonArgs = [
        daemonScript,
        `--workspaceDir=${clientInfo.workspaceDir ?? ''}`,
      ];
      // Only pass --sessionName when the user explicitly requested a session
      // (via -s/--session or PLAYWRIGHT_CLI_SESSION). Bare `playwright cli show`
      // opens the dashboard generically, with no specific session to reveal,
      // so the daemon should ack as soon as it's ready rather than waiting for
      // a reveal that was never asked for.
      const explicit = explicitSessionName(args.session as string);
      if (explicit)
        daemonArgs.push(`--sessionName=${explicit}`);
      if (args.port !== undefined)
        daemonArgs.push(`--port=${args.port}`);
      if (args.host !== undefined)
        daemonArgs.push(`--host=${args.host as string}`);
      if (args.kill) {
        daemonArgs.push(`--kill`);
        const child = spawn(process.execPath, daemonArgs, { stdio: 'ignore' });
        await new Promise<void>(resolve => child.on('exit', () => resolve()));
        return;
      }
      if (args.annotate) {
        const entry = registry.entry(clientInfo, sessionName);
        if (!entry)
          output.errorBrowserNotOpenForTool(sessionName);
        args.raw = true;
        const text = await runInSession(entry, clientInfo, args, output);
        output.toolResult(text);
        return;
      }
      const foreground = args.port !== undefined;
      const child = spawn(process.execPath, daemonArgs, {
        detached: !foreground,
        stdio: foreground ? 'inherit' : ['pipe', 'pipe', 'ignore'],
        windowsHide: true,
      });
      if (foreground) {
        await new Promise<void>(resolve => child.on('exit', () => resolve()));
        return;
      }
      const timer = setTimeout(() => child.stdin!.destroy(), 60_000);
      child.unref();
      let daemonPid: number;
      try {
        await new Promise<void>((resolve, reject) => {
          let outLog = '';
          child.stdout!.on('data', data => {
            outLog += data.toString();
            const match = outLog.match(/Dashboard is running pid=(\d+)/);
            if (match) {
              daemonPid = Number(match[1]);
              resolve();
            }
          });
          child.once('exit', (code, signal) => reject(new Error(`Dashboard daemon exited (code=${code}, signal=${signal}) before signaling READY${outLog ? '\n' + outLog : ''}`)));
        });
      } finally {
        clearTimeout(timer);
        child.removeAllListeners('exit');
        child.stdin!.destroy();
        child.stdout!.destroy();
      }
      output.show(sessionName, daemonPid!);
      return;
    }
    default: {
      const entry = registry.entry(clientInfo, sessionName);
      if (!entry)
        output.errorBrowserNotOpenForTool(sessionName);
      if (command.raw)
        args.raw = true;
      const text = await runInSession(entry, clientInfo, args, output);
      output.toolResult(text);
    }
  }
}

async function startSession(sessionName: string, registry: Registry, clientInfo: ClientInfo, args: MinimistArgs, mode: 'open' | 'attach') {
  const entry = registry.entry(clientInfo, sessionName);
  if (entry)
    await new Session(entry).stop();
  return await Session.startDaemon(clientInfo, args, mode);
}

async function runInSession(entry: SessionFile, clientInfo: ClientInfo, args: MinimistArgs, output: Output): Promise<string> {
  const raw = !!args.raw;
  for (const globalOption of globalOptions)
    delete args[globalOption];
  const session = new Session(entry);
  const result = await session.run(clientInfo, args, { raw, json: output.json });
  if (result.isError)
    process.exitCode = 1;
  return result.text;
}

// Used by `open` / `attach` after `startSession`: if the implicit goto/snapshot
// fails post-spawn (e.g. tool runtime error), stop the freshly-spawned daemon
// so we don't strand a detached browser. Pre-spawn arg validation lives in
// `validateArgs`; this is a defense-in-depth backstop for runtime errors.
async function runInSessionOrStop(entry: SessionFile, clientInfo: ClientInfo, args: MinimistArgs, output: Output): Promise<string> {
  try {
    return await runInSession(entry, clientInfo, args, output);
  } catch (e) {
    await new Session(entry).stop().catch(() => {});
    throw e;
  }
}

async function runInitWorkspace(args: MinimistArgs, output: Output) {
  const cliPath = libPath('entry', 'cliDaemon.js');
  const daemonArgs: string[] = [
    cliPath,
    '--init-workspace',
    ...(args.skills ? [args.global ? '--init-skills-global' : '--init-skills', String(args.skills)] : []),
  ];
  await new Promise<void>((resolve, reject) => {
    const child = spawn(process.execPath, daemonArgs, {
      stdio: output.installStdio(),
      cwd: process.cwd(),
    });
    child.on('close', code => {
      if (code === 0)
        resolve();
      else
        reject(new Error(`Workspace initialization failed with exit code ${code}`));
    });
  });
}

async function installBrowser() {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  const { libCli } = require('../../coreBundle.js') as typeof import('../../coreBundle');
  const { program } = require('../../utilsBundle.js') as typeof import('../../utilsBundle');
  if (!program.version())
    libCli.decorateProgram(program);
  program.parse(argv);
}

const daemonProcessPatterns = ['run-mcp-server', 'run-cli-server', 'cli-daemon', 'cliDaemon.js', 'dashboardApp.js'];

async function killAllDaemons(): Promise<number[]> {
  const platform = os.platform();
  const pidFilterEnv = process.env.PWTEST_KILL_ALL_PID_FILTER_FOR_TEST;
  const pidFilter = pidFilterEnv ? new Set(pidFilterEnv.split(',').map(p => parseInt(p, 10)).filter(n => !isNaN(n))) : undefined;
  const killed: number[] = [];

  try {
    if (platform === 'win32') {
      const clauses = [`(${daemonProcessPatterns.map(p => `$_.CommandLine -like '*${p}*'`).join(' -or ')})`];
      if (pidFilter)
        clauses.push(`(${[...pidFilter].map(p => `$_.ProcessId -eq ${p}`).join(' -or ')})`);
      const whereClause = clauses.join(' -and ');
      const result = execSync(
          `powershell -NoProfile -NonInteractive -Command `
          + `"Get-CimInstance Win32_Process `
          + `| Where-Object { ${whereClause} } `
          + `| ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue; $_.ProcessId }"`,
          { encoding: 'utf-8' }
      );
      const pids = result.split('\n')
          .map(line => line.trim())
          .filter(line => /^\d+$/.test(line));
      for (const pid of pids)
        killed.push(parseInt(pid, 10));
    } else {
      const result = execSync('ps auxww', { encoding: 'utf-8' });
      const lines = result.split('\n');
      for (const line of lines) {
        if (daemonProcessPatterns.some(p => line.includes(p))) {
          const parts = line.trim().split(/\s+/);
          const pid = parts[1];
          if (pid && /^\d+$/.test(pid)) {
            const numericPid = parseInt(pid, 10);
            if (pidFilter && !pidFilter.has(numericPid))
              continue;
            try {
              process.kill(numericPid, 'SIGKILL');
              killed.push(numericPid);
            } catch {
              // Process may have already exited
            }
          }
        }
      }
    }
  } catch (e) {
    // Silently handle errors - no processes to kill is fine
  }
  return killed;
}

async function collectList(registry: Registry, clientInfo: ClientInfo, all: boolean): Promise<ListData> {
  const browsers: ListedBrowser[] = [];
  const entries = registry.entryMap();

  // List early to GC.
  const serverEntries = await serverRegistry.list();
  const key = clientKey(clientInfo);
  for (const [workspaceKey, list] of entries) {
    if (!all && workspaceKey !== key)
      continue;
    for (const entry of list) {
      const session = new Session(entry);
      const canConnect = await session.canConnect();
      if (!canConnect) {
        await session.deleteSessionConfig();
        continue;
      }
      const config = session.config;
      const channel = config.browser?.launchOptions.channel ?? config.browser?.browserName;
      browsers.push({
        name: session.name,
        workspace: workspaceKey,
        status: canConnect ? 'open' : 'closed',
        browserType: channel,
        userDataDir: config.browser?.userDataDir ?? null,
        headed: config.browser ? !config.browser.launchOptions.headless : undefined,
        persistent: !!config.cli.persistent,
        attached: !!config.attached,
        compatible: session.isCompatible(clientInfo),
        version: config.version,
      });
    }
  }

  if (!all)
    return { all, browsers };

  const servers = [...serverEntries.values()].flat();
  return { all, browsers, servers, channelSessions: await listChannelSessions() };
}

function validateFlags(args: MinimistArgs, command: { flags: Record<string, 'boolean' | 'string'>, help: string }, output: Output) {
  const unknownFlags: string[] = [];
  for (const key of Object.keys(args)) {
    if (key === '_')
      continue;
    if ((globalOptions as readonly string[]).includes(key))
      continue;
    if (key in command.flags)
      continue;
    // Negated flags like '--no-shell' are parsed as { shell: false }.
    if (args[key] === false && `no-${key}` in command.flags)
      continue;
    unknownFlags.push(key);
  }
  if (unknownFlags.length)
    output.errorUnknownOption(unknownFlags, command.help);
}

function validateArgs(args: MinimistArgs, command: { args: string[], variadicArg?: boolean, help: string }, output: Output) {
  const positional = args._.slice(1);
  if (positional.length > command.args.length && !command.variadicArg)
    output.errorTooManyArguments(command.args.length, positional.length, command.help);
}

export function calculateSha1(buffer: Buffer | string): string {
  const hash = crypto.createHash('sha1');
  hash.update(buffer);
  return hash.digest('hex');
}