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 { getMetainfo } from '@isomorphic/protocolMetainfo';
import { renderFullTitleForCall } from '@isomorphic/protocolFormatter';
import { monotonicTime } from '@isomorphic/time';
import { SdkObject } from './instrumentation';
import { BrowserContext } from './browserContext';
import type { CallMetadata, InstrumentationListener } from './instrumentation';
import type { Progress } from './progress';
import type { Point } from './types';
const symbol = Symbol('Debugger');
const kApiCallsFlushDelay = 500;
const DebuggerEvent = {
PausedStateChanged: 'pausedstatechanged',
ApiCallsUpdated: 'apicallsupdated',
} as const;
type PauseAt = { next?: boolean, location?: { file: string, line?: number, column?: number } };
export type ApiCallUpdate = {
id: string;
title: string;
location?: { file: string, line?: number, column?: number };
newLogEntries: string[];
actionPoint?: Point;
status: 'running' | 'success' | 'error';
error?: string;
};
type OngoingCall = {
metadata: CallMetadata;
actionPoint?: Point;
sentLogCount: number;
status: 'running' | 'success' | 'error';
};
type DebuggerEventMap = {
[DebuggerEvent.PausedStateChanged]: [];
[DebuggerEvent.ApiCallsUpdated]: [apiCalls: ApiCallUpdate[]];
};
export class Debugger extends SdkObject<DebuggerEventMap> implements InstrumentationListener {
static Events = DebuggerEvent;
private _pauseAt: PauseAt = {};
private _pausedCall: { metadata: CallMetadata, sdkObject: SdkObject, resolve: () => void } | undefined;
private _enabled = false;
private _pauseBeforeWaitingActions = false; // instead of inside input actions
private _context: BrowserContext;
private _apiCallsEnabled = false;
private _ongoingCalls = new Map<string, OngoingCall>();
private _apiCallsWithPendingUpdates = new Set<string>();
private _apiCallsFlushTimer: NodeJS.Timeout | undefined;
private _muted = false;
constructor(context: BrowserContext) {
super(context, 'debugger');
this._context = context;
(this._context as any)[symbol] = this;
// Register as a last listener so the debugger pause runs after other listeners
// (e.g. recorder action-point capture) have recorded their state.
context.instrumentation.addListener(this, context, { order: 'last' });
this._context.once(BrowserContext.Events.Close, () => {
this._context.instrumentation.removeListener(this);
if (this._apiCallsFlushTimer)
clearTimeout(this._apiCallsFlushTimer);
});
}
requestPause(progress: Progress) {
if (this.isPaused())
throw new Error('Debugger is already paused');
this.setPauseBeforeWaitingActions();
this.setPauseAt({ next: true });
}
doResume(progress: Progress) {
if (!this.isPaused())
throw new Error('Debugger is not paused');
this.resume();
}
next(progress: Progress) {
if (!this.isPaused())
throw new Error('Debugger is not paused');
this.setPauseBeforeWaitingActions();
this.setPauseAt({ next: true });
this.resume();
}
runTo(progress: Progress, location: { file: string, line?: number, column?: number }) {
if (!this.isPaused())
throw new Error('Debugger is not paused');
this.setPauseBeforeWaitingActions();
this.setPauseAt({ location });
this.resume();
}
async setMuted(muted: boolean) {
this._muted = muted;
}
async onBeforeCall(progress: Progress, sdkObject: SdkObject): Promise<void> {
const { metadata } = progress;
if (!metadata.internal && metadata.method)
this._ongoingCalls.set(metadata.id, { metadata, sentLogCount: 0, status: 'running' });
if (this._apiCallsEnabled) {
this._apiCallsWithPendingUpdates.add(metadata.id);
this._flushApiCalls();
}
if (this._muted || metadata.internal)
return;
const metainfo = getMetainfo(metadata);
const pauseOnPauseCall = this._enabled && metadata.type === 'BrowserContext' && metadata.method === 'pause';
const pauseBeforeAction = !!this._pauseAt.next && !!metainfo?.pause && (this._pauseBeforeWaitingActions || !metainfo?.isAutoWaiting);
const pauseOnLocation = !!this._pauseAt.location && matchesLocation(metadata, this._pauseAt.location);
if (pauseOnPauseCall || pauseBeforeAction || pauseOnLocation)
await this._pause(progress, sdkObject);
}
async onBeforeInputAction(progress: Progress, sdkObject: SdkObject, point?: Point): Promise<void> {
const { metadata } = progress;
const call = this._ongoingCalls.get(metadata.id);
if (call) {
call.actionPoint = point;
if (this._apiCallsEnabled) {
this._apiCallsWithPendingUpdates.add(metadata.id);
this._flushApiCalls();
}
}
if (this._muted || metadata.internal)
return;
const metainfo = getMetainfo(metadata);
const pauseBeforeInput = !!this._pauseAt.next && !!metainfo?.pause && !!metainfo?.isAutoWaiting && !this._pauseBeforeWaitingActions;
if (pauseBeforeInput)
await this._pause(progress, sdkObject);
}
async onAfterCall(progress: Progress, sdkObject: SdkObject): Promise<void> {
const { metadata } = progress;
const call = this._ongoingCalls.get(metadata.id);
if (!call)
return;
call.status = metadata.error ? 'error' : 'success';
if (this._apiCallsEnabled) {
this._apiCallsWithPendingUpdates.add(metadata.id);
this._flushApiCalls();
}
this._ongoingCalls.delete(metadata.id);
}
onCallLog(sdkObject: SdkObject, metadata: CallMetadata, logName: string, message: string): void {
if (this._apiCallsEnabled && this._ongoingCalls.has(metadata.id)) {
this._apiCallsWithPendingUpdates.add(metadata.id);
this._scheduleApiCallsFlush();
}
}
enableApiCalls() {
if (this._apiCallsEnabled)
return;
this._apiCallsEnabled = true;
this._pauseBeforeWaitingActions = false;
for (const id of this._ongoingCalls.keys())
this._apiCallsWithPendingUpdates.add(id);
this._flushApiCalls();
}
private _scheduleApiCallsFlush() {
if (this._apiCallsFlushTimer || !this._apiCallsWithPendingUpdates.size)
return;
this._apiCallsFlushTimer = setTimeout(() => this._flushApiCalls(), kApiCallsFlushDelay);
}
private _flushApiCalls() {
if (this._apiCallsFlushTimer) {
clearTimeout(this._apiCallsFlushTimer);
this._apiCallsFlushTimer = undefined;
}
const updates: ApiCallUpdate[] = [];
for (const id of this._apiCallsWithPendingUpdates) {
const call = this._ongoingCalls.get(id);
if (!call)
continue;
updates.push({
id: call.metadata.id,
title: renderFullTitleForCall(call.metadata, this._context._browser.sdkLanguage()) ?? '',
location: call.metadata.location,
newLogEntries: call.metadata.log.slice(call.sentLogCount),
actionPoint: call.actionPoint,
status: call.metadata.error ? 'error' : call.status,
error: call.metadata.error?.error?.message,
});
call.sentLogCount = call.metadata.log.length;
}
this._apiCallsWithPendingUpdates.clear();
if (updates.length)
this.emit(Debugger.Events.ApiCallsUpdated, updates);
}
private async _pause(progress: Progress, sdkObject: SdkObject) {
const { metadata } = progress;
if (this._muted || metadata.internal)
return;
if (this._pausedCall)
return;
this._pauseAt = {};
metadata.pauseStartTime = monotonicTime();
const result = new Promise<void>(resolve => {
this._pausedCall = { metadata, sdkObject, resolve };
});
this.emit(Debugger.Events.PausedStateChanged);
return result;
}
resume() {
if (!this._pausedCall)
return;
this._pausedCall.metadata.pauseEndTime = monotonicTime();
this._pausedCall.resolve();
this._pausedCall = undefined;
this.emit(Debugger.Events.PausedStateChanged);
}
setPauseBeforeWaitingActions() {
if (this._apiCallsEnabled)
return;
this._pauseBeforeWaitingActions = true;
}
setPauseAt(at: { next?: boolean, location?: { file: string, line?: number, column?: number } } = {}) {
this._enabled = true;
this._pauseAt = at;
}
isPaused(metadata?: CallMetadata): boolean {
if (metadata)
return this._pausedCall?.metadata === metadata;
return !!this._pausedCall;
}
pausedDetails(): { metadata: CallMetadata, sdkObject: SdkObject } | undefined {
return this._pausedCall;
}
}
function matchesLocation(metadata: CallMetadata, location: { file: string, line?: number, column?: number }): boolean {
return !!metadata.location?.file.includes(location.file) &&
(location.line === undefined || metadata.location.line === location.line) &&
(location.column === undefined || metadata.location.column === location.column);
}