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 { eventsHelper } from '@utils/eventsHelper';
import { Browser } from '../browser';
import { BrowserContext, verifyGeolocation } from '../browserContext';
import * as network from '../network';
import { BidiConnection } from './bidiConnection';
import { bidiBytesValueToString } from './bidiNetworkManager';
import { BidiPage, kPlaywrightBindingChannel } from './bidiPage';
import { PageBinding } from '../page';
import * as bidi from './third_party/bidiProtocol';
import * as rawBidiInsertTextSource from '../../generated/bidiInsertTextSource';
import type { RegisteredListener } from '@utils/eventsHelper';
import type { BrowserOptions } from '../browser';
import type { SdkObject } from '../instrumentation';
import type { InitScript, Page } from '../page';
import type { ConnectionTransport } from '../transport';
import type * as types from '../types';
import type { HttpCredentials } from '@protocol/structs';
import type { BidiSession } from './bidiConnection';
import type * as channels from '../channels';
export type BidiBrowserOptions = {
// Authenticate against a proxy with a Proxy-Authorization header on every request,
// or by answering the proxy's auth challenge with the credentials.
proxyAuthentication: 'header' | 'credentials',
};
export class BidiBrowser extends Browser {
private readonly _connection: BidiConnection;
readonly _bidiOptions: BidiBrowserOptions;
readonly _browserSession: BidiSession;
private _bidiSessionInfo!: bidi.Session.NewResult;
readonly _contexts = new Map<string, BidiBrowserContext>();
readonly _bidiPages = new Map<bidi.BrowsingContext.BrowsingContext, BidiPage>();
private readonly _eventListeners: RegisteredListener[];
private _cacheBehavior: bidi.Network.SetCacheBehaviorParameters['cacheBehavior'] = 'default';
static async connect(parent: SdkObject, transport: ConnectionTransport, options: BrowserOptions, bidiOptions: BidiBrowserOptions): Promise<BidiBrowser> {
const browser = new BidiBrowser(parent, transport, options, bidiOptions);
if ((options as any).__testHookOnConnectToBrowser)
await (options as any).__testHookOnConnectToBrowser();
browser._bidiSessionInfo = await browser._browserSession.send('session.new', {
capabilities: {
alwaysMatch: {
'acceptInsecureCerts': options.persistent?.internalIgnoreHTTPSErrors || options.persistent?.ignoreHTTPSErrors,
'proxy': getProxyConfiguration(options.originalLaunchOptions.proxyOverride ?? options.proxy),
'unhandledPromptBehavior': {
default: bidi.Session.UserPromptHandlerType.Ignore,
},
'webSocketUrl': true,
// Chrome with WebDriver BiDi does not support prerendering
// yet because WebDriver BiDi behavior is not specified. See
// https://github.com/w3c/webdriver-bidi/issues/321.
'goog:prerenderingDisabled': true,
},
}
});
await browser._browserSession.send('session.subscribe', {
events: [
'browsingContext',
'network',
'log',
'script',
'input',
],
});
await browser._browserSession.send('network.addIntercept', { phases: [bidi.Network.InterceptPhase.AuthRequired] });
await browser._browserSession.send('network.addDataCollector', {
dataTypes: [bidi.Network.DataType.Response],
maxEncodedDataSize: 20_000_000, // same default as in CDP: https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/inspector/inspector_network_agent.cc;l=134;drc=4128411589187a396829a827f59a655bed876aa7
});
if (options.persistent) {
const context = new BidiBrowserContext(browser, undefined, options.persistent);
browser._defaultContext = context;
await context.initialize();
// Create default page as we cannot get access to the existing one.
const page = await browser._defaultContext.doCreateNewPage();
await page.waitForInitializedOrError();
}
return browser;
}
constructor(parent: SdkObject, transport: ConnectionTransport, options: BrowserOptions, bidiOptions: BidiBrowserOptions) {
super(parent, options);
this._bidiOptions = bidiOptions;
this._connection = new BidiConnection(transport, this._onDisconnect.bind(this), options.protocolLogger, options.browserLogsCollector);
this._browserSession = this._connection.browserSession;
this._eventListeners = [
eventsHelper.addEventListener(this._browserSession, 'browsingContext.contextCreated', this._onBrowsingContextCreated.bind(this)),
eventsHelper.addEventListener(this._browserSession, 'script.realmDestroyed', this._onScriptRealmDestroyed.bind(this)),
];
}
_onDisconnect() {
this.didClose();
}
async doCreateNewContext(options: types.BrowserContextOptions): Promise<BrowserContext> {
const proxy = options.proxyOverride || options.proxy;
const { userContext } = await this._browserSession.send('browser.createUserContext', {
acceptInsecureCerts: options.internalIgnoreHTTPSErrors || options.ignoreHTTPSErrors,
proxy: getProxyConfiguration(proxy),
});
const context = new BidiBrowserContext(this, userContext, options);
await context.initialize();
this._contexts.set(userContext, context);
return context;
}
contexts(): BrowserContext[] {
return Array.from(this._contexts.values());
}
version(): string {
return this._bidiSessionInfo.capabilities.browserVersion;
}
userAgent(): string {
return this._bidiSessionInfo.capabilities.userAgent;
}
isConnected(): boolean {
return !this._connection.isClosed();
}
async updateCacheBehavior() {
const cacheBehavior = [...this._contexts.values()].some(context => context.requestInterceptors.length > 0) ? 'bypass' : 'default';
if (this._cacheBehavior !== cacheBehavior) {
await this._browserSession.send('network.setCacheBehavior', { cacheBehavior });
this._cacheBehavior = cacheBehavior;
}
}
private _onBrowsingContextCreated(event: bidi.BrowsingContext.Info) {
if (event.parent) {
const parentFrameId = event.parent;
const page = this._findPageForFrame(parentFrameId);
if (page) {
page._session.addFrameBrowsingContext(event.context);
const frame = page._page.frameManager.frameAttached(event.context, parentFrameId);
frame._url = event.url;
page._getFrameNode(frame).then(node => {
const attributes = node?.value?.attributes;
frame._name = attributes?.name ?? attributes?.id ?? '';
}, () => {});
return;
}
return;
}
let context = this._contexts.get(event.userContext);
if (!context)
context = this._defaultContext as BidiBrowserContext;
if (!context)
return;
context.doGrantGlobalPermissionsForURL(event.url);
const session = this._connection.createMainFrameBrowsingContextSession(event.context);
const opener = event.originalOpener && this._findPageForFrame(event.originalOpener);
const page = new BidiPage(context, session, opener || null);
page._page.mainFrame()._url = event.url;
this._bidiPages.set(event.context, page);
}
_onBrowsingContextDestroyed(event: bidi.BrowsingContext.Info) {
if (event.parent) {
this._browserSession.removeFrameBrowsingContext(event.context);
const parentFrameId = event.parent;
for (const page of this._bidiPages.values()) {
const parentFrame = page._page.frameManager.frame(parentFrameId);
if (!parentFrame)
continue;
page._page.frameManager.frameDetached(event.context);
return;
}
return;
}
const bidiPage = this._bidiPages.get(event.context);
if (!bidiPage)
return;
bidiPage.didClose();
this._bidiPages.delete(event.context);
}
private _onScriptRealmDestroyed(event: bidi.Script.RealmDestroyedParameters) {
for (const page of this._bidiPages.values()) {
if (page._onRealmDestroyed(event))
return;
}
}
private _findPageForFrame(frameId: string) {
for (const page of this._bidiPages.values()) {
if (page._page.frameManager.frame(frameId))
return page;
}
}
}
export class BidiBrowserContext extends BrowserContext {
declare readonly _browser: BidiBrowser;
private _originToPermissions = new Map<string, string[]>();
private _initScriptIds = new Map<InitScript, string>();
private _interceptId: bidi.Network.Intercept | undefined;
constructor(browser: BidiBrowser, browserContextId: string | undefined, options: types.BrowserContextOptions) {
super(browser, options, browserContextId);
if (browser._bidiOptions.proxyAuthentication === 'header')
this.authenticateProxyViaHeader();
}
private _bidiPages() {
return [...this._browser._bidiPages.values()].filter(bidiPage => bidiPage._browserContext === this);
}
override async initialize() {
const promises: Promise<any>[] = [
super.initialize(),
];
promises.push(this.extendInjectedScript(rawBidiInsertTextSource.source));
const downloadBehavior: bidi.Browser.DownloadBehavior = this._options.acceptDownloads === 'accept' ?
{ type: 'allowed', destinationFolder: this._browser.options.downloadsPath } :
{ type: 'denied' };
promises.push(this._browser._browserSession.send('browser.setDownloadBehavior', {
downloadBehavior,
userContexts: [this._userContextId()],
}));
promises.push(this.doUpdateDefaultViewport());
if (this._options.geolocation)
promises.push(this.setGeolocation(this._options.geolocation));
if (this._options.locale) {
promises.push(this._browser._browserSession.send('emulation.setLocaleOverride', {
locale: this._options.locale,
userContexts: [this._userContextId()],
}));
}
if (this._options.timezoneId) {
promises.push(this._browser._browserSession.send('emulation.setTimezoneOverride', {
timezone: this._options.timezoneId,
userContexts: [this._userContextId()],
}));
}
if (this._options.userAgent) {
promises.push(this._browser._browserSession.send('emulation.setUserAgentOverride', {
userAgent: this._options.userAgent,
userContexts: [this._userContextId()],
}));
}
if (this._options.extraHTTPHeaders)
promises.push(this.doUpdateExtraHTTPHeaders());
if (this._options.permissions)
promises.push(this.doGrantPermissions('*', this._options.permissions));
if (this._options.offline)
promises.push(this.doUpdateOffline());
await Promise.all(promises);
}
override possiblyUninitializedPages(): Page[] {
return this._bidiPages().map(bidiPage => bidiPage._page);
}
override async doCreateNewPage(): Promise<Page> {
const { context } = await this._browser._browserSession.send('browsingContext.create', {
type: bidi.BrowsingContext.CreateType.Window,
userContext: this._browserContextId,
});
const page = this._browser._bidiPages.get(context)!._page;
page.frameManager.frameLifecycleEvent(context, 'domcontentloaded');
page.frameManager.frameLifecycleEvent(context, 'load');
return page;
}
async doGetCookies(urls: string[]): Promise<channels.NetworkCookie[]> {
const { cookies } = await this._browser._browserSession.send('storage.getCookies',
{ partition: { type: 'storageKey', userContext: this._browserContextId } });
return network.filterCookies(cookies.map((c: bidi.Network.Cookie) => {
const copy: channels.NetworkCookie = {
name: c.name,
value: bidiBytesValueToString(c.value),
domain: c.domain,
path: c.path,
httpOnly: c.httpOnly,
secure: c.secure,
expires: c.expiry ?? -1,
sameSite: c.sameSite ? fromBidiSameSite(c.sameSite) : 'None',
};
return copy;
}), urls);
}
async addCookies(cookies: channels.SetNetworkCookie[]) {
cookies = network.rewriteCookies(cookies);
const promises = cookies.map(async (c: channels.SetNetworkCookie) => {
const cookie: bidi.Storage.PartialCookie = {
name: c.name,
value: { type: 'string', value: c.value },
domain: c.domain!,
path: c.path,
httpOnly: c.httpOnly,
secure: c.secure,
sameSite: c.sameSite && toBidiSameSite(c.sameSite),
expiry: (c.expires === -1 || c.expires === undefined) ? undefined : Math.round(c.expires),
};
try {
return await this._browser._browserSession.send('storage.setCookie',
{ cookie, partition: { type: 'storageKey', userContext: this._browserContextId, sourceOrigin: c.partitionKey } });
} catch (e) {
if (!e.message.startsWith('Protocol error (storage.setCookie): unable to set cookie'))
throw e;
}
});
await Promise.all(promises);
}
async doClearCookies() {
await this._browser._browserSession.send('storage.deleteCookies',
{ partition: { type: 'storageKey', userContext: this._browserContextId } });
}
async doGrantPermissions(origin: string, permissions: string[]) {
if (origin === 'null')
return;
const protocolPermissions = permissions.flatMap(
permission => permission === 'local-network-access' ? ['local-network', 'loopback-network'] : permission
);
const currentPermissions = this._originToPermissions.get(origin) || [];
const toGrant = protocolPermissions.filter(permission => !currentPermissions.includes(permission));
this._originToPermissions.set(origin, [...currentPermissions, ...toGrant]);
if (origin === '*') {
await Promise.all(this._bidiPages().flatMap(page =>
page._page.frames().map(frame =>
this.doGrantPermissions(new URL(frame._url).origin, permissions)
)
));
} else {
await Promise.all(toGrant.map(permission => this._setPermission(origin, permission, bidi.Permissions.PermissionState.Granted)));
}
}
async doGrantGlobalPermissionsForURL(url: string) {
const permissions = this._originToPermissions.get('*');
if (!permissions)
return;
await this.doGrantPermissions(new URL(url).origin, permissions);
}
async doClearPermissions() {
const currentPermissions = [...this._originToPermissions.entries()];
this._originToPermissions = new Map();
await Promise.all(currentPermissions.flatMap(([origin, permissions]) => {
if (origin !== '*')
return permissions.map(p => this._setPermission(origin, p, bidi.Permissions.PermissionState.Prompt));
}));
}
private async _setPermission(origin: string, permission: string, state: bidi.Permissions.PermissionState) {
await this._browser._browserSession.send('permissions.setPermission', {
descriptor: {
name: permission,
},
state,
origin,
userContext: this._userContextId(),
});
}
async setGeolocation(geolocation?: types.Geolocation): Promise<void> {
verifyGeolocation(geolocation);
this._options.geolocation = geolocation;
// Setting geolocation on the user context automatically applies it to all existing
// pages in the context in Bidi.
await this._browser._browserSession.send('emulation.setGeolocationOverride', {
coordinates: geolocation ? {
latitude: geolocation.latitude,
longitude: geolocation.longitude,
accuracy: geolocation.accuracy,
} : null,
userContexts: [this._userContextId()],
});
}
async doUpdateExtraHTTPHeaders(): Promise<void> {
const allHeaders = this._options.extraHTTPHeaders || [];
await this._browser._browserSession.send('network.setExtraHeaders', {
headers: allHeaders.map(({ name, value }) => ({ name, value: { type: 'string' as 'string', value } })),
userContexts: [this._userContextId()],
});
}
async setUserAgent(userAgent: string | undefined): Promise<void> {
this._options.userAgent = userAgent;
await this._browser._browserSession.send('emulation.setUserAgentOverride', {
userAgent: userAgent ?? null,
userContexts: [this._userContextId()],
});
}
async doUpdateOffline(): Promise<void> {
await this._browser._browserSession.send('emulation.setNetworkConditions', {
networkConditions: this._options.offline ? { type: 'offline' } : null,
userContexts: [this._userContextId()],
});
}
async doSetHTTPCredentials(httpCredentials?: HttpCredentials[]): Promise<void> {
this._options.httpCredentials = httpCredentials;
for (const page of this.pages())
await (page.delegate as BidiPage).updateHttpCredentials();
}
async doAddInitScript(initScript: InitScript) {
const { script } = await this._browser._browserSession.send('script.addPreloadScript', {
// TODO: remove function call from the source.
functionDeclaration: `() => { return ${initScript.source} }`,
userContexts: [this._userContextId()],
});
this._initScriptIds.set(initScript, script);
}
async doRemoveInitScripts(initScripts: InitScript[]) {
const ids: string[] = [];
for (const script of initScripts) {
const id = this._initScriptIds.get(script);
if (id)
ids.push(id);
this._initScriptIds.delete(script);
}
await Promise.all(ids.map(script => this._browser._browserSession.send('script.removePreloadScript', { script })));
}
async doUpdateRequestInterception(): Promise<void> {
let interceptPromise = Promise.resolve<any>(undefined);
if (this.requestInterceptors.length > 0 && !this._interceptId) {
interceptPromise = this._browser._browserSession.send('network.addIntercept', {
phases: [bidi.Network.InterceptPhase.BeforeRequestSent],
}).then(({ intercept }) => this._interceptId = intercept);
}
if (this.requestInterceptors.length === 0 && this._interceptId) {
const intercept = this._interceptId;
this._interceptId = undefined;
interceptPromise = this._browser._browserSession.send('network.removeIntercept', { intercept });
}
await Promise.all([this._browser.updateCacheBehavior(), interceptPromise]);
}
override async doUpdateDefaultViewport() {
if (!this._options.viewport && !this._options.screen)
return;
const screenSize = (this._options.screen || this._options.viewport)!;
const viewportSize = (this._options.viewport || this._options.screen)!;
await Promise.all([
this._browser._browserSession.send('browsingContext.setViewport', {
viewport: {
width: viewportSize.width,
height: viewportSize.height
},
devicePixelRatio: this._options.deviceScaleFactor || 1,
userContexts: [this._userContextId()],
}),
this._browser._browserSession.send('emulation.setScreenOrientationOverride', {
screenOrientation: getScreenOrientation(!!this._options.isMobile, screenSize),
userContexts: [this._userContextId()],
}),
this._browser._browserSession.send('emulation.setScreenSettingsOverride', {
screenArea: {
width: screenSize.width,
height: screenSize.height,
},
userContexts: [this._userContextId()],
})
]);
}
override async doUpdateDefaultEmulatedMedia() {
}
override async doExposePlaywrightBinding() {
const args: bidi.Script.ChannelValue[] = [{
type: 'channel',
value: {
channel: kPlaywrightBindingChannel,
ownership: bidi.Script.ResultOwnership.Root,
}
}];
const functionDeclaration = `function addMainBinding(callback) { globalThis['${PageBinding.kBindingName}'] = callback; }`;
const promises = [];
promises.push(this._browser._browserSession.send('script.addPreloadScript', {
functionDeclaration,
arguments: args,
userContexts: [this._userContextId()],
}));
promises.push(...this._bidiPages().map(page => {
const realms = [...page._contextIdToContext].filter(([realm, context]) => context.world === 'main').map(([realm, context]) => realm);
return Promise.all(realms.map(realm => {
return page._session.send('script.callFunction', {
functionDeclaration,
arguments: args,
target: { realm },
awaitPromise: false,
userActivation: false,
});
}));
}));
await Promise.all(promises);
}
override async clearCache(): Promise<void> {
}
async doClose(reason: string | undefined): Promise<void | 'close-browser'> {
if (!this._browserContextId) {
// Closing persistent context should close the browser.
return 'close-browser';
}
await this._browser._browserSession.send('browser.removeUserContext', {
userContext: this._browserContextId
});
await Promise.all(this._bidiPages().map(bidiPage => bidiPage._page.closedPromise));
this._browser._contexts.delete(this._browserContextId);
}
async cancelDownload(uuid: string) {
}
private _userContextId(): bidi.Browser.UserContext {
if (this._browserContextId)
return this._browserContextId;
// Default context always has same id, see
// https://w3c.github.io/webdriver-bidi/#default-user-context
return 'default';
}
}
function fromBidiSameSite(sameSite: bidi.Network.SameSite): channels.NetworkCookie['sameSite'] {
switch (sameSite) {
case 'strict': return 'Strict';
case 'lax': return 'Lax';
case 'none': return 'None';
case 'default': return 'Lax';
}
return 'None';
}
function toBidiSameSite(sameSite: channels.SetNetworkCookie['sameSite']): bidi.Network.SameSite {
switch (sameSite) {
case 'Strict': return bidi.Network.SameSite.Strict;
case 'Lax': return bidi.Network.SameSite.Lax;
case 'None': return bidi.Network.SameSite.None;
}
return bidi.Network.SameSite.None;
}
function getProxyConfiguration(proxySettings?: types.ProxySettings): bidi.Session.ManualProxyConfiguration | undefined {
if (!proxySettings)
return undefined;
const proxy: bidi.Session.ManualProxyConfiguration = {
proxyType: 'manual',
};
const url = new URL(proxySettings.server); // Validate proxy server.
switch (url.protocol) {
case 'http:':
proxy.httpProxy = url.host;
break;
case 'https:':
proxy.sslProxy = url.host;
break;
case 'socks4:':
proxy.socksProxy = url.host;
proxy.socksVersion = 4;
break;
case 'socks5:':
proxy.socksProxy = url.host;
proxy.socksVersion = 5;
break;
default:
throw new Error('Invalid proxy server protocol: ' + proxySettings.server);
}
const bypass = proxySettings.bypass ?? process.env.PLAYWRIGHT_PROXY_BYPASS_FOR_TESTING;
if (bypass)
proxy.noProxy = bypass.split(',');
return proxy;
}
export function getScreenOrientation(isMobile: boolean, viewportSize: types.Size) {
const screenOrientation: bidi.Emulation.ScreenOrientation = {
type: 'landscape-primary',
natural: bidi.Emulation.ScreenOrientationNatural.Landscape
};
if (isMobile) {
screenOrientation.natural = bidi.Emulation.ScreenOrientationNatural.Portrait;
if (viewportSize.width <= viewportSize.height)
screenOrientation.type = 'portrait-primary';
}
return screenOrientation;
}
export namespace Network {
export const enum SameSite {
Strict = 'strict',
Lax = 'lax',
None = 'none',
}
}