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 colors from 'colors/safe';
import { rewriteErrorMessage } from '@utils/stackTrace';
import { isUnderTest } from '@utils/debug';
import { debugLogger } from '@utils/debugLogger';
import { emptyZone } from '@utils/zones';
import { ValidationError, findValidator, maybeFindValidator } from '@protocol/validator';
import { createCallIdGenerator } from '@isomorphic/trace/traceUtils';
import { EventEmitter } from './eventEmitter';
import { Android, AndroidDevice, AndroidSocket } from './android';
import { Artifact } from './artifact';
import { Browser } from './browser';
import { BrowserContext } from './browserContext';
import { BrowserType } from './browserType';
import { CDPSession } from './cdpSession';
import { ChannelOwner } from './channelOwner';
import { createInstrumentation } from './clientInstrumentation';
import { Debugger } from './debugger';
import { Dialog } from './dialog';
import { DisposableObject } from './disposable';
import { Electron, ElectronApplication } from './electron';
import { ElementHandle } from './elementHandle';
import { AbortError, TargetClosedError, parseError } from './errors';
import { APIRequestContext } from './fetch';
import { Frame } from './frame';
import { JSHandle } from './jsHandle';
import { JsonPipe } from './jsonPipe';
import { LocalUtils } from './localUtils';
import { Request, Response, Route, WebSocket, WebSocketRoute } from './network';
import { BindingCall, Page } from './page';
import { Playwright } from './playwright';
import { Stream } from './stream';
import { Tracing } from './tracing';
import { Worker } from './worker';
import { WritableStream } from './writableStream';
import { kNoTimeout } from './timeoutSettings';
import type { ClientInstrumentation } from './clientInstrumentation';
import type { HeadersArray } from './types';
import type { ValidatorContext } from '@protocol/validator';
import type * as channels from './channels';
class Root extends ChannelOwner<channels.RootChannel> {
constructor(connection: Connection) {
super(connection, 'Root', '', {});
}
async initialize(): Promise<Playwright> {
return Playwright.from((await this._channel.initialize({
sdkLanguage: 'javascript',
supportsLoneSurrogates: true,
}, kNoTimeout)).playwright);
}
}
class DummyChannelOwner extends ChannelOwner {
}
export type ChannelOwnerFactory = (parent: ChannelOwner, type: string, guid: string, initializer: any) => ChannelOwner;
export class Connection extends EventEmitter {
readonly _objects = new Map<string, ChannelOwner>();
onmessage = (message: object): void => {};
private _nextCallId = createCallIdGenerator();
private _callbacks = new Map<string, { resolve: (a: any) => void, reject: (a: Error) => void, signal: AbortSignal | undefined, title: string | undefined, type: string, method: string }>();
private _rootObject: Root;
private _closedError: Error | undefined;
private _isRemote = false;
private _localUtils?: LocalUtils;
private _rawBuffers = false;
// Some connections allow resolving in-process dispatchers.
toImpl: ((client: ChannelOwner | Connection) => any) | undefined;
private _tracingCount = 0;
readonly _instrumentation: ClientInstrumentation;
// Used from @playwright/test fixtures -> TODO remove?
readonly headers: HeadersArray;
private _objectFactories = new Map<string, ChannelOwnerFactory>();
constructor(localUtils?: LocalUtils, instrumentation?: ClientInstrumentation, headers: HeadersArray = []) {
super();
this._instrumentation = instrumentation || createInstrumentation();
this._localUtils = localUtils;
this._rootObject = new Root(this);
this.headers = headers;
this.registerObjectFactories({
Android: (parent, type, guid, init) => new Android(parent, type, guid, init),
AndroidDevice: (parent, type, guid, init) => new AndroidDevice(parent, type, guid, init),
AndroidSocket: (parent, type, guid, init) => new AndroidSocket(parent, type, guid, init),
APIRequestContext: (parent, type, guid, init) => new APIRequestContext(parent, type, guid, init),
Artifact: (parent, type, guid, init) => new Artifact(parent, type, guid, init),
BindingCall: (parent, type, guid, init) => new BindingCall(parent, type, guid, init),
Browser: (parent, type, guid, init) => new Browser(parent, type, guid, init),
BrowserContext: (parent, type, guid, init) => new BrowserContext(parent, type, guid, init),
BrowserType: (parent, type, guid, init) => new BrowserType(parent, type, guid, init),
CDPSession: (parent, type, guid, init) => new CDPSession(parent, type, guid, init),
Debugger: (parent, type, guid, init) => new Debugger(parent, type, guid, init),
Dialog: (parent, type, guid, init) => new Dialog(parent, type, guid, init),
Disposable: (parent, type, guid, init) => new DisposableObject(parent, type, guid, init),
Electron: (parent, type, guid, init) => new Electron(parent, type, guid, init),
ElectronApplication: (parent, type, guid, init) => new ElectronApplication(parent, type, guid, init),
ElementHandle: (parent, type, guid, init) => new ElementHandle(parent, type, guid, init),
Frame: (parent, type, guid, init) => new Frame(parent, type, guid, init),
JSHandle: (parent, type, guid, init) => new JSHandle(parent, type, guid, init),
JsonPipe: (parent, type, guid, init) => new JsonPipe(parent, type, guid, init),
LocalUtils: (parent, type, guid, init) => {
const result = new LocalUtils(parent, type, guid, init);
if (!this._localUtils)
this._localUtils = result;
return result;
},
Page: (parent, type, guid, init) => new Page(parent, type, guid, init),
Playwright: (parent, type, guid, init) => new Playwright(parent, type, guid, init),
Request: (parent, type, guid, init) => new Request(parent, type, guid, init),
Response: (parent, type, guid, init) => new Response(parent, type, guid, init),
Route: (parent, type, guid, init) => new Route(parent, type, guid, init),
Stream: (parent, type, guid, init) => new Stream(parent, type, guid, init),
SocksSupport: (parent, type, guid, init) => new DummyChannelOwner(parent, type, guid, init),
Tracing: (parent, type, guid, init) => new Tracing(parent, type, guid, init),
WebSocket: (parent, type, guid, init) => new WebSocket(parent, type, guid, init),
WebSocketRoute: (parent, type, guid, init) => new WebSocketRoute(parent, type, guid, init),
Worker: (parent, type, guid, init) => new Worker(parent, type, guid, init),
WritableStream: (parent, type, guid, init) => new WritableStream(parent, type, guid, init),
});
}
registerObjectFactories(factories: Record<string, ChannelOwnerFactory>) {
for (const [type, factory] of Object.entries(factories))
this._objectFactories.set(type, factory);
}
markAsRemote() {
this._isRemote = true;
}
isRemote() {
return this._isRemote;
}
useRawBuffers() {
this._rawBuffers = true;
}
rawBuffers() {
return this._rawBuffers;
}
localUtils(): LocalUtils | undefined {
return this._localUtils;
}
async initializePlaywright(): Promise<Playwright> {
return await this._rootObject.initialize();
}
getObjectWithKnownName(guid: string): any {
return this._objects.get(guid)!;
}
setIsTracing(isTracing: boolean) {
if (isTracing)
this._tracingCount++;
else
this._tracingCount--;
}
async sendMessageToServer(object: ChannelOwner, method: string, params: any, options: { apiName?: string, title?: string, internal?: boolean, frames?: channels.StackFrame[], callId?: string, signal?: AbortSignal, timeout: number }): Promise<any> {
// Fire-and-forget: server intentionally never replies to __waitInfo__,
// so silently drop it after the connection is closed or the object was collected.
if (method === '__waitInfo__' && (this._closedError || object._wasCollected))
return;
if (this._closedError)
throw this._closedError;
if (object._wasCollected)
throw new Error('The object has been collected to prevent unbounded heap growth.');
const signal = options.signal;
if (signal?.aborted)
throw new AbortError(undefined, { cause: signal.reason });
const guid = object._guid;
const type = object._type;
const id = options.callId ?? this._nextCallId();
const message = { id, guid, method, params };
if (debugLogger.isEnabled('channel')) {
// Do not include metadata in debug logs to avoid noise.
debugLogger.log('channel', 'SEND> ' + JSON.stringify(message));
}
const location = options.frames?.[0] ? { file: options.frames[0].file, line: options.frames[0].line, column: options.frames[0].column } : undefined;
const metadata: channels.Metadata = { title: options.title, location, internal: options.internal, timeout: options.timeout };
if (this._tracingCount && options.frames && type !== 'LocalUtils')
this._localUtils?.addStackToTracingNoReply({ callData: { stack: options.frames ?? [], id } }).catch(() => {});
// We need to exit zones before calling into the server, otherwise
// when we receive events from the server, we would be in an API zone.
emptyZone.run(() => this.onmessage({ ...message, metadata }));
// Fire-and-forget: server intentionally never replies to __waitInfo__.
if (method === '__waitInfo__')
return;
let abortListener: (() => void) | undefined;
if (signal) {
abortListener = () => {
const reason = signal.reason instanceof Error ? signal.reason.message : String(signal.reason);
emptyZone.run(() => this.onmessage({ guid, method: '__abort__', params: { id, reason } }));
};
signal.addEventListener('abort', abortListener, { once: true });
}
try {
return await new Promise((resolve, reject) => this._callbacks.set(id, { resolve, reject, signal, title: options.title, type, method }));
} finally {
if (abortListener)
signal!.removeEventListener('abort', abortListener);
}
}
private _validatorFromWireContext(): ValidatorContext {
return {
tChannelImpl: this._tChannelImplFromWire.bind(this),
binary: this._rawBuffers ? 'buffer' : 'fromBase64',
isUnderTest,
};
}
dispatch(message: object) {
if (this._closedError)
return;
const { id, guid, method, params, result, error, errorDetails, log } = message as any;
if (id) {
if (debugLogger.isEnabled('channel'))
debugLogger.log('channel', '<RECV ' + JSON.stringify(message));
const callback = this._callbacks.get(id);
if (!callback)
throw new Error(`Cannot find command to respond: ${id}`);
this._callbacks.delete(id);
if (error && !result) {
const parsedError = parseError(error);
if (callback.signal?.aborted && parsedError instanceof AbortError)
parsedError.cause = callback.signal.reason;
parsedError.log = log || [];
rewriteErrorMessage(parsedError, parsedError.message + formatCallLog(log));
const detailsValidator = maybeFindValidator(callback.type, callback.method, 'ErrorDetails');
if (detailsValidator)
parsedError.details = detailsValidator(errorDetails ?? {}, '', this._validatorFromWireContext());
callback.reject(parsedError);
} else {
const validator = findValidator(callback.type, callback.method, 'Result');
callback.resolve(validator(result, '', this._validatorFromWireContext()));
}
return;
}
if (debugLogger.isEnabled('channel'))
debugLogger.log('channel', '<EVENT ' + JSON.stringify(message));
if (method === '__create__') {
this._createRemoteObject(guid, params.type, params.guid, params.initializer);
return;
}
const object = this._objects.get(guid);
if (!object)
throw new Error(`Cannot find object to "${method}": ${guid}`);
if (method === '__adopt__') {
const child = this._objects.get(params.guid);
if (!child)
throw new Error(`Unknown new child: ${params.guid}`);
object._adopt(child);
return;
}
if (method === '__dispose__') {
object._dispose(params.reason);
return;
}
const validator = findValidator(object._type, method, 'Event');
(object._channel as any).emit(method, validator(params, '', this._validatorFromWireContext()));
}
close(cause?: string) {
if (this._closedError)
return;
this._closedError = new TargetClosedError(cause);
for (const callback of this._callbacks.values())
callback.reject(this._closedError);
this._callbacks.clear();
this.emit('close');
}
private _tChannelImplFromWire(names: '*' | string[], arg: any, path: string, context: ValidatorContext) {
if (arg && typeof arg === 'object' && typeof arg.guid === 'string') {
const object = this._objects.get(arg.guid)!;
if (!object)
throw new Error(`Object with guid ${arg.guid} was not bound in the connection`);
if (names !== '*' && !names.includes(object._type))
throw new ValidationError(`${path}: expected channel ${names.toString()}`);
return object._channel;
}
throw new ValidationError(`${path}: expected channel ${names.toString()}`);
}
private _createRemoteObject(parentGuid: string, type: string, guid: string, initializer: any): any {
const parent = this._objects.get(parentGuid);
if (!parent)
throw new Error(`Cannot find parent object ${parentGuid} to create ${guid}`);
const validator = findValidator(type, '', 'Initializer');
initializer = validator(initializer, '', this._validatorFromWireContext());
const factory = this._objectFactories.get(type);
if (!factory)
throw new Error('Missing type ' + type);
return factory(parent, type, guid, initializer);
}
}
function formatCallLog(log: string[] | undefined): string {
if (!log || !log.some(l => !!l))
return '';
return `
Call log:
${colors.dim(log.join('\n'))}
`;
}