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 { isRegExp, isString } from '@isomorphic/rtti';
import { Artifact } from './artifact';
import { ChannelOwner, apiCall, internal } from './channelOwner';
import { DisposableStub } from './disposable';
import { kNoTimeout } from './timeoutSettings';
import type { Page } from './page';
import type * as api from '../../types/types';
import type * as channels from './channels';
export class Tracing extends ChannelOwner<channels.TracingChannel> implements api.Tracing {
private _includeSources = false;
private _additionalSources = new Set<string>();
private _isLive = false;
_tracesDir: string | undefined;
private _stacksId: string | undefined;
private _isTracing = false;
private _harId: string | undefined;
private _harRecorders = new Map<string, { path: string, resourcesDir?: string }>();
static from(channel: channels.TracingChannel): Tracing {
return (channel as any)._object;
}
constructor(parent: ChannelOwner, type: string, guid: string, initializer: channels.TracingInitializer) {
super(parent, type, guid, initializer);
}
@apiCall()
async start(options: { name?: string, title?: string, snapshots?: boolean | { dom?: boolean, aria?: boolean, screen?: boolean }, screenshots?: boolean, _coverage?: boolean, sources?: boolean, live?: boolean } = {}) {
this._includeSources = !!options.sources;
this._isLive = !!options.live;
const snapshots = typeof options.snapshots === 'object' ? options.snapshots : { dom: options.snapshots };
await this._channel.tracingStart({
name: options.name,
snapshotDom: snapshots.dom,
snapshotAria: snapshots.aria,
snapshotScreen: snapshots.screen,
screencast: options.screenshots,
coverage: options._coverage,
live: options.live,
}, kNoTimeout);
const { traceName } = await this._channel.tracingStartChunk({ name: options.name, title: options.title }, kNoTimeout);
await this._startCollectingStacks(traceName, this._isLive);
return new DisposableStub(() => this.stop());
}
@apiCall()
async startChunk(options: { name?: string, title?: string } = {}) {
const { traceName } = await this._channel.tracingStartChunk(options, kNoTimeout);
await this._startCollectingStacks(traceName, this._isLive);
return new DisposableStub(() => this.stopChunk());
}
async group(name: string, options: { location?: { file: string, line?: number, column?: number } } = {}) {
if (options.location)
this._additionalSources.add(options.location.file);
await this._channel.tracingGroup({ name, location: options.location }, kNoTimeout);
return new DisposableStub(() => this.groupEnd());
}
async groupEnd() {
await this._channel.tracingGroupEnd({}, kNoTimeout);
}
private async _startCollectingStacks(traceName: string, live: boolean) {
if (!this._isTracing) {
this._isTracing = true;
this._connection.setIsTracing(true);
}
const result = await this._connection.localUtils()?.tracingStarted({ tracesDir: this._tracesDir, traceName, live });
this._stacksId = result?.stacksId;
}
@apiCall()
async stopChunk(options: { path?: string } = {}) {
await this._doStopChunk(options.path);
}
@apiCall()
async stop(options: { path?: string } = {}) {
const error = await this._doStopChunk(options.path).catch(e => e);
await this._channel.tracingStop({}, kNoTimeout);
if (error)
throw error;
}
@apiCall()
async startHar(path: string, options: { content?: 'embed' | 'attach' | 'omit', mode?: 'full' | 'minimal', urlFilter?: string | RegExp, resourcesDir?: string } = {}) {
if (this._harId)
throw new Error('HAR recording has already been started');
if (options.resourcesDir && /\.zip$/i.test(path))
throw new Error('resourcesDir option is not compatible with a .zip har file');
const defaultContent = /\.zip$/i.test(path) ? 'attach' : 'embed';
this._harId = await this._recordIntoHAR(path, null, {
url: options.urlFilter,
updateContent: options.content ?? defaultContent,
updateMode: options.mode ?? 'full',
resourcesDir: options.resourcesDir,
});
return new DisposableStub(() => this.stopHar());
}
@apiCall()
async stopHar() {
const harId = this._harId;
if (!harId)
throw new Error('HAR recording has not been started');
this._harId = undefined;
await this._exportHAR(harId);
}
async _recordIntoHAR(har: string, page: Page | null, options: { url?: string | RegExp, updateContent?: 'attach' | 'embed' | 'omit', updateMode?: 'minimal' | 'full', resourcesDir?: string } = {}): Promise<string> {
const isZip = /\.zip$/i.test(har);
const { harId } = await this._channel.harStart({
page: page?._channel,
options: {
content: options.updateContent ?? 'attach',
urlGlob: isString(options.url) ? options.url : undefined,
urlRegexSource: isRegExp(options.url) ? options.url.source : undefined,
urlRegexFlags: isRegExp(options.url) ? options.url.flags : undefined,
mode: options.updateMode ?? 'minimal',
harPath: isZip ? undefined : har,
resourcesDir: options.resourcesDir,
},
}, kNoTimeout);
this._harRecorders.set(harId, { path: har, resourcesDir: options.resourcesDir });
return harId;
}
async _exportHAR(harId: string): Promise<void> {
const harParams = this._harRecorders.get(harId);
if (!harParams)
return;
this._harRecorders.delete(harId);
const isLocal = !this._connection.isRemote();
const isZip = /\.zip$/i.test(harParams.path);
if (isLocal) {
const { entries } = await this._channel.harExport({ harId, mode: 'entries' }, kNoTimeout);
if (!isZip) {
// Server wrote HAR and resources to the user's chosen paths.
return;
}
const localUtils = this._connection.localUtils();
if (!localUtils)
throw new Error('Cannot save zipped HAR in thin clients');
await localUtils.zip({ zipFile: harParams.path, entries: entries!, mode: 'write', includeSources: false, additionalSources: [] });
return;
}
const { artifact: artifactChannel } = await this._channel.harExport({ harId, mode: 'archive' }, kNoTimeout);
const artifact = Artifact.from(artifactChannel!);
if (isZip) {
await artifact.saveAs(harParams.path);
await artifact.delete();
return;
}
const localUtils = this._connection.localUtils();
if (!localUtils)
throw new Error('Uncompressed har is not supported in thin clients');
await artifact.saveAs(harParams.path + '.tmp');
await localUtils.harUnzip({ zipFile: harParams.path + '.tmp', harFile: harParams.path, resourcesDir: harParams.resourcesDir });
await artifact.delete();
}
@internal
async _exportAllHars(): Promise<void> {
await Promise.all([...this._harRecorders.keys()].map(harId => this._exportHAR(harId)));
}
private async _doStopChunk(filePath: string | undefined) {
this._resetStackCounter();
const additionalSources = [...this._additionalSources];
this._additionalSources.clear();
const stacksId = this._stacksId;
this._stacksId = undefined;
try {
await this._saveChunk(filePath, stacksId, additionalSources);
} catch (error) {
// Release the stack session even on failure, otherwise later traces keep appending to it.
if (stacksId)
await this._connection.localUtils()?.traceDiscarded({ stacksId }).catch(() => {});
throw error;
}
}
private async _saveChunk(filePath: string | undefined, stacksId: string | undefined, additionalSources: string[]) {
if (!filePath) {
// Not interested in artifacts.
await this._channel.tracingStopChunk({ mode: 'discard' }, kNoTimeout);
if (stacksId)
await this._connection.localUtils()!.traceDiscarded({ stacksId });
return;
}
const localUtils = this._connection.localUtils();
if (!localUtils)
throw new Error('Cannot save trace in thin clients');
const isLocal = !this._connection.isRemote();
if (isLocal) {
const result = await this._channel.tracingStopChunk({ mode: 'entries' }, kNoTimeout);
await localUtils.zip({ zipFile: filePath, entries: result.entries!, mode: 'write', stacksId, includeSources: this._includeSources, additionalSources });
return;
}
const result = await this._channel.tracingStopChunk({ mode: 'archive' }, kNoTimeout);
// The artifact may be missing if the browser closed while stopping tracing.
if (!result.artifact) {
if (stacksId)
await localUtils.traceDiscarded({ stacksId });
return;
}
// Save trace to the final local file.
const artifact = Artifact.from(result.artifact);
try {
await artifact.saveAs(filePath);
} catch (error) {
// Delete the artifact best-effort, the save error is the one to surface.
await artifact.delete().catch(() => {});
throw error;
}
await artifact.delete();
await localUtils.zip({ zipFile: filePath, entries: [], mode: 'append', stacksId, includeSources: this._includeSources, additionalSources });
}
_resetStackCounter() {
if (this._isTracing) {
this._isTracing = false;
this._connection.setIsTracing(false);
}
}
}