Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
/**
* 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 url from 'url';
import open from 'open';
import { HttpServer } from '@utils/httpServer';
import { gracefullyProcessExitDoNotHang } from '@utils/processLauncher';
import { isUnderTest } from '@utils/debug';
import { isCodingAgent } from '@utils/env';
import { isPathInside } from '@utils/fileUtils';
import { libPath } from '../../../package';
import { syncLocalStorageWithSettings } from '../../launchApp';
import { launchApp } from '../../launchApp';
import { createPlaywright } from '../../playwright';
import { ProgressController } from '../../progress';
import { nullProgress } from '../../progress';
import type { Transport } from '@utils/httpServer';
import type { BrowserType } from '../../browserType';
import type { Page } from '../../page';
import type http from 'http';
// HMR: build-time flag — `true` in watch builds, `false` in release. Mirror of
// the one in dashboardApp.ts; esbuild's `define` replaces both.
declare const __PW_HMR__: boolean;
export type TraceViewerServerOptions = {
host?: string;
port?: number;
isServer?: boolean;
transport?: Transport;
};
export type TraceViewerRedirectOptions = {
args?: string[];
grep?: string;
grepInvert?: string;
project?: string[];
reporter?: string[];
webApp?: string;
isServer?: boolean;
};
export type TraceViewerAppOptions = {
headless?: boolean;
persistentContextOptions?: Parameters<BrowserType['launchPersistentContext']>[2];
};
const tracesDirMarker = 'traces.dir';
function validateTraceUrlOrPath(traceFileOrUrl: string | undefined): string | undefined {
if (!traceFileOrUrl)
return traceFileOrUrl;
if (traceFileOrUrl.startsWith('http://') || traceFileOrUrl.startsWith('https://'))
return traceFileOrUrl;
let traceFile = traceFileOrUrl;
// If .json is requested, we'll synthesize it.
if (traceFile.endsWith('.json'))
return toFilePathUrl(traceFile);
try {
const stat = fs.statSync(traceFile);
// If the path is a directory, add 'trace.dir' which has a special handler.
if (stat.isDirectory())
traceFile = path.join(traceFile, tracesDirMarker);
return toFilePathUrl(traceFile);
} catch {
throw new Error(`Trace file ${traceFileOrUrl} does not exist!`);
}
}
export async function startTraceViewerServer(options: TraceViewerServerOptions & { allowedFileRoots: () => string[] }): Promise<HttpServer> {
const server = new HttpServer(libPath('vite', 'traceViewer'));
const isAllowed = (filePath: string) => options.allowedFileRoots().some(root => isPathInside(path.resolve(root), filePath));
const serveTraceDataRoute = (request: http.IncomingMessage, response: http.ServerResponse, relativePath: string): boolean => {
if (!relativePath.startsWith('/file'))
return false;
const url = new URL('http://localhost' + request.url!);
try {
const filePath = path.resolve(url.searchParams.get('path')!);
if (!isAllowed(filePath)) {
response.statusCode = 403;
response.end();
return true;
}
if (fs.existsSync(filePath))
return server.serveFile(request, response, filePath, undefined, { skipRootCheck: true });
// If .json is requested, we'll synthesize it for zip-less operation.
if (filePath.endsWith('.json')) {
const fullPrefix = filePath.substring(0, filePath.length - '.json'.length);
// Live traces are stored in the common artifacts directory. Trace files
// corresponding to a particular test, all have the same unique prefix.
return sendTraceDescriptor(response, path.dirname(fullPrefix), path.basename(fullPrefix));
}
// If 'trace.dir' is requested, return all trace files inside.
if (filePath.endsWith(tracesDirMarker))
return sendTraceDescriptor(response, path.dirname(filePath));
} catch {
}
response.statusCode = 404;
response.end();
return true;
};
// HMR: watch builds serve the trace viewer (incl. UI mode) through an
// embedded Vite dev server. 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. The service worker at /trace/sw.bundle.js
// still ships from the separate vite.sw.config.ts build — serve it from lib.
if (__PW_HMR__ && process.env.PW_HMR_STATIC !== '1') {
const traceViewerRoot = path.resolve(__dirname, '..', '..', 'trace-viewer');
const devServer = await server.createViteDevServer({ root: traceViewerRoot, base: '/trace/' });
server.routePrefix('/trace', (request, response) => {
const url = new URL('http://localhost' + request.url!);
const relativePath = url.pathname.slice('/trace'.length);
if (relativePath.startsWith('/file'))
return serveTraceDataRoute(request, response, relativePath);
if (relativePath === '/sw.bundle.js')
return server.serveFile(request, response, path.join(libPath('vite', 'traceViewer'), 'sw.bundle.js'));
devServer.middlewares(request, response, HttpServer.notFoundFallback(response));
return true;
});
} else {
server.routePrefix('/trace', (request, response) => {
const url = new URL('http://localhost' + request.url!);
const relativePath = url.pathname.slice('/trace'.length);
if (relativePath.startsWith('/file'))
return serveTraceDataRoute(request, response, relativePath);
const absolutePath = path.join(libPath('vite', 'traceViewer'), ...relativePath.split('/'));
return server.serveFile(request, response, absolutePath);
});
}
const transport = options.transport || (options.isServer ? new StdinServer() : undefined);
if (transport)
server.createWebSocket(() => transport);
const { host, port } = options;
await server.start({ preferredPort: port, host });
return server;
}
export async function installRootRedirect(server: HttpServer, traceUrl: string | undefined, options: TraceViewerRedirectOptions) {
const params = new URLSearchParams();
if (path.sep !== path.posix.sep)
params.set('pathSeparator', path.sep);
if (traceUrl)
params.append('trace', traceUrl);
if (server.wsGuid())
params.append('ws', server.wsGuid()!);
if (options?.isServer)
params.append('isServer', '');
if (isUnderTest())
params.append('isUnderTest', 'true');
for (const arg of options.args || [])
params.append('arg', arg);
if (options.grep)
params.append('grep', options.grep);
if (options.grepInvert)
params.append('grepInvert', options.grepInvert);
for (const project of options.project || [])
params.append('project', project);
for (const reporter of options.reporter || [])
params.append('reporter', reporter);
const urlPath = `./trace/${options.webApp || 'index.html'}?${params.toString()}`;
server.routePath('/', (_, response) => {
response.statusCode = 302;
response.setHeader('Location', urlPath);
response.end();
return true;
});
}
export async function runTraceViewerApp(traceUrl: string | undefined, browserName: string, options: TraceViewerServerOptions & { headless?: boolean }) {
traceUrl = validateTraceUrlOrPath(traceUrl);
const allowedFileRoots = traceFileRoots(traceUrl);
const server = await startTraceViewerServer({ ...options, allowedFileRoots: () => allowedFileRoots });
await installRootRedirect(server, traceUrl, options);
const page = await openTraceViewerApp(server.urlPrefix('precise'), browserName, options);
page.on('close', () => gracefullyProcessExitDoNotHang(0));
return page;
}
export async function runTraceInBrowser(traceUrl: string | undefined, options: TraceViewerServerOptions) {
traceUrl = validateTraceUrlOrPath(traceUrl);
const allowedFileRoots = traceFileRoots(traceUrl);
const server = await startTraceViewerServer({ ...options, allowedFileRoots: () => allowedFileRoots });
await installRootRedirect(server, traceUrl, options);
await openTraceInBrowser(server.urlPrefix('human-readable'));
}
function traceFileRoots(traceUrl: string | undefined): string[] {
if (traceUrl?.startsWith('file://')) {
try {
return [path.dirname(url.fileURLToPath(traceUrl))];
} catch {
}
}
if (traceUrl?.startsWith('file?path=')) {
try {
const url = new URL(traceUrl, 'http://localhost');
return [path.dirname(url.searchParams.get('path')!)];
} catch {
}
}
return [process.cwd()];
}
export async function openTraceViewerApp(url: string, browserName: string, options?: TraceViewerAppOptions): Promise<Page> {
const traceViewerPlaywright = createPlaywright({ sdkLanguage: 'javascript', isInternalPlaywright: true });
const traceViewerBrowser = isUnderTest() ? 'chromium' : browserName;
const { context, page } = await launchApp(traceViewerPlaywright[traceViewerBrowser as 'chromium'], {
sdkLanguage: traceViewerPlaywright.options.sdkLanguage,
windowSize: { width: 1280, height: 800 },
persistentContextOptions: {
...options?.persistentContextOptions,
args: isUnderTest() ? ['--remote-debugging-port=0'] : undefined,
headless: !!options?.headless,
colorScheme: isUnderTest() ? 'light' : undefined,
},
});
const controller = new ProgressController();
await controller.run(async progress => {
await context._browser._defaultContext!.loadDefaultContextAsIs(progress);
if (process.env.PWTEST_PRINT_WS_ENDPOINT) {
// eslint-disable-next-line no-restricted-properties
process.stderr.write('DevTools listening on: ' + context._browser.options.wsEndpoint + '\n');
}
if (!isUnderTest())
await progress.race(syncLocalStorageWithSettings(page, 'traceviewer'));
if (isUnderTest())
page.on('close', () => context.close(nullProgress, { reason: 'Trace viewer closed' }).catch(() => {}));
await page.mainFrame().goto(progress, url);
});
return page;
}
export async function openTraceInBrowser(url: string) {
// eslint-disable-next-line no-console
console.log('\nListening on ' + url);
if (!isUnderTest() && !isCodingAgent())
await open(url.replace('0.0.0.0', 'localhost')).catch(() => {});
}
class StdinServer implements Transport {
private _pollTimer: NodeJS.Timeout | undefined;
private _traceUrl: string | undefined;
constructor() {
process.stdin.on('data', data => {
const url = validateTraceUrlOrPath(data.toString().trim());
if (!url || url === this._traceUrl)
return;
if (url.endsWith('.json'))
this._pollLoadTrace(url);
else
this._loadTrace(url);
});
process.stdin.on('close', () => gracefullyProcessExitDoNotHang(0));
}
onconnect() {
}
async dispatch(method: string, params: any) {
if (method === 'initialize') {
if (this._traceUrl)
this._loadTrace(this._traceUrl);
}
}
onclose() {
}
sendEvent?: (method: string, params: any) => void;
close?: () => void;
private _loadTrace(traceUrl: string) {
this._traceUrl = traceUrl;
clearTimeout(this._pollTimer);
this.sendEvent?.('loadTraceRequested', { traceUrl });
}
private _pollLoadTrace(url: string) {
this._loadTrace(url);
this._pollTimer = setTimeout(() => {
this._pollLoadTrace(url);
}, 500);
}
}
function sendTraceDescriptor(response: http.ServerResponse, traceDir: string, tracePrefix?: string) {
response.statusCode = 200;
response.setHeader('Content-Type', 'application/json');
response.end(JSON.stringify(traceDescriptor(traceDir, tracePrefix)));
return true;
}
function traceDescriptor(traceDir: string, tracePrefix: string | undefined) {
const result: { entries: { name: string, path: string }[] } = {
entries: []
};
for (const name of fs.readdirSync(traceDir)) {
if (!tracePrefix || name.startsWith(tracePrefix))
result.entries.push({ name, path: toFilePathUrl(path.join(traceDir, name)) });
}
for (const dir of ['resources', 'screencast', 'screenshots', 'aria', 'attachments', 'src']) {
const dirPath = path.join(traceDir, dir);
if (fs.existsSync(dirPath)) {
for (const name of fs.readdirSync(dirPath))
result.entries.push({ name: dir + '/' + name, path: toFilePathUrl(path.join(dirPath, name)) });
}
}
return result;
}
function toFilePathUrl(filePath: string): string {
return `file?path=${encodeURIComponent(filePath)}`;
}