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 { Semaphore } from '@isomorphic/semaphore';
import { DEFAULT_PLAYWRIGHT_LAUNCH_TIMEOUT } from '@isomorphic/time';
import { WSServer } from '@utils/wsServer';
import { wrapInASCIIBox } from '@utils/ascii';
import { SocksProxy } from '@utils/socksProxy';
import { debugLogger } from '@utils/debugLogger';
import { isUnderTest } from '@utils/debug';
import { getPlaywrightVersion } from '../server/userAgent';
import { PlaywrightConnection, PlaywrightInitializeResult } from './playwrightConnection';
import { WebSocketServerTransport } from './serverTransport';
import { createPlaywright } from '../server/playwright';
import { Browser } from '../server/browser';
import { nullProgress, ProgressController } from '../server/progress';
import type { AndroidDevice } from '../server/android/android';
import type { Playwright } from '../server/playwright';
import type { LaunchOptions as LaunchOptionsWithoutTimeout } from '../server/types';
type LaunchOptionsWithTimeout = LaunchOptionsWithoutTimeout & { timeout: number };
type ServerOptions = {
path: string;
maxConnections: number;
mode: 'default' | 'launchServer' | 'launchServerShared' | 'extension';
preLaunchedBrowser?: Browser;
preLaunchedAndroidDevice?: AndroidDevice;
preLaunchedSocksProxy?: SocksProxy;
artifactsDir?: string;
unsafe?: boolean;
};
export class PlaywrightServer {
private _playwright: Playwright;
private _options: ServerOptions;
private _wsServer: WSServer;
private _dontReuseBrowsers = new Set<Browser>();
constructor(options: ServerOptions) {
this._options = options;
if (options.preLaunchedBrowser) {
this._playwright = options.preLaunchedBrowser.attribution.playwright;
this._dontReuse(options.preLaunchedBrowser);
}
if (options.preLaunchedAndroidDevice)
this._playwright = options.preLaunchedAndroidDevice._android.attribution.playwright;
this._playwright ??= createPlaywright({ sdkLanguage: 'javascript', isServer: true });
const browserSemaphore = new Semaphore(this._options.maxConnections);
const controllerSemaphore = new Semaphore(1);
const reuseBrowserSemaphore = new Semaphore(1);
this._wsServer = new WSServer({
onRequest: (request, response) => {
if (request.method === 'GET' && request.url === '/json') {
response.setHeader('Content-Type', 'application/json');
response.end(JSON.stringify({
wsEndpointPath: this._options.path,
}));
return;
}
response.end('Running');
},
onUpgrade: (request, socket) => {
const uaError = userAgentVersionMatchesErrorMessage(request.headers['user-agent'] || '');
if (uaError)
return { error: `HTTP/${request.httpVersion} 428 Precondition Required\r\n\r\n${uaError}` };
},
isAllowedPathname: pathname => pathname === this._options.path,
onHeaders: headers => {
if (process.env.PWTEST_SERVER_WS_HEADERS)
headers.push(process.env.PWTEST_SERVER_WS_HEADERS!);
},
onConnection: (request, url, ws, id) => {
const browserHeader = request.headers['x-playwright-browser'];
const browserName = url.searchParams.get('browser') || (Array.isArray(browserHeader) ? browserHeader[0] : browserHeader) || null;
const proxyHeader = request.headers['x-playwright-proxy'];
const proxyValue = url.searchParams.get('proxy') || (Array.isArray(proxyHeader) ? proxyHeader[0] : proxyHeader);
const launchOptionsHeader = request.headers['x-playwright-launch-options'] || '';
const launchOptionsHeaderValue = Array.isArray(launchOptionsHeader) ? launchOptionsHeader[0] : launchOptionsHeader;
const launchOptionsParam = url.searchParams.get('launch-options');
let launchOptions: LaunchOptionsWithTimeout = { timeout: DEFAULT_PLAYWRIGHT_LAUNCH_TIMEOUT };
try {
launchOptions = JSON.parse(launchOptionsParam || launchOptionsHeaderValue);
if (!launchOptions.timeout)
launchOptions.timeout = DEFAULT_PLAYWRIGHT_LAUNCH_TIMEOUT;
} catch (e) {
}
const isExtension = this._options.mode === 'extension';
launchOptions = filterLaunchOptions(launchOptions, isExtension, !!this._options.unsafe);
// Always override artifacts dir with the one from server options.
if (this._options.artifactsDir)
launchOptions.artifactsDir = this._options.artifactsDir;
if (isExtension) {
const connectFilter = url.searchParams.get('connect');
if (connectFilter) {
if (connectFilter !== 'first')
throw new Error(`Unknown connect filter: ${connectFilter}`);
return new PlaywrightConnection(
browserSemaphore,
new WebSocketServerTransport(ws),
false,
this._playwright,
() => this._initConnectMode(id, connectFilter, browserName, launchOptions),
id,
);
}
if (url.searchParams.has('debug-controller')) {
return new PlaywrightConnection(
controllerSemaphore,
new WebSocketServerTransport(ws),
true,
this._playwright,
async () => { throw new Error('shouldnt be used'); },
id,
);
}
return new PlaywrightConnection(
reuseBrowserSemaphore,
new WebSocketServerTransport(ws),
false,
this._playwright,
() => this._initReuseBrowsersMode(browserName, launchOptions, id),
id,
);
}
if (this._options.mode === 'launchServer' || this._options.mode === 'launchServerShared') {
if (this._options.preLaunchedBrowser) {
return new PlaywrightConnection(
browserSemaphore,
new WebSocketServerTransport(ws),
false,
this._playwright,
() => this._initPreLaunchedBrowserMode(id),
id,
);
}
return new PlaywrightConnection(
browserSemaphore,
new WebSocketServerTransport(ws),
false,
this._playwright,
() => this._initPreLaunchedAndroidMode(id),
id,
);
}
return new PlaywrightConnection(
browserSemaphore,
new WebSocketServerTransport(ws),
false,
this._playwright,
() => this._initLaunchBrowserMode(browserName, proxyValue, launchOptions, id),
id,
);
},
});
}
private async _initReuseBrowsersMode(browserName: string | null, launchOptions: LaunchOptionsWithTimeout, id: string): Promise<PlaywrightInitializeResult> {
// Note: reuse browser mode does not support socks proxy, because
// clients come and go, while the browser stays the same.
debugLogger.log('server', `[${id}] engaged reuse browsers mode for ${browserName}`);
const requestedOptions = launchOptionsHash(launchOptions);
let browser = this._playwright.allBrowsers().find(b => {
if (b.options.name !== browserName)
return false;
if (this._dontReuseBrowsers.has(b))
return false;
const existingOptions = launchOptionsHash({ ...b.options.originalLaunchOptions, timeout: DEFAULT_PLAYWRIGHT_LAUNCH_TIMEOUT });
return existingOptions === requestedOptions;
});
// Close remaining browsers of this type+channel. Keep different browser types for the speed.
for (const b of this._playwright.allBrowsers()) {
if (b === browser)
continue;
if (this._dontReuseBrowsers.has(b))
continue;
if (b.options.name === browserName && b.options.channel === launchOptions.channel)
await b.close(nullProgress, { reason: 'Connection terminated' });
}
if (!browser) {
const browserType = this._playwright[(browserName || 'chromium') as 'chromium'];
const controller = new ProgressController();
browser = await controller.run(progress => browserType.launch(progress, {
...launchOptions,
headless: !!process.env.PW_DEBUG_CONTROLLER_HEADLESS,
}), launchOptions.timeout);
}
return {
preLaunchedBrowser: browser,
denyLaunch: true,
dispose: async () => {
// Don't close the pages so that user could debug them,
// but close all the empty contexts to clean up.
// keep around browser so it can be reused by the next connection.
for (const context of browser.contexts()) {
if (!context.pages().length)
await context.close(nullProgress, { reason: 'Connection terminated' });
}
}
};
}
private async _initConnectMode(id: string, filter: 'first', browserName: string | null, launchOptions: LaunchOptionsWithTimeout): Promise<PlaywrightInitializeResult> {
browserName ??= 'chromium';
debugLogger.log('server', `[${id}] engaged connect mode`);
let browser = this._playwright.allBrowsers().find(b => b.options.name === browserName);
if (!browser) {
const browserType = this._playwright[browserName as 'chromium'];
const controller = new ProgressController();
browser = await controller.run(progress => browserType.launch(progress, launchOptions), launchOptions.timeout);
this._dontReuse(browser);
}
return {
preLaunchedBrowser: browser,
denyLaunch: true,
sharedBrowser: true,
};
}
private async _initPreLaunchedBrowserMode(id: string): Promise<PlaywrightInitializeResult> {
debugLogger.log('server', `[${id}] engaged pre-launched (browser) mode`);
const browser = this._options.preLaunchedBrowser!;
// In pre-launched mode, keep only the pre-launched browser.
for (const b of this._playwright.allBrowsers()) {
if (b !== browser)
await b.close(nullProgress, { reason: 'Connection terminated' });
}
return {
preLaunchedBrowser: browser,
socksProxy: this._options.preLaunchedSocksProxy,
sharedBrowser: this._options.mode === 'launchServerShared',
denyLaunch: true,
};
}
private async _initPreLaunchedAndroidMode(id: string): Promise<PlaywrightInitializeResult> {
debugLogger.log('server', `[${id}] engaged pre-launched (Android) mode`);
const androidDevice = this._options.preLaunchedAndroidDevice!;
return {
preLaunchedAndroidDevice: androidDevice,
denyLaunch: true,
};
}
private async _initLaunchBrowserMode(browserName: string | null, proxyValue: string | undefined, launchOptions: LaunchOptionsWithTimeout, id: string): Promise<PlaywrightInitializeResult> {
debugLogger.log('server', `[${id}] engaged launch mode for "${browserName}"`);
let socksProxy: SocksProxy | undefined;
if (proxyValue) {
socksProxy = new SocksProxy();
socksProxy.setPattern(proxyValue);
launchOptions.socksProxyPort = await socksProxy.listen(0);
debugLogger.log('server', `[${id}] started socks proxy on port ${launchOptions.socksProxyPort}`);
} else {
launchOptions.socksProxyPort = undefined;
}
const browserType = this._playwright[browserName as 'chromium'];
const controller = new ProgressController();
const browser = await controller.run(progress => browserType.launch(progress, launchOptions), launchOptions.timeout);
this._dontReuse(browser);
return {
preLaunchedBrowser: browser,
socksProxy,
denyLaunch: true,
dispose: async () => {
await browser.close(nullProgress, { reason: 'Connection terminated' });
socksProxy?.close();
},
};
}
private _dontReuse(browser: Browser) {
this._dontReuseBrowsers.add(browser);
browser.on(Browser.Events.Disconnected, () => {
this._dontReuseBrowsers.delete(browser);
});
}
async listen(port: number = 0, hostname?: string): Promise<string> {
return this._wsServer.listen(port, hostname, this._options.path);
}
async close() {
await this._wsServer.close();
// Close all browsers that were launched by this server (e.g. in reuse mode)
// to avoid leaking browser processes that may hold connections to test servers.
for (const browser of this._playwright.allBrowsers())
await browser.close(nullProgress, { reason: 'Server closed' });
}
}
function userAgentVersionMatchesErrorMessage(userAgent: string) {
const match = userAgent.match(/^Playwright\/(\d+\.\d+\.\d+)/);
if (!match) {
// Cannot parse user agent - be lax.
return;
}
const received = match[1].split('.').slice(0, 2).join('.');
const expected = getPlaywrightVersion(true);
if (received !== expected) {
return wrapInASCIIBox([
`Playwright version mismatch:`,
` - server version: v${expected}`,
` - client version: v${received}`,
``,
`If you are using VSCode extension, restart VSCode.`,
``,
`If you are connecting to a remote service,`,
`keep your local Playwright version in sync`,
`with the remote service version.`,
``,
`<3 Playwright Team`
].join('\n'), 1);
}
}
function launchOptionsHash(options: LaunchOptionsWithTimeout) {
const copy = { ...options };
for (const k of Object.keys(copy)) {
const key = k as keyof LaunchOptionsWithTimeout;
if (copy[key] === defaultLaunchOptions[key])
delete copy[key];
}
for (const key of optionsThatAllowBrowserReuse)
delete copy[key];
return JSON.stringify(copy);
}
function filterLaunchOptions(options: LaunchOptionsWithTimeout, isExtension: boolean, unsafe: boolean): LaunchOptionsWithTimeout {
const allowUnsafe = isExtension || unsafe;
return {
channel: options.channel,
args: allowUnsafe ? options.args : undefined,
ignoreAllDefaultArgs: allowUnsafe ? options.ignoreAllDefaultArgs : undefined,
ignoreDefaultArgs: allowUnsafe ? options.ignoreDefaultArgs : undefined,
timeout: options.timeout,
headless: options.headless,
proxy: options.proxy,
chromiumSandbox: allowUnsafe ? options.chromiumSandbox : undefined,
firefoxUserPrefs: (isUnderTest() || allowUnsafe) ? options.firefoxUserPrefs : undefined,
slowMo: options.slowMo,
executablePath: (isUnderTest() || allowUnsafe) ? options.executablePath : undefined,
downloadsPath: (isUnderTest() || isExtension) ? options.downloadsPath : undefined,
artifactsDir: (isUnderTest() || isExtension) ? options.artifactsDir : undefined,
};
}
const defaultLaunchOptions: Partial<LaunchOptionsWithTimeout> = {
ignoreAllDefaultArgs: false,
handleSIGINT: false,
handleSIGTERM: false,
handleSIGHUP: false,
headless: true,
};
const optionsThatAllowBrowserReuse: (keyof LaunchOptionsWithTimeout)[] = [
'headless',
'timeout',
'tracesDir',
'artifactsDir',
];