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 EventEmitter from 'events';
import fs from 'fs';
import { locatorOrSelectorAsSelector } from '@isomorphic/locatorParser';
import { ManualPromise } from '@isomorphic/manualPromise';
import { isUnderTest } from '@utils/debug';
import { eventsHelper } from '@utils/eventsHelper';
import { BrowserContext } from './browserContext';
import { Debugger } from './debugger';
import { buildFullSelectorForFrame, metadataToCallLog } from './recorder/recorderUtils';
import { nullProgress, ProgressController } from './progress';
import { RecorderSignalProcessor } from './recorder/recorderSignalProcessor';
import * as rawRecorderSource from './../generated/pollingRecorderSource';
import { Frame } from './frames';
import { Page } from './page';
import { performAction } from './recorder/recorderRunner';
import type { Language } from '@isomorphic/codegen/types';
import type { CallMetadata, InstrumentationListener, SdkObject } from './instrumentation';
import type { Point } from '@isomorphic/types';
import type { AriaTemplateNode } from '@isomorphic/ariaSnapshot';
import type { Progress } from './progress';
import type * as channels from './channels';
import type * as actions from '@isomorphic/codegen/actions';
import type { CallLog, CallLogStatus, ElementInfo, Mode, OverlayState, Source, UIState } from '@recorder/recorderTypes';
import type { RegisteredListener } from '@utils/eventsHelper';
const recorderSymbol = Symbol('recorderSymbol');
type BindingSource = { frame: Frame, page: Page };
type RecorderParams = channels.BrowserContextShowRecorderParams & { recorderMode?: 'default' | 'api', hideToolbar?: boolean };
export const RecorderEvent = {
PausedStateChanged: 'pausedStateChanged',
ModeChanged: 'modeChanged',
ElementPicked: 'elementPicked',
CallLogsUpdated: 'callLogsUpdated',
UserSourcesChanged: 'userSourcesChanged',
ActionAdded: 'actionAdded',
SignalAdded: 'signalAdded',
PageNavigated: 'pageNavigated',
ContextClosed: 'contextClosed',
} as const;
export type RecorderEventMap = {
[RecorderEvent.PausedStateChanged]: [paused: boolean];
[RecorderEvent.ModeChanged]: [mode: Mode];
[RecorderEvent.ElementPicked]: [elementInfo: ElementInfo, userGesture?: boolean];
[RecorderEvent.CallLogsUpdated]: [callLogs: CallLog[]];
[RecorderEvent.UserSourcesChanged]: [sources: Source[], pausedSourceId?: string];
[RecorderEvent.ActionAdded]: [action: actions.ActionInContext];
[RecorderEvent.SignalAdded]: [signal: actions.SignalInContext];
[RecorderEvent.PageNavigated]: [url: string];
[RecorderEvent.ContextClosed]: [];
};
export class Recorder extends EventEmitter<RecorderEventMap> implements InstrumentationListener {
readonly handleSIGINT: boolean | undefined;
private _context: BrowserContext;
private _params: RecorderParams;
private _mode: Mode;
private _highlightedSelector: { selector: string, anyFrame: boolean } | undefined;
private _overlayState: OverlayState = { offsetX: 0 };
private _currentCallsMetadata = new Map<CallMetadata, SdkObject>();
private _actionPoints = new Map<string, Point>();
private _userSources = new Map<string, Source>();
private _debugger: Debugger;
private _omitCallTracking = false;
private _currentLanguage: Language = 'javascript';
private _recorderMode: 'default' | 'api';
private _signalProcessor: RecorderSignalProcessor;
private _lastDialogOrdinal = -1;
private _lastDownloadOrdinal = -1;
private _listeners: RegisteredListener[] = [];
private _enabled: boolean = false;
private _callLogs: CallLog[] = [];
private _pickLocatorPage: Page | undefined;
static forContext(context: BrowserContext, params: RecorderParams): Promise<Recorder> {
let recorderPromise = (context as any)[recorderSymbol] as Promise<Recorder>;
if (!recorderPromise) {
recorderPromise = Recorder._create(context, params);
(context as any)[recorderSymbol] = recorderPromise;
}
return recorderPromise;
}
static async existingForContext(context: BrowserContext): Promise<Recorder | undefined> {
const recorderPromise = (context as any)[recorderSymbol] as Promise<Recorder> | undefined;
return await recorderPromise;
}
private static async _create(context: BrowserContext, params: RecorderParams = {}): Promise<Recorder> {
const recorder = new Recorder(context, params);
await recorder._install();
return recorder;
}
constructor(context: BrowserContext, params: RecorderParams) {
super();
this._context = context;
this._params = params;
this._mode = params.mode || 'none';
this._recorderMode = params.recorderMode ?? 'default';
this.handleSIGINT = params.handleSIGINT;
this._signalProcessor = new RecorderSignalProcessor({
addAction: (actionInContext: actions.ActionInContext) => {
if (this._enabled)
this.emit(RecorderEvent.ActionAdded, actionInContext);
},
addSignal: (signal: actions.SignalInContext) => {
if (this._enabled)
this.emit(RecorderEvent.SignalAdded, signal);
},
});
context.on(BrowserContext.Events.BeforeClose, () => {
this._signalProcessor.flush();
this.emit(RecorderEvent.ContextClosed);
});
this._listeners.push(eventsHelper.addEventListener(process, 'exit', () => {
this.emit(RecorderEvent.ContextClosed);
}));
this._setEnabled(params.mode === 'recording');
this._omitCallTracking = !!params.omitCallTracking;
this._debugger = context.debugger();
context.instrumentation.addListener(this, context);
if (isUnderTest()) {
// Most of our tests put elements at the top left, so get out of the way.
this._overlayState.offsetX = 200;
}
}
private async _install() {
this.emit(RecorderEvent.ModeChanged, this._mode);
this.emit(RecorderEvent.PausedStateChanged, this._debugger.isPaused());
this._context.once(BrowserContext.Events.Close, () => {
eventsHelper.removeEventListeners(this._listeners);
this._context.instrumentation.removeListener(this);
this.emit(RecorderEvent.ContextClosed);
});
const controller = new ProgressController();
await controller.run(async progress => {
await this._context.exposeBinding(progress, '__pw_recorderState', async source => {
let actionPoint: Point | undefined;
const hasActiveScreenshotCommand = [...this._currentCallsMetadata.keys()].some(isScreenshotCommand);
if (!hasActiveScreenshotCommand) {
for (const [metadata, sdkObject] of this._currentCallsMetadata) {
if (source.page === sdkObject.attribution.page)
actionPoint = this._actionPoints.get(metadata.id) || actionPoint;
}
}
let mode = this._mode;
if (this._pickLocatorPage && source.page !== this._pickLocatorPage)
mode = 'none';
const uiState: UIState = {
mode,
actionPoint,
language: this._currentLanguage,
testIdAttributeName: this._testIdAttributeName(),
overlay: this._overlayState,
};
return uiState;
});
await this._context.exposeBinding(progress, '__pw_recorderElementPicked', async ({ frame }, elementInfo: ElementInfo) => {
const selector = await buildFullSelectorForFrame(progress, frame, elementInfo.selector);
this.emit(RecorderEvent.ElementPicked, { selector, ariaSnapshot: elementInfo.ariaSnapshot }, true);
});
await this._context.exposeBinding(progress, '__pw_recorderSetMode', async ({ frame }, mode: Mode) => {
if (frame.parentFrame())
return;
await this.setMode(mode);
});
await this._context.exposeBinding(progress, '__pw_recorderSetOverlayState', async ({ frame }, state: OverlayState) => {
if (frame.parentFrame())
return;
this._overlayState = state;
});
await this._context.exposeBinding(progress, '__pw_resume', () => {
this._debugger.resume();
});
this._context.on(BrowserContext.Events.Page, (page: Page) => this._onPage(page));
for (const page of this._context.pages())
this._onPage(page);
this._context.dialogManager.addDialogHandler(dialog => {
this._onDialog(dialog.page());
// Not handling the dialog, let it automatically close.
return false;
});
await this._context.exposeBinding(progress, '__pw_recorderPerformAction',
(source: BindingSource, action: actions.PerformableAction) => this._performAction(progress, source.frame, action));
await this._context.exposeBinding(progress, '__pw_recorderRecordAction',
(source: BindingSource, action: actions.Action, preconditionSelector?: string) => this._recordAction(progress, source.frame, action, preconditionSelector));
await progress.race(this._context.extendInjectedScript(rawRecorderSource.source, { recorderMode: this._recorderMode, hideToolbar: !!this._params.hideToolbar }));
});
if (this._debugger.isPaused())
this._pausedStateChanged();
this._debugger.on(Debugger.Events.PausedStateChanged, () => this._pausedStateChanged());
}
private _pausedStateChanged() {
// If we are called upon page.pause, we don't have metadatas, populate them.
const pausedDetails = this._debugger.pausedDetails();
if (pausedDetails && !this._currentCallsMetadata.has(pausedDetails.metadata))
this._onBeforeCall(pausedDetails.sdkObject, pausedDetails.metadata);
this.emit(RecorderEvent.PausedStateChanged, this._debugger.isPaused());
this._updateUserSources();
this._updateCallLog([...this._currentCallsMetadata.keys()]);
}
mode() {
return this._mode;
}
flushPendingActions() {
this._signalProcessor.flush();
}
async setMode(mode: Mode) {
if (this._mode === mode)
return;
this._updateHighlightedSelector(undefined).catch(() => {});
this._mode = mode;
this.emit(RecorderEvent.ModeChanged, this._mode);
this._setEnabled(this._isRecording());
this._debugger.setMuted(this._isRecording());
if (this._mode !== 'none' && this._mode !== 'standby') {
let pageToFocus = this._pickLocatorPage;
if (!pageToFocus && this._context.pages().length === 1)
pageToFocus = this._context.pages()[0];
pageToFocus?.bringToFront(nullProgress).catch(() => {});
}
await this._refreshOverlay();
}
async pickLocator(progress: Progress, page: Page): Promise<string> {
if (this._mode !== 'none')
await progress.race(this.setMode('none'));
const selectorPromise = new ManualPromise<string>();
let recorderChangedState = false;
const onElementPicked = (elementInfo: ElementInfo) => {
selectorPromise.resolve(elementInfo.selector);
};
const onModeChanged = () => {
if (this._mode === 'inspecting')
return;
recorderChangedState = true;
selectorPromise.reject(new Error('Locator picking was cancelled'));
};
const listeners: RegisteredListener[] = [
eventsHelper.addEventListener(this, RecorderEvent.ElementPicked, onElementPicked),
eventsHelper.addEventListener(this, RecorderEvent.ModeChanged, onModeChanged),
];
try {
const doPickLocator = async () => {
// Prevent unhandled rejection in case of cancellation during setMode
selectorPromise.catch(() => {});
this._pickLocatorPage = page;
await this.setMode('inspecting');
return await selectorPromise;
};
return await progress.race(page.openScope.race(doPickLocator()));
} finally {
eventsHelper.removeEventListeners(listeners);
this._pickLocatorPage = undefined;
if (!recorderChangedState)
await progress.race(this.setMode('none'));
}
}
url(): string | undefined {
const page = this._context.pages()[0];
return page?.mainFrame().url();
}
async setHighlightedSelector(selector: string) {
const converted = locatorOrSelectorAsSelector(this._currentLanguage, selector, this._context.selectors().testIdAttributeName());
await this._updateHighlightedSelector(converted || undefined, true /* anyFrame */);
}
async setHighlightedAriaTemplate(ariaTemplate: AriaTemplateNode) {
await this._updateHighlightedSelector('aria-template=' + JSON.stringify(ariaTemplate), true /* anyFrame */);
}
step() {
this._debugger.setPauseAt({ next: true });
this._debugger.resume();
}
async setLanguage(language: Language) {
this._currentLanguage = language;
await this._refreshOverlay();
}
resume() {
this._debugger.resume();
}
pause() {
this._debugger.setPauseAt({ next: true });
}
paused() {
return this._debugger.isPaused();
}
close() {
this._debugger.resume();
}
async hideHighlightedSelector() {
await this._updateHighlightedSelector(undefined);
}
pausedSourceId() {
const pausedDetails = this._debugger.pausedDetails();
if (pausedDetails?.metadata.location) {
const source = this._userSources.get(pausedDetails.metadata.location.file);
if (source)
return source.id;
}
}
userSources() {
return [...this._userSources.values()];
}
callLog(): CallLog[] {
return this._callLogs;
}
private async _updateHighlightedSelector(selector: string | undefined, anyFrame = false) {
const previous = this._highlightedSelector;
if (!previous && !selector)
return;
if (previous && previous.selector === selector && previous.anyFrame === anyFrame)
return;
this._highlightedSelector = selector === undefined ? undefined : { selector, anyFrame };
await Promise.all(this._context.pages().map(async page => {
if (previous)
await page.highlightController.removeHighlight(previous.selector).catch(() => {});
if (selector)
await page.highlightController.addHighlight(selector, { anyFrame }).catch(() => {});
}));
}
private async _refreshOverlay() {
await Promise.all(this._context.pages().map(
page => page.safeNonStallingEvaluateInAllFrames('window.__pw_refreshOverlay()', 'main')));
}
async onBeforeCall(progress: Progress, sdkObject: SdkObject) {
this._onBeforeCall(sdkObject, progress.metadata);
}
private _onBeforeCall(sdkObject: SdkObject, metadata: CallMetadata) {
if (this._omitCallTracking || this._isRecording())
return;
this._currentCallsMetadata.set(metadata, sdkObject);
this._updateUserSources();
this._updateCallLog([metadata]);
if (isScreenshotCommand(metadata))
this.hideHighlightedSelector();
else if (!metadata.internal && metadata.params && metadata.params.selector)
this._updateHighlightedSelector(metadata.params.selector).catch(() => {});
}
async onAfterCall(progress: Progress) {
const { metadata } = progress;
this._actionPoints.delete(metadata.id);
if (this._omitCallTracking || this._isRecording())
return;
if (!metadata.error)
this._currentCallsMetadata.delete(metadata);
this._updateUserSources();
this._updateCallLog([metadata]);
}
async onBeforeInputAction(progress: Progress, sdkObject: SdkObject, point?: Point): Promise<void> {
const { metadata } = progress;
if (point)
this._actionPoints.set(metadata.id, point);
}
private _updateUserSources() {
// Remove old decorations.
for (const source of this._userSources.values()) {
source.highlight = [];
source.revealLine = undefined;
}
// Apply new decorations.
for (const metadata of this._currentCallsMetadata.keys()) {
if (!metadata.location)
continue;
const { file, line } = metadata.location;
let source = this._userSources.get(file);
if (!source) {
source = { isRecorded: false, label: file, id: file, text: this._readSource(file), highlight: [], language: languageForFile(file) };
this._userSources.set(file, source);
}
if (line) {
const paused = this._debugger.isPaused(metadata);
source.highlight.push({ line, type: metadata.error ? 'error' : (paused ? 'paused' : 'running') });
source.revealLine = line;
}
}
this.emit(RecorderEvent.UserSourcesChanged, this.userSources(), this.pausedSourceId());
}
async onCallLog(sdkObject: SdkObject, metadata: CallMetadata, logName: string, message: string): Promise<void> {
this._updateCallLog([metadata]);
}
private _updateCallLog(metadatas: CallMetadata[]) {
if (this._isRecording())
return;
const logs: CallLog[] = [];
for (const metadata of metadatas) {
if (!metadata.method || metadata.internal)
continue;
let status: CallLogStatus = 'done';
if (this._currentCallsMetadata.has(metadata))
status = 'in-progress';
if (this._debugger.isPaused(metadata))
status = 'paused';
logs.push(metadataToCallLog(metadata, status, this._currentLanguage));
}
this._callLogs = logs;
this.emit(RecorderEvent.CallLogsUpdated, logs);
}
private _isRecording() {
return ['recording', 'assertingText', 'assertingVisibility', 'assertingValue', 'assertingSnapshot'].includes(this._mode);
}
private _readSource(fileName: string): string {
try {
return fs.readFileSync(fileName, 'utf-8');
} catch (e) {
return '// No source available';
}
}
private _setEnabled(enabled: boolean) {
if (this._enabled && !enabled)
this._signalProcessor.flush();
this._enabled = enabled;
}
private async _onPage(page: Page) {
const frame = page.mainFrame();
if (this._highlightedSelector)
page.highlightController.addHighlight(this._highlightedSelector.selector, { anyFrame: this._highlightedSelector.anyFrame }).catch(() => {});
page.on(Page.Events.Close, () => {
this._signalProcessor.addAction({
pageGuid: page.guid,
action: {
name: 'closePage',
},
signals: [],
});
this._filePrimaryURLChanged();
});
frame.on(Frame.Events.InternalNavigation, event => {
if (event.isPublic && !event.error) {
this._onFrameNavigated(frame, page);
this._filePrimaryURLChanged();
}
});
page.on(Page.Events.Download, () => this._onDownload(page));
if (page.opener()) {
this._onPopup(page.opener()!, page);
} else {
this._signalProcessor.addAction({
pageGuid: page.guid,
action: {
name: 'openPage',
url: page.mainFrame().url(),
},
signals: [],
});
}
this._filePrimaryURLChanged();
}
private _filePrimaryURLChanged() {
const page = this._context.pages()[0];
this.emit(RecorderEvent.PageNavigated, page?.mainFrame().url());
}
clear(): void {
if (this._params.mode === 'recording') {
for (const page of this._context.pages())
this._onFrameNavigated(page.mainFrame(), page);
}
}
private _testIdAttributeName(): string {
return this._params.testIdAttributeName || this._context.selectors().testIdAttributeName() || 'data-testid';
}
private async _performAction(progress: Progress, frame: Frame, action: actions.PerformableAction) {
const selector = await buildFullSelectorForFrame(progress, frame, action.selector);
await performAction(progress, frame._page.mainFrame(), { ...action, selector });
}
private async _recordAction(progress: Progress, frame: Frame, action: actions.Action, preconditionSelector?: string) {
if (preconditionSelector)
this._signalProcessor.signal(frame, { name: 'expect', selector: await buildFullSelectorForFrame(progress, frame, preconditionSelector) });
if ('selector' in action)
action.selector = await buildFullSelectorForFrame(progress, frame, action.selector);
const actionInContext: actions.ActionInContext = {
pageGuid: frame._page.guid,
action,
signals: [],
};
this._signalProcessor.addAction(actionInContext);
}
private _onFrameNavigated(frame: Frame, page: Page) {
this._signalProcessor.signal(frame, { name: 'navigation', url: frame.url() });
}
private _onPopup(page: Page, popup: Page) {
this._signalProcessor.signal(page.mainFrame(), { name: 'popup', popupPageGuid: popup.guid });
}
private _onDownload(page: Page) {
++this._lastDownloadOrdinal;
this._signalProcessor.signal(page.mainFrame(), { name: 'download', downloadAlias: this._lastDownloadOrdinal ? String(this._lastDownloadOrdinal) : '' });
}
private _onDialog(page: Page) {
++this._lastDialogOrdinal;
this._signalProcessor.signal(page.mainFrame(), { name: 'dialog', dialogAlias: this._lastDialogOrdinal ? String(this._lastDialogOrdinal) : '' });
}
}
function isScreenshotCommand(metadata: CallMetadata) {
return metadata.method.toLowerCase().includes('screenshot');
}
function languageForFile(file: string): Language {
if (file.endsWith('.py'))
return 'python';
if (file.endsWith('.java'))
return 'java';
if (file.endsWith('.cs'))
return 'csharp';
return 'javascript';
}