Skip to content

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

16.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 fs from 'fs';
import path from 'path';
import net from 'net';
import http from 'http';

import { HttpServer } from '@utils/httpServer';
import { makeSocketPath } from '@utils/fileUtils';
import { gracefullyProcessExitDoNotHang } from '@utils/processLauncher';
import { ManualPromise } from '@isomorphic/manualPromise';
import { libPath } from '../../package';
import { playwright } from '../../inprocess';
import { findChromiumChannelBestEffort, registryDirectory } from '../../server/registry/index';
import { minimist } from '../cli-client/minimist';
import { DashboardConnection } from './dashboardController';
import { RegistrySessionProvider } from './registrySessionProvider';
import { IdentitySessionProvider } from './identitySessionProvider';

import type * as api from '../../..';
import type { AnnotateResult } from './dashboardController';
import type { SessionProvider } from './sessionProvider';

// HMR: build-time flag — `true` in watch builds, `false` in release. esbuild
// replaces the identifier via `define`, so the static branch pays zero runtime
// cost and the dev-server code (incl. `import('vite')`) is DCE'd in release.
declare const __PW_HMR__: boolean;

type DashboardServer = {
  url: string;
  reveal: (options: DashboardOptions) => void;
  triggerAnnotate: (signal: AbortSignal) => Promise<AnnotateResult>;
  close: () => Promise<void>;
};

async function startDashboardServer(provider: SessionProvider, options: DashboardOptions): Promise<DashboardServer> {
  const dashboardDir = libPath('vite', 'dashboard');
  const httpServer = new HttpServer(dashboardDir);

  const connections = new Set<DashboardConnection>();
  let connectionLanded = new ManualPromise<void>();

  httpServer.createWebSocket(() => {
    let connection: DashboardConnection;
    // eslint-disable-next-line prefer-const
    connection = new DashboardConnection(provider, () => {
      connections.delete(connection);
      if (connections.size === 0)
        connectionLanded = new ManualPromise<void>();
    }, () => {
      connectionLanded.resolve();
    });
    connections.add(connection);
    return connection;
  });

  const wsGuid = httpServer.wsGuid()!;
  httpServer.routePath('/', (_, response) => {
    response.statusCode = 302;
    response.setHeader('Location', `/index.html?ws=${wsGuid}`);
    response.end();
    return true;
  });

  // HMR: watch builds serve the dashboard through an embedded Vite dev server
  // so edits to packages/dashboard/src/* reload live. Release builds always
  // take the static branch (the dev-server arm is DCE'd). Set
  // PW_HMR_STATIC=1 during watch to exercise the bundled output.
  if (__PW_HMR__ && process.env.PW_HMR_STATIC !== '1')
    await attachDashboardDevServer(httpServer);
  else
    attachDashboardStaticServer(httpServer, dashboardDir);
  await httpServer.start({ port: options.port, host: options.host });

  const reveal = (next: DashboardOptions): void => {
    void connectionLanded.then(() => {
      for (const c of connections) {
        if (next.pageId)
          c.revealPage(next.pageId);
        else if (next.sessionName)
          c.revealSession(next.sessionName, next.workspaceDir);
      }
    });
  };

  const triggerAnnotate = async (cancellation: AbortSignal): Promise<AnnotateResult> => {
    await connectionLanded;
    if (cancellation.aborted || connections.size === 0)
      return { type: 'cancelled' };
    // Multiple dashboard connections is theoretical today (one UI per daemon).
    // If two ever land, the first to submit wins but the losers stay in
    // annotation mode until their UI reloads — revisit if that becomes a real
    // scenario.
    return await Promise.race([...connections].map(c => c.emitAnnotate({ signal: cancellation })));
  };

  const close = async () => {
    for (const c of connections)
      c.close?.();
    await httpServer.stop();
  };
  return { url: httpServer.urlPrefix('human-readable'), reveal, triggerAnnotate, close };
}

function attachDashboardStaticServer(httpServer: HttpServer, dashboardDir: string) {
  httpServer.routePrefix('/', (request: http.IncomingMessage, response: http.ServerResponse) => {
    const pathname = new URL(request.url!, `http://${request.headers.host}`).pathname;
    const filePath = pathname === '/' ? 'index.html' : pathname.substring(1);
    const resolved = path.join(dashboardDir, filePath);
    return httpServer.serveFile(request, response, resolved);
  });
}

// HMR begin: dev-mode branch — wires a Vite dev server into HttpServer.
async function attachDashboardDevServer(httpServer: HttpServer) {
  const dashboardRoot = path.resolve(__dirname, '..', '..', 'dashboard');
  const devServer = await httpServer.createViteDevServer({ root: dashboardRoot });
  httpServer.routePrefix('/', (request: http.IncomingMessage, response: http.ServerResponse) => {
    devServer.middlewares(request, response, HttpServer.notFoundFallback(response));
    return true;
  });
}
// HMR end

type AppState = { page?: api.Page; server: DashboardServer };

async function launchApp(appName: string, options?: { onClose?: () => void }) {
  const channel = findChromiumChannelBestEffort('javascript');
  const context = await playwright.chromium.launchPersistentContext('', {
    ignoreDefaultArgs: ['--enable-automation'],
    channel,
    headless: !!process.env.PWTEST_DASHBOARD_APP_BIND_TITLE,
    args: [
      '--app=data:text/html,',
      '--test-type=',
      `--window-size=1280,800`,
      `--window-position=100,100`,
    ],
    viewport: null,
  });
  if (process.env.PWTEST_DASHBOARD_APP_BIND_TITLE)
    await context.browser()?.bind(process.env.PWTEST_DASHBOARD_APP_BIND_TITLE, { workspaceDir: process.cwd() });

  const [page] = context.pages();
  // Chromium on macOS opens a new tab when clicking on the dock icon.
  // See https://github.com/microsoft/playwright/issues/9434
  if (process.platform === 'darwin') {
    context.on('page', async newPage => {
      if (newPage.mainFrame().url() === 'chrome://new-tab-page/') {
        await page.bringToFront();
        await newPage.close();
      }
    });
  }

  page.on('close', () => options?.onClose?.());

  const image = await fs.promises.readFile(libPath('tools', 'dashboard', 'appIcon.png'));
  // This is local Playwright, so I can access private methods.
  // eslint-disable-next-line no-restricted-syntax -- it is not essential, can regress.
  await (page as any)._setDockTile?.(image);
  await syncLocalStorageWithSettings(page, appName);
  return { context, page };
}

export async function syncLocalStorageWithSettings(page: api.Page, appName: string) {
  const settingsFile = process.env.PWTEST_DASHBOARD_SETTINGS_FILE ?? path.join(registryDirectory, '.settings', `${appName}.json`);

  await page.exposeBinding('_saveSerializedSettings', (_, settings) => {
    fs.mkdirSync(path.dirname(settingsFile), { recursive: true });
    fs.writeFileSync(settingsFile, settings);
  });

  const settings = await fs.promises.readFile(settingsFile, 'utf-8').catch(() => ('{}'));
  await page.addInitScript(
      `(${String((settings: any) => {
        // iframes w/ snapshots, etc.
        if (location && location.protocol === 'data:')
          return;
        if (window.top !== window)
          return;
        Object.entries(settings).map(([k, v]) => localStorage[k] = v);
        // eslint-disable-next-line no-restricted-syntax
        (window as any).saveSettings = () => {
          // eslint-disable-next-line no-restricted-syntax
          (window as any)._saveSerializedSettings(JSON.stringify({ ...localStorage }));
        };
      })})(${settings});
  `);
}

function dashboardSocketPath() {
  return makeSocketPath('dashboard', 'app');
}

type DashboardOptions = {
  sessionName?: string;
  workspaceDir?: string;
  pageId?: string;
  kill?: boolean;
  annotate?: boolean;
  port?: number;
  host?: string;
};

function parseOpenArgs(): DashboardOptions {
  const args = minimist(process.argv.slice(2), { string: ['sessionName', 'workspaceDir', 'host', 'pageId'], boolean: ['annotate', 'kill'] });
  const portStr = args.port as string | undefined;
  return {
    sessionName: args.sessionName as string | undefined,
    workspaceDir: args.workspaceDir as string | undefined,
    pageId: args.pageId as string | undefined,
    port: portStr !== undefined ? Number(portStr) : undefined,
    host: args.host as string | undefined,
    annotate: !!args.annotate,
    kill: !!args.kill,
  };
}

type AcquireResult =
  | { role: 'winner', server: net.Server }
  | { role: 'loser', daemonPid: number };

async function acquireSingleton(options: DashboardOptions, onConnection: (socket: net.Socket) => void): Promise<AcquireResult> {
  const socketPath = dashboardSocketPath();
  if (process.platform !== 'win32')
    await fs.promises.mkdir(path.dirname(socketPath), { recursive: true });

  return await new Promise((resolve, reject) => {
    // Attach the connection handler at creation — before listen() — so a loser
    // that connects the instant we win the socket is never dropped.
    const server = net.createServer(onConnection);
    server.listen(socketPath, () => resolve({ role: 'winner', server }));
    server.on('error', (err: NodeJS.ErrnoException) => {
      if (err.code !== 'EADDRINUSE' && err.code !== 'EEXIST')
        return reject(err);
      let ackBuffer = '';
      const client = net.connect(socketPath, () => {
        client.write(JSON.stringify(options) + '\n');
      });
      client.on('data', chunk => { ackBuffer += chunk.toString(); });
      client.on('end', () => {
        try {
          const { pid } = JSON.parse(ackBuffer.trim());
          resolve({ role: 'loser', daemonPid: pid });
        } catch (e) {
          reject(e);
        }
      });
      client.on('error', () => {
        if (process.platform !== 'win32')
          fs.unlinkSync(socketPath);
        server.listen(socketPath, () => resolve({ role: 'winner', server }));
      });
    });
  });
}

export async function openDashboardApp() {
  const options = parseOpenArgs();
  if (options.kill) {
    await runKillClient();
    return;
  }
  if (options.annotate) {
    await runAnnotateClient(options);
    return;
  }
  process.on('unhandledRejection', error => {
    // eslint-disable-next-line no-console
    console.error('Unhandled promise rejection:', error);
  });

  // Self-destruct if the parent CLI dies before we signal READY. Unregistered
  // before we signal so the daemon outlives the parent.
  const stopSelfDestruct = selfDestructOnParentGone();

  const statePromise = new ManualPromise<AppState>();
  const acquired = await acquireSingleton(options, socket => handleConnection(socket, statePromise));
  if (acquired.role === 'loser') {
    // Another daemon is already running, signal success.
    stopSelfDestruct();
    // eslint-disable-next-line no-console
    console.log(`Dashboard is running pid=${acquired.daemonPid}`);
    return;
  }
  const { server } = acquired;
  process.on('exit', () => server.close());
  try {
    const dashboard = await startDashboardServer(new RegistrySessionProvider(), options);
    dashboard.reveal(options);
    if (options.port !== undefined) {
      // Server mode serves HTTP in the foreground and stays tied to the parent CLI.
      statePromise.resolve({ server: dashboard });
      // eslint-disable-next-line no-console
      console.log(`Listening on ${dashboard.url}`);
    } else {
      // Windowed daemon launches a browser window and detaches from the parent CLI.
      const { page } = await launchApp('dashboard', { onClose: () => gracefullyProcessExitDoNotHang(0) });
      await page.goto(dashboard.url);
      statePromise.resolve({ page, server: dashboard });
      stopSelfDestruct();
      // eslint-disable-next-line no-console
      console.log(`Dashboard is running pid=${process.pid}`);
    }
  } catch (error) {
    // eslint-disable-next-line no-console
    console.log(error);
    gracefullyProcessExitDoNotHang(1);
  }
}

function handleConnection(socket: net.Socket, statePromise: Promise<AppState>) {
  let buffer = '';
  socket.on('data', async data => {
    buffer += data.toString();
    const newlineIndex = buffer.indexOf('\n');
    if (newlineIndex === -1)
      return;
    const line = buffer.slice(0, newlineIndex);
    buffer = buffer.slice(newlineIndex + 1);
    let parsed: DashboardOptions | undefined;
    try {
      parsed = JSON.parse(line);
    } catch {
      // no-op
    }
    if (!parsed) {
      socket.end();
      return;
    }
    const { page, server: dashboard } = await statePromise;
    if (parsed.annotate) {
      const cancellation = new AbortController();
      socket.on('close', () => cancellation.abort());
      socket.on('error', () => cancellation.abort());
      try {
        await page?.bringToFront();
        dashboard.reveal(parsed);
        const result = await dashboard.triggerAnnotate(cancellation.signal);
        socket.end(JSON.stringify(result));
      } catch (e) {
        socket.end(e);
      }
    } else if (parsed.kill) {
      await dashboard.close().catch(() => {});
      gracefullyProcessExitDoNotHang(0, () => new Promise(r => socket.end(r)));
    } else {
      void page?.bringToFront().catch(() => {});
      dashboard.reveal(parsed);
      socket.end(JSON.stringify({ pid: process.pid }) + '\n');
    }
  });
}

export async function openDashboardForContext(context: api.BrowserContext): Promise<void> {
  const server = await startDashboardServer(new IdentitySessionProvider(context), {});

  let closed = false;
  const close = async () => {
    if (closed)
      return;
    closed = true;
    await server.close();
  };

  const { page } = await launchApp('dashboard', { onClose: () => { void close(); } });
  context.on('close', () => { void close(); });
  await page.goto(server.url);
}

async function runKillClient(): Promise<void> {
  const socketPath = dashboardSocketPath();
  await new Promise<void>(resolve => {
    const client = net.connect(socketPath);
    client.once('connect', () => {
      client.write(JSON.stringify({ kill: true }) + '\n');
    });
    client.once('end', () => resolve());
    client.once('error', () => resolve());
  });
}

async function runAnnotateClient(options: DashboardOptions): Promise<void> {
  selfDestructOnParentGone();
  // stdin is a pipe from the process that started this client. It emits 'close' only after it
  // has been read to the end, so read it. Unref it, so that it does not keep the process alive.
  process.stdin.resume().unref();

  const socketPath = dashboardSocketPath();
  const tryConnect = () => new Promise<net.Socket | undefined>(resolve => {
    const s = net.connect(socketPath);
    const onError = () => { s.destroy(); resolve(undefined); };
    s.once('connect', () => { s.off('error', onError); resolve(s); });
    s.once('error', onError);
  });
  const deadline = Date.now() + 15000;
  let socket: net.Socket | undefined;
  while (Date.now() < deadline) {
    socket = await tryConnect();
    if (socket)
      break;
    await new Promise(r => setTimeout(r, 200));
  }
  if (!socket) {
    // eslint-disable-next-line no-console
    console.error('Dashboard did not start in time.');
    gracefullyProcessExitDoNotHang(1);
    return;
  }
  socket.write(JSON.stringify(options) + '\n');
  const chunks: Buffer[] = [];
  await new Promise<void>((resolve, reject) => {
    socket!.on('data', chunk => chunks.push(chunk));
    socket!.on('end', () => resolve());
    socket!.on('error', reject);
  });
  socket.destroy();
  const text = Buffer.concat(chunks).toString();
  if (!text)
    return;
  // eslint-disable-next-line no-console
  console.log(text);
}

function selfDestructOnParentGone(): () => void {
  const onClose = () => gracefullyProcessExitDoNotHang(0);
  process.stdin.on('close', onClose);
  return () => process.stdin.off('close', onClose);
}