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 fs from 'fs';
import path from 'path';
import mime from 'mime';
import { isUnderTest } from '@utils/debug';
import * as js from './javascript';
import { prepareFilesForUpload } from './fileUploadUtils';
import * as rawInjectedScriptSource from '../generated/injectedScriptSource';
import type * as frames from './frames';
import type { ElementState, HitTargetInterceptionResult, InjectedScript, InjectedScriptOptions } from '@injected/injectedScript';
import type { Page } from './page';
import type { Progress } from './progress';
import type { ScreenshotOptions } from './screenshotter';
import type * as types from './types';
import type * as channels from './channels';
export type InputFilesItems = {
filePayloads?: types.FilePayload[],
localPaths?: string[]
localDirectory?: string
};
type ActionName = 'click' | 'hover' | 'dblclick' | 'tap' | 'move and up' | 'move and down' | 'drop';
type PerformActionResult = 'error:notvisible' | 'error:notconnected' | 'error:notinviewport' | 'error:optionsnotfound' | 'error:optionnotenabled' | { missingState: ElementState } | { hitTargetDescription: string } | 'done';
type PointerAction = {
name: ActionName,
waitForEnabled: boolean,
// true: wait for navigations triggered by the action.
// false: noWaitAfter was passed, do not wait and do not stall on hit target cleanup.
// 'disabled': this action never waits for navigations.
waitAfter: boolean | 'disabled',
skipActionPreChecks?: boolean,
perform: (progress: Progress, point: types.Point) => Promise<void>,
};
export class NonRecoverableDOMError extends Error {
}
export function isNonRecoverableDOMError(error: Error) {
return error instanceof NonRecoverableDOMError;
}
export class FrameExecutionContext extends js.ExecutionContext {
readonly frame: frames.Frame;
private _injectedScriptPromise?: Promise<js.JSHandle>;
readonly world: types.World | null;
constructor(delegate: js.ExecutionContextDelegate, frame: frames.Frame, world: types.World|null) {
super(frame, delegate, world || 'content-script', { noUtilityWorld: frame._page.delegate.noUtilityWorld?.() });
this.frame = frame;
this.world = world;
}
override adoptIfNeeded(handle: js.JSHandle): Promise<js.JSHandle> | null {
if (handle instanceof ElementHandle && handle._context !== this)
return this.frame._page.delegate.adoptElementHandle(handle, this);
return null;
}
async evaluate<Arg, R>(pageFunction: js.Func1<Arg, R>, arg?: Arg): Promise<R> {
return js.evaluate(this, true /* returnByValue */, pageFunction, arg);
}
async evaluateHandle<Arg, R>(pageFunction: js.Func1<Arg, R>, arg?: Arg): Promise<js.SmartHandle<R>> {
return js.evaluate(this, false /* returnByValue */, pageFunction, arg);
}
async evaluateExpression(expression: string, options: { isFunction?: boolean }, arg?: any): Promise<any> {
return js.evaluateExpression(this, expression, { ...options, returnByValue: true }, arg);
}
async evaluateExpressionHandle(expression: string, options: { isFunction?: boolean }, arg?: any): Promise<js.JSHandle<any>> {
return js.evaluateExpression(this, expression, { ...options, returnByValue: false }, arg);
}
injectedScript(): Promise<js.JSHandle<InjectedScript>> {
if (!this._injectedScriptPromise) {
const customEngines: InjectedScriptOptions['customEngines'] = [];
const selectorsRegistry = this.frame._page.browserContext.selectors();
for (const [name, { source }] of selectorsRegistry._engines)
customEngines.push({ name, source: `(${source})` });
const sdkLanguage = this.frame._page.browserContext._browser.sdkLanguage();
const options: InjectedScriptOptions = {
isUnderTest: isUnderTest(),
sdkLanguage,
frameSeq: this.frame.seq,
testIdAttributeName: selectorsRegistry.testIdAttributeName(),
stableRafCount: this.frame._page.delegate.rafCountForStablePosition(),
browserName: this.frame._page.browserContext._browser.options.name,
shouldPrependErrorPrefix: this.delegate.shouldPrependErrorPrefix(),
isUtilityWorld: this.world === 'utility',
customEngines,
skipInertCheck: !!process.env.PLAYWRIGHT_SKIP_INERT_CHECK,
skipDialogCheck: !!process.env.PLAYWRIGHT_SKIP_DIALOG_CHECK,
};
const globalsSnapshot = this.frame._page.delegate.noUtilityWorld?.() ? js.mainWorldGlobalsSnapshotSource : '';
const source = `
(() => {
${globalsSnapshot}
const module = {};
${rawInjectedScriptSource.source}
return new (module.exports.InjectedScript())(globalThis, ${JSON.stringify(options)});
})();
`;
this._injectedScriptPromise = this.rawEvaluateHandle(source)
.then(handle => {
handle._setPreview('InjectedScript');
return handle;
});
}
return this._injectedScriptPromise;
}
}
export class ElementHandle<T extends Node = Node> extends js.JSHandle<T> {
__elementhandle: T = true as any;
declare readonly _context: FrameExecutionContext;
readonly _page: Page;
declare readonly _objectId: string;
readonly _frame: frames.Frame;
constructor(context: FrameExecutionContext, objectId: string) {
super(context, 'node', undefined, objectId);
this._page = context.frame._page;
this._frame = context.frame;
this._initializePreview().catch(e => {});
}
async _initializePreview() {
const utility = await this._context.injectedScript();
this._setPreview(await utility.evaluate((injected, e) => 'JSHandle@' + injected.previewNode(e), this));
}
override asElement(): ElementHandle<T> | null {
return this;
}
async evaluateInUtility<R, Arg>(pageFunction: js.Func1<[js.JSHandle<InjectedScript>, ElementHandle<T>, Arg], R>, arg: Arg): Promise<R | 'error:notconnected'> {
try {
const utility = await this._frame.utilityContext();
return await utility.evaluate(pageFunction, [await utility.injectedScript(), this, arg]);
} catch (e) {
if (this._frame.isNonRetriableError(e))
throw e;
return 'error:notconnected';
}
}
private async _evaluateHandleInUtility<R, Arg>(pageFunction: js.Func1<[js.JSHandle<InjectedScript>, ElementHandle<T>, Arg], R>, arg: Arg): Promise<js.JSHandle<R> | 'error:notconnected'> {
try {
const utility = await this._frame.utilityContext();
return await utility.evaluateHandle(pageFunction, [await utility.injectedScript(), this, arg]);
} catch (e) {
if (this._frame.isNonRetriableError(e))
throw e;
return 'error:notconnected';
}
}
async ownerFrame(progress: Progress): Promise<frames.Frame | null> {
return await progress.race(this._ownerFrame());
}
private async _ownerFrame(): Promise<frames.Frame | null> {
const frameId = await this._page.delegate.getOwnerFrame(this);
if (!frameId)
return null;
const frame = this._page.frameManager.frame(frameId);
if (frame)
return frame;
for (const page of this._page.browserContext.pages()) {
const frame = page.frameManager.frame(frameId);
if (frame)
return frame;
}
return null;
}
private async _isIframeElement(): Promise<boolean | 'error:notconnected'> {
return this.evaluateInUtility(([injected, node]) => node && (node.nodeName === 'IFRAME' || node.nodeName === 'FRAME'), {});
}
async contentFrame(progress: Progress): Promise<frames.Frame | null> {
return progress.race(this._contentFrame());
}
private async _contentFrame(): Promise<frames.Frame | null> {
const isFrameElement = throwRetargetableDOMError(await this._isIframeElement());
if (!isFrameElement)
return null;
return this._page.delegate.getContentFrame(this);
}
async getAttribute(progress: Progress, name: string): Promise<string | null> {
return this._frame.getAttribute(progress, { selector: ':scope', scope: this }, name);
}
async inputValue(progress: Progress): Promise<string> {
return this._frame.inputValue(progress, { selector: ':scope', scope: this });
}
async textContent(progress: Progress): Promise<string | null> {
return this._frame.textContent(progress, { selector: ':scope', scope: this });
}
async innerText(progress: Progress): Promise<string> {
return this._frame.innerText(progress, { selector: ':scope', scope: this });
}
async innerHTML(progress: Progress): Promise<string> {
return this._frame.innerHTML(progress, { selector: ':scope', scope: this });
}
async dispatchEvent(progress: Progress, type: string, eventInit: Object = {}) {
return this._frame.dispatchEvent(progress, { selector: ':scope', scope: this }, type, eventInit);
}
async _scrollRectIntoViewIfNeeded(progress: Progress, rect?: types.Rect): Promise<'error:notvisible' | 'error:notconnected' | 'done'> {
return await progress.race(this._page.delegate.scrollRectIntoViewIfNeeded(this, rect));
}
async _waitAndScrollIntoViewIfNeeded(progress: Progress, waitForVisible: boolean, frameVisible: boolean): Promise<void> {
const result = await this._retryAction(progress, 'scroll into view', async progress => {
progress.log(` waiting for element to be stable`);
const waitResult = await progress.race(this.evaluateInUtility(async ([injected, node, { waitForVisible, frameVisible }]) => {
return await injected.checkElementStates(node, waitForVisible ? ['visible', 'stable'] : ['stable'], frameVisible);
}, { waitForVisible, frameVisible }));
if (waitResult)
return waitResult;
return await this._scrollRectIntoViewIfNeeded(progress);
}, {});
assertDone(throwRetargetableDOMError(result));
}
async scrollIntoViewIfNeeded(progress: Progress) {
await this._waitAndScrollIntoViewIfNeeded(progress, false /* waitForVisible */, true /* frameVisible */);
}
private async _clickablePoint(progress: Progress): Promise<{ point: types.Point, box: types.Rect } | 'error:notvisible' | 'error:notinviewport' | 'error:notconnected'> {
const intersectQuadWithViewport = (quad: types.Quad): types.Quad => {
return quad.map(point => ({
x: Math.min(Math.max(point.x, 0), metrics.width),
y: Math.min(Math.max(point.y, 0), metrics.height),
})) as types.Quad;
};
const computeQuadArea = (quad: types.Quad) => {
// Compute sum of all directed areas of adjacent triangles
// https://en.wikipedia.org/wiki/Polygon#Simple_polygons
let area = 0;
for (let i = 0; i < quad.length; ++i) {
const p1 = quad[i];
const p2 = quad[(i + 1) % quad.length];
area += (p1.x * p2.y - p2.x * p1.y) / 2;
}
return Math.abs(area);
};
const [quads, metrics] = await progress.race(Promise.all([
this._page.delegate.getContentQuads(this),
this._page.mainFrame().utilityContext().then(utility => utility.evaluate(() => ({ width: innerWidth, height: innerHeight }))),
] as const));
if (quads === 'error:notconnected')
return quads;
if (!quads || !quads.length)
return 'error:notvisible';
// Allow 1x1 elements. Compensate for rounding errors by comparing with 0.99 instead.
const filtered = quads.map(quad => intersectQuadWithViewport(quad)).filter(quad => computeQuadArea(quad) > 0.99);
if (!filtered.length)
return 'error:notinviewport';
const quad = filtered[0];
const box = quadToRect(quad);
if (this._page.browserContext._browser.options.name === 'firefox') {
// Firefox internally uses integer coordinates, so 8.x is converted to 8 or 9 when clicking.
//
// This does not work nicely for small elements. For example, 1x1 square with corners
// (8;8) and (9;9) is targeted when clicking at (8;8) but not when clicking at (9;9).
// So, clicking at (8.x;8.y) will sometimes click at (9;9) and miss the target.
//
// Therefore, we try to find an integer point within a quad to make sure we click inside the element.
for (const q of filtered) {
const integerPoint = findIntegerPointInsideQuad(q);
if (integerPoint)
return { point: integerPoint, box };
}
}
// Return the middle point of the first quad.
return { point: quadMiddlePoint(quad), box };
}
private async _offsetPoint(progress: Progress, offset: types.Point): Promise<{ point: types.Point, box: types.Rect } | 'error:notvisible' | 'error:notconnected'> {
const [box, border] = await progress.race(Promise.all([
this.boundingBox(progress),
this.evaluateInUtility(([injected, node]) => injected.getElementBorderWidth(node), {}).catch(e => {}),
]));
if (!box || !border)
return 'error:notvisible';
if (border === 'error:notconnected')
return border;
// Make point relative to the padding box to align with offsetX/offsetY.
return {
point: {
x: box.x + border.left + offset.x,
y: box.y + border.top + offset.y,
},
box,
};
}
async _retryAction(progress: Progress, actionName: string, action: (progress: Progress, retry: number) => Promise<PerformActionResult>, options: { trial?: boolean, force?: boolean, skipActionPreChecks?: boolean }): Promise<'error:notconnected' | 'done'> {
let retry = 0;
// We progressively wait longer between retries, up to 500ms.
const waitTime = [0, 20, 100, 100, 500];
while (true) {
if (retry) {
progress.log(`retrying ${actionName} action${options.trial ? ' (trial run)' : ''}`);
const timeout = waitTime[Math.min(retry - 1, waitTime.length - 1)];
if (timeout) {
progress.log(` waiting ${timeout}ms`);
await progress.wait(timeout);
}
} else {
progress.log(`attempting ${actionName} action${options.trial ? ' (trial run)' : ''}`);
}
if (!options.skipActionPreChecks && !options.force)
await this._frame._page.performActionPreChecks(progress);
const result = await action(progress, retry);
++retry;
if (result === 'error:notvisible') {
if (options.force)
throw new NonRecoverableDOMError('Element is not visible');
progress.log(' element is not visible');
continue;
}
if (result === 'error:notinviewport') {
if (options.force)
throw new NonRecoverableDOMError('Element is outside of the viewport');
progress.log(' element is outside of the viewport');
continue;
}
if (result === 'error:optionsnotfound') {
progress.log(' did not find some options');
continue;
}
if (result === 'error:optionnotenabled') {
progress.log(' option being selected is not enabled');
continue;
}
if (typeof result === 'object' && 'hitTargetDescription' in result) {
progress.log(` ${result.hitTargetDescription} intercepts pointer events`);
continue;
}
if (typeof result === 'object' && 'missingState' in result) {
if (result.missingState === 'non-inert')
progress.log(' element is inert');
else
progress.log(` element is not ${result.missingState}`);
continue;
}
return result;
}
}
async _retryPointerAction(progress: Progress, action: PointerAction, options: types.PointerActionOptions & types.PointerActionWaitOptions, frameVisible: boolean): Promise<'error:notconnected' | 'done'> {
return await this._retryAction(progress, action.name, async (progress, retry) => {
// By default, we scroll with protocol method to reveal the action point.
// However, that might not work to scroll from under position:sticky elements
// that overlay the target element. To fight this, we cycle through different
// scroll alignments. This works in most scenarios.
const scrollOptions: (ScrollIntoViewOptions | undefined)[] = [
undefined,
{ block: 'end', inline: 'end' },
{ block: 'center', inline: 'center' },
{ block: 'start', inline: 'start' },
];
const forceScrollOptions = scrollOptions[retry % scrollOptions.length];
return await this._performPointerAction(progress, action, forceScrollOptions, options, frameVisible);
}, { trial: options.trial, force: options.force, skipActionPreChecks: action.skipActionPreChecks });
}
async _performPointerAction(
progress: Progress,
action: PointerAction,
forceScrollOptions: ScrollIntoViewOptions | undefined,
options: types.PointerActionOptions & types.PointerActionWaitOptions,
frameVisible: boolean,
): Promise<PerformActionResult> {
const { force = false, position, scroll } = options;
const doScrollIntoView = async (progress: Progress): Promise<'error:notvisible' | 'error:notconnected' | 'done'> => {
if (scroll === 'none')
return 'done';
if (forceScrollOptions) {
return await progress.race(this.evaluateInUtility(([injected, node, options]) => {
if (node.nodeType === 1 /* Node.ELEMENT_NODE */)
(node as Node as Element).scrollIntoView({ ...options, behavior: 'instant' });
return 'done' as const;
}, forceScrollOptions));
}
return await this._scrollRectIntoViewIfNeeded(progress, position ? { x: position.x, y: position.y, width: 0, height: 0 } : undefined);
};
if (this._frame.parentFrame()) {
// Best-effort scroll to make sure any iframes containing this element are scrolled
// into view and visible, so they are not throttled.
// See https://github.com/microsoft/playwright/issues/27196 for an example.
await doScrollIntoView(progress).catch(() => {});
}
if ((options as any).__testHookBeforeStable)
await progress.race((options as any).__testHookBeforeStable());
if (!force) {
const elementStates: ElementState[] = action.waitForEnabled ? ['visible', 'enabled', 'stable', 'non-inert'] : ['visible', 'stable'];
progress.log(` waiting for element to be ${action.waitForEnabled ? 'visible, enabled and stable' : 'visible and stable'}`);
const result = await progress.race(this.evaluateInUtility(async ([injected, node, { elementStates, frameVisible }]) => {
return await injected.checkElementStates(node, elementStates, frameVisible);
}, { elementStates, frameVisible }));
if (result)
return result;
progress.log(` element is ${action.waitForEnabled ? 'visible, enabled and stable' : 'visible and stable'}`);
}
if ((options as any).__testHookAfterStable)
await progress.race((options as any).__testHookAfterStable());
progress.log(' scrolling into view if needed');
const scrolled = await doScrollIntoView(progress);
if (scrolled !== 'done')
return scrolled;
progress.log(' done scrolling');
const maybeResult = position ? await this._offsetPoint(progress, position) : await this._clickablePoint(progress);
if (typeof maybeResult === 'string')
return maybeResult;
const point = roundPoint(maybeResult.point);
await this.instrumentation.onBeforeInputAction(progress, this, point, maybeResult.box);
let hitTargetInterceptionHandle: js.JSHandle<HitTargetInterceptionResult> | undefined;
if (force) {
progress.log(` forcing action`);
} else {
if ((options as any).__testHookBeforeHitTarget)
await progress.race((options as any).__testHookBeforeHitTarget());
const frameCheckResult = await this._checkFrameIsHitTarget(progress, point);
if (frameCheckResult === 'error:notconnected' || ('hitTargetDescription' in frameCheckResult))
return frameCheckResult;
const hitPoint = frameCheckResult.framePoint;
const actionType = action.name === 'move and up' ? 'drag' : ((action.name === 'hover' || action.name === 'tap') ? action.name : 'mouse');
const handle = await progress.race(this._evaluateHandleInUtility(([injected, node, { actionType, hitPoint, trial }]) => injected.setupHitTargetInterceptor(node, actionType, hitPoint, trial), { actionType, hitPoint, trial: !!options.trial } as const));
if (handle === 'error:notconnected')
return handle;
if (!handle._objectId) {
const error = handle.rawValue() as string;
if (error === 'error:notconnected')
return error;
return { hitTargetDescription: error };
}
hitTargetInterceptionHandle = handle as any;
}
const actionResult = await this._page.frameManager.waitForSignalsCreatedBy(progress, action.waitAfter === true, async progress => {
if ((options as any).__testHookBeforePointerAction)
await progress.race((options as any).__testHookBeforePointerAction());
let restoreModifiers: types.KeyboardModifier[] | undefined;
if (options && options.modifiers)
restoreModifiers = await this._page.keyboard.ensureModifiers(progress, options.modifiers);
progress.log(` performing ${action.name} action`);
await action.perform(progress, point);
if (restoreModifiers)
await this._page.keyboard.ensureModifiers(progress, restoreModifiers);
if (hitTargetInterceptionHandle) {
const stopHitTargetInterception = this._frame.raceAgainstEvaluationStallingEvents(() => {
return hitTargetInterceptionHandle.evaluate(h => h.stop());
}).catch(e => 'done' as const).finally(() => {
hitTargetInterceptionHandle?.dispose();
});
if (action.waitAfter !== false) {
// When noWaitAfter is passed, we do not want to accidentally stall on
// non-committed navigation blocking the evaluate.
const hitTargetResult = await progress.race(stopHitTargetInterception);
if (hitTargetResult !== 'done')
return hitTargetResult;
}
}
progress.log(` ${options.trial ? 'trial ' : ''}${action.name} action done`);
progress.log(' waiting for scheduled navigations to finish');
if ((options as any).__testHookAfterPointerAction)
await progress.race((options as any).__testHookAfterPointerAction());
return 'done';
}).finally(() => {
// Do not await here, just in case the renderer is stuck (e.g. on alert)
// and we won't be able to cleanup.
const stopPromise = hitTargetInterceptionHandle?.evaluate(h => h.stop()).catch(() => {});
stopPromise?.then(() => hitTargetInterceptionHandle?.dispose());
});
if (actionResult !== 'done')
return actionResult;
progress.log(' navigations have finished');
return 'done';
}
private async _markAsTargetElement(progress: Progress) {
await progress.race(this.evaluateInUtility(([injected, node]) => {
if (node.nodeType === 1 /* Node.ELEMENT_NODE */)
injected.markTargetElements(new Set([node as Node as Element]));
}, {}));
}
async hover(progress: Progress, options: types.PointerActionOptions & types.PointerActionWaitOptions): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._hover(progress, options, true /* frameVisible */);
return assertDone(throwRetargetableDOMError(result));
}
_hover(progress: Progress, options: types.PointerActionOptions & types.PointerActionWaitOptions, frameVisible: boolean): Promise<'error:notconnected' | 'done'> {
return this._retryPointerAction(progress, {
name: 'hover',
waitForEnabled: false,
waitAfter: 'disabled',
perform: (progress, point) => this._page.mouse.move(progress, point.x, point.y),
}, options, frameVisible);
}
async click(progress: Progress, options: { noWaitAfter?: boolean } & types.MouseClickOptions & types.PointerActionWaitOptions): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._click(progress, options, !options.noWaitAfter, true /* frameVisible */);
return assertDone(throwRetargetableDOMError(result));
}
_click(progress: Progress, options: types.MouseClickOptions & types.PointerActionWaitOptions, waitAfter: boolean | 'disabled', frameVisible: boolean): Promise<'error:notconnected' | 'done'> {
return this._retryPointerAction(progress, {
name: 'click',
waitForEnabled: true,
waitAfter,
perform: (progress, point) => this._page.mouse.click(progress, point.x, point.y, options),
}, options, frameVisible);
}
async dblclick(progress: Progress, options: types.MouseClickOptions & types.PointerActionWaitOptions): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._dblclick(progress, options, true /* frameVisible */);
return assertDone(throwRetargetableDOMError(result));
}
_dblclick(progress: Progress, options: types.MouseClickOptions & types.PointerActionWaitOptions, frameVisible: boolean): Promise<'error:notconnected' | 'done'> {
return this._retryPointerAction(progress, {
name: 'dblclick',
waitForEnabled: true,
waitAfter: 'disabled',
perform: (progress, point) => this._page.mouse.click(progress, point.x, point.y, { ...options, clickCount: 2 }),
}, options, frameVisible);
}
async tap(progress: Progress, options: types.PointerActionWaitOptions): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._tap(progress, options, true /* frameVisible */);
return assertDone(throwRetargetableDOMError(result));
}
_tap(progress: Progress, options: types.PointerActionWaitOptions, frameVisible: boolean): Promise<'error:notconnected' | 'done'> {
return this._retryPointerAction(progress, {
name: 'tap',
waitForEnabled: true,
waitAfter: 'disabled',
perform: (progress, point) => this._page.touchscreen.tap(progress, point.x, point.y),
}, options, frameVisible);
}
async selectOption(progress: Progress, elements: ElementHandle[], values: types.SelectOption[], options: types.CommonActionOptions): Promise<string[]> {
await this._markAsTargetElement(progress);
const result = await this._selectOption(progress, elements, values, options, true /* frameVisible */);
return throwRetargetableDOMError(result);
}
async _selectOption(progress: Progress, elements: ElementHandle[], values: types.SelectOption[], options: types.CommonActionOptions, frameVisible: boolean, box?: types.Rect): Promise<string[] | 'error:notconnected'> {
let resultingOptions: string[] = [];
const result = await this._retryAction(progress, 'select option', async progress => {
await this.instrumentation.onBeforeInputAction(progress, this, undefined, box);
if (!options.force)
progress.log(` waiting for element to be visible and enabled`);
const optionsToSelect = [...elements, ...values];
const result = await progress.race(this.evaluateInUtility(async ([injected, node, { optionsToSelect, force, frameVisible }]) => {
if (!force) {
const checkResult = await injected.checkElementStates(node, ['visible', 'enabled'], frameVisible);
if (checkResult)
return checkResult;
}
return injected.selectOptions(node, optionsToSelect);
}, { optionsToSelect, force: options.force, frameVisible }));
if (Array.isArray(result)) {
progress.log(' selected specified option(s)');
resultingOptions = result;
return 'done';
}
return result;
}, options);
if (result === 'error:notconnected')
return result;
return resultingOptions;
}
async fill(progress: Progress, value: string, options: types.CommonActionOptions): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._fill(progress, value, options, true /* frameVisible */);
assertDone(throwRetargetableDOMError(result));
}
async _fill(progress: Progress, value: string, options: types.CommonActionOptions, frameVisible: boolean, box?: types.Rect): Promise<'error:notconnected' | 'done'> {
progress.log(` fill("${value}")`);
return await this._retryAction(progress, 'fill', async progress => {
await this.instrumentation.onBeforeInputAction(progress, this, undefined, box);
if (!options.force)
progress.log(' waiting for element to be visible, enabled and editable');
const result = await progress.race(this.evaluateInUtility(async ([injected, node, { value, force, frameVisible }]) => {
if (!force) {
const checkResult = await injected.checkElementStates(node, ['visible', 'enabled', 'editable', 'non-inert'], frameVisible);
if (checkResult)
return checkResult;
}
return injected.fill(node, value);
}, { value, force: options.force, frameVisible }));
if (result === 'needsinput') {
if (value)
await this._page.keyboard.insertText(progress, value);
else
await this._page.keyboard.press(progress, 'Delete');
return 'done';
} else {
return result;
}
}, options);
}
async selectText(progress: Progress, options: types.CommonActionOptions): Promise<void> {
const result = await this._retryAction(progress, 'selectText', async progress => {
if (!options.force)
progress.log(' waiting for element to be visible');
return await progress.race(this.evaluateInUtility(async ([injected, node, { force, frameVisible }]) => {
if (!force) {
const checkResult = await injected.checkElementStates(node, ['visible'], frameVisible);
if (checkResult)
return checkResult;
}
return injected.selectText(node);
}, { force: options.force, frameVisible: true }));
}, options);
assertDone(throwRetargetableDOMError(result));
}
async setInputFiles(progress: Progress, params: Omit<channels.ElementHandleSetInputFilesParams, 'timeout'>) {
const inputFileItems = await progress.race(prepareFilesForUpload(this._frame, params));
await this._markAsTargetElement(progress);
const result = await this._setInputFiles(progress, inputFileItems);
return assertDone(throwRetargetableDOMError(result));
}
async _drop(progress: Progress, inputFileItems: InputFilesItems, data: { mimeType: string, value: string }[], options: { position?: types.Point }, frameVisible: boolean): Promise<'error:notconnected' | 'done'> {
const { filePayloads, localPaths } = inputFileItems;
let payloads: { name: string, mimeType: string, buffer: string, lastModifiedMs?: number }[];
if (localPaths && !filePayloads) {
// Co-located server/browser: read files into buffers so File objects can be
// constructed in page context.
payloads = await Promise.all(localPaths.map(async p => ({
name: path.basename(p),
mimeType: mime.getType(p) || 'application/octet-stream',
buffer: (await fs.promises.readFile(p)).toString('base64'),
lastModifiedMs: (await fs.promises.stat(p)).mtimeMs,
})));
} else {
payloads = (filePayloads ?? []).map(p => ({
name: p.name,
mimeType: p.mimeType || 'application/octet-stream',
buffer: p.buffer,
lastModifiedMs: p.lastModifiedMs,
}));
}
const perform = async (progress: Progress, point: types.Point) => {
// Firefox strips files from DataTransfer objects that cross the isolated-world
// boundary into the page's main world. Adopt the element to main context and
// construct the DataTransfer + dispatch events there.
const mainContext = await progress.race(this._frame.mainContext());
const handle = this._context === mainContext ? this : await progress.race(this._page.delegate.adoptElementHandle(this, mainContext));
const disposeHandle = handle !== this;
try {
const result = await progress.race(handle.evaluate((node: Node, { payloads, data, point }) => {
if (!node.isConnected || node.nodeType !== 1 /* ELEMENT_NODE */)
return 'error:notconnected' as const;
const element = node as Element;
const dt = new DataTransfer();
for (const p of payloads) {
const bytes = Uint8Array.from(atob(p.buffer), c => c.charCodeAt(0));
const file = new File([bytes], p.name, { type: p.mimeType, lastModified: p.lastModifiedMs });
dt.items.add(file);
}
for (const entry of data)
dt.setData(entry.mimeType, entry.value);
const makeEvent = (type: string) => new DragEvent(type, {
bubbles: true,
cancelable: true,
composed: true,
clientX: point.x,
clientY: point.y,
dataTransfer: dt,
});
element.dispatchEvent(makeEvent('dragenter'));
const over = makeEvent('dragover');
element.dispatchEvent(over);
if (!over.defaultPrevented) {
element.dispatchEvent(makeEvent('dragleave'));
return 'not-accepted' as const;
}
element.dispatchEvent(makeEvent('drop'));
return 'accepted' as const;
}, { payloads, data, point }));
if (result === 'not-accepted')
throw new NonRecoverableDOMError('Drop target did not accept the drop — its dragover handler did not call preventDefault()');
} finally {
if (disposeHandle)
handle.dispose();
}
};
return this._retryPointerAction(progress, { name: 'drop', waitForEnabled: false, waitAfter: 'disabled', perform }, options, frameVisible);
}
async _setInputFiles(progress: Progress, items: InputFilesItems, box?: types.Rect): Promise<'error:notconnected' | 'done'> {
const { filePayloads, localPaths, localDirectory } = items;
const multiple = filePayloads && filePayloads.length > 1 || localPaths && localPaths.length > 1;
const result = await progress.race(this._evaluateHandleInUtility(([injected, node, { multiple, directoryUpload }]): Element | undefined => {
const element = injected.retarget(node, 'follow-label');
if (!element)
return;
if (element.tagName !== 'INPUT')
throw injected.createStacklessError('Node is not an HTMLInputElement');
const inputElement = element as HTMLInputElement;
if (multiple && !inputElement.multiple && !inputElement.webkitdirectory)
throw injected.createStacklessError('Non-multiple file input can only accept single file');
if (directoryUpload && !inputElement.webkitdirectory)
throw injected.createStacklessError('File input does not support directories, pass individual files instead');
if (!directoryUpload && inputElement.webkitdirectory)
throw injected.createStacklessError('[webkitdirectory] input requires passing a path to a directory');
return inputElement;
}, { multiple, directoryUpload: !!localDirectory }));
if (result === 'error:notconnected' || !result.asElement())
return 'error:notconnected';
const retargeted = result.asElement() as ElementHandle<HTMLInputElement>;
await this.instrumentation.onBeforeInputAction(progress, this, undefined, box);
if (localPaths || localDirectory) {
const localPathsOrDirectory = localDirectory ? [localDirectory] : localPaths!;
await progress.race(Promise.all((localPathsOrDirectory).map(localPath => (
fs.promises.access(localPath, fs.constants.F_OK)
))));
// Browsers traverse the given directory asynchronously and we want to ensure all files are uploaded.
// Install the listener on the input itself before setting the files, so that the event is not missed.
const inputEvent = localDirectory ? await progress.race(retargeted.evaluateHandle(node => ({
promise: new Promise<void>(fulfill => node.addEventListener('input', () => fulfill(), { once: true })),
})).catch(() => undefined)) : undefined;
try {
await this._page.delegate.setInputFilePaths(progress, retargeted, localPathsOrDirectory);
if (inputEvent)
await progress.race(inputEvent.evaluate(event => event.promise).catch(() => {}));
} finally {
inputEvent?.dispose();
}
} else {
await progress.race(retargeted.evaluateInUtility(([injected, node, files]) =>
injected.setInputFiles(node, files), filePayloads!));
}
return 'done';
}
async focus(progress: Progress): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._focus(progress);
return assertDone(throwRetargetableDOMError(result));
}
async _focus(progress: Progress, resetSelectionIfNotFocused?: boolean): Promise<'error:notconnected' | 'done'> {
return await progress.race(this.evaluateInUtility(([injected, node, resetSelectionIfNotFocused]) => injected.focusNode(node, resetSelectionIfNotFocused), resetSelectionIfNotFocused));
}
async _blur(progress: Progress): Promise<'error:notconnected' | 'done'> {
return await progress.race(this.evaluateInUtility(([injected, node]) => injected.blurNode(node), {}));
}
async type(progress: Progress, text: string, options: { delay?: number }): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._type(progress, text, options);
return assertDone(throwRetargetableDOMError(result));
}
async _type(progress: Progress, text: string, options: { delay?: number }, box?: types.Rect): Promise<'error:notconnected' | 'done'> {
progress.log(`elementHandle.type("${text}")`);
await this.instrumentation.onBeforeInputAction(progress, this, undefined, box);
const result = await this._focus(progress, true /* resetSelectionIfNotFocused */);
if (result !== 'done')
return result;
await this._page.keyboard.type(progress, text, options);
return 'done';
}
async press(progress: Progress, key: string, options: { delay?: number, noWaitAfter?: boolean }): Promise<void> {
await this._markAsTargetElement(progress);
const result = await this._press(progress, key, options);
return assertDone(throwRetargetableDOMError(result));
}
async _press(progress: Progress, key: string, options: { delay?: number, noWaitAfter?: boolean }, box?: types.Rect): Promise<'error:notconnected' | 'done'> {
progress.log(`elementHandle.press("${key}")`);
await this.instrumentation.onBeforeInputAction(progress, this, undefined, box);
return this._page.frameManager.waitForSignalsCreatedBy(progress, !options.noWaitAfter, async progress => {
const result = await this._focus(progress, true /* resetSelectionIfNotFocused */);
if (result !== 'done')
return result;
await this._page.keyboard.press(progress, key, options);
return 'done';
});
}
async check(progress: Progress, options: { position?: types.Point } & types.PointerActionWaitOptions) {
const result = await this._setChecked(progress, true, options, true /* frameVisible */);
return assertDone(throwRetargetableDOMError(result));
}
async uncheck(progress: Progress, options: { position?: types.Point } & types.PointerActionWaitOptions) {
const result = await this._setChecked(progress, false, options, true /* frameVisible */);
return assertDone(throwRetargetableDOMError(result));
}
async _setChecked(progress: Progress, state: boolean, options: { position?: types.Point } & types.PointerActionWaitOptions, frameVisible: boolean): Promise<'error:notconnected' | 'done'> {
const isChecked = async (progress: Progress) => {
const result = await progress.race(this.evaluateInUtility(([injected, node]) => injected.elementState(node, 'checked'), {}));
if (result === 'error:notconnected' || result.received === 'error:notconnected')
throwElementIsNotAttached();
return { matches: result.matches, isRadio: result.isRadio };
};
await this._markAsTargetElement(progress);
const checkedState = await isChecked(progress);
if (checkedState.matches === state)
return 'done';
if (!state && checkedState.isRadio)
throw new NonRecoverableDOMError('Cannot uncheck radio button. Radio buttons can only be unchecked by selecting another radio button in the same group.');
const result = await this._click(progress, options, 'disabled', frameVisible);
if (result !== 'done')
return result;
if (options.trial)
return 'done';
const finalState = await isChecked(progress);
if (finalState.matches !== state)
throw new NonRecoverableDOMError('Clicking the checkbox did not change its state');
return 'done';
}
async boundingBox(progress: Progress): Promise<types.Rect | null> {
return await progress.race(this._page.delegate.getBoundingBox(this));
}
async screenshot(progress: Progress, options: ScreenshotOptions): Promise<Buffer> {
return await this._page.screenshotter.screenshotElement(progress, this, options, true /* frameVisible */);
}
async querySelector(progress: Progress, target: types.SelectorTarget): Promise<ElementHandle | null> {
return progress.race(this._frame.selectors.query({ ...target, scope: this }));
}
async querySelectorAll(progress: Progress, selector: string): Promise<ElementHandle<Element>[]> {
return progress.race(this._querySelectorAll(selector));
}
private async _querySelectorAll(selector: string): Promise<ElementHandle<Element>[]> {
return this._frame.selectors.queryAll(selector, this);
}
async evalOnSelector(progress: Progress, target: types.SelectorTarget, expression: string, isFunction: boolean | undefined, arg: any): Promise<any> {
return this._frame.evalOnSelector(progress, { ...target, scope: this }, expression, isFunction, arg);
}
async evalOnSelectorAll(progress: Progress, selector: string, expression: string, isFunction: boolean | undefined, arg: any): Promise<any> {
return this._frame.evalOnSelectorAll(progress, selector, expression, isFunction, arg, this);
}
async isVisible(progress: Progress): Promise<boolean> {
return this._frame.isVisible(progress, { selector: ':scope', scope: this });
}
async isHidden(progress: Progress): Promise<boolean> {
return this._frame.isHidden(progress, { selector: ':scope', scope: this });
}
async isEnabled(progress: Progress): Promise<boolean> {
return this._frame.isEnabled(progress, { selector: ':scope', scope: this });
}
async isDisabled(progress: Progress): Promise<boolean> {
return this._frame.isDisabled(progress, { selector: ':scope', scope: this });
}
async isEditable(progress: Progress): Promise<boolean> {
return this._frame.isEditable(progress, { selector: ':scope', scope: this });
}
async isChecked(progress: Progress): Promise<boolean> {
return this._frame.isChecked(progress, { selector: ':scope', scope: this });
}
async waitForElementState(progress: Progress, state: 'visible' | 'hidden' | 'stable' | 'enabled' | 'disabled' | 'editable'): Promise<void> {
const actionName = `wait for ${state}`;
const result = await this._retryAction(progress, actionName, async progress => {
return await progress.race(this.evaluateInUtility(async ([injected, node, state]) => {
return (await injected.checkElementStates(node, [state], true /* frameVisible */)) || 'done';
}, state));
}, {});
assertDone(throwRetargetableDOMError(result));
}
async waitForSelector(progress: Progress, target: types.SelectorTarget, options: types.WaitForElementOptions): Promise<ElementHandle<Element> | null> {
return await this._frame.waitForSelector(progress, { ...target, scope: this }, true, options);
}
async _adoptTo(context: FrameExecutionContext): Promise<ElementHandle<T>> {
if (this._context !== context) {
const adopted = await this._page.delegate.adoptElementHandle(this, context);
this.dispose();
return adopted;
}
return this;
}
async _checkFrameIsHitTarget(progress: Progress, point: types.Point): Promise<{ framePoint: types.Point | undefined } | 'error:notconnected' | { hitTargetDescription: string }> {
let frame = this._frame;
const data: { frame: frames.Frame, frameElement: ElementHandle<Element> | null, pointInFrame: types.Point }[] = [];
const temporaryFrameElements: ElementHandle<Element>[] = [];
try {
while (frame.parentFrame()) {
const frameElement = await frame.frameElement(progress) as ElementHandle<Element>;
temporaryFrameElements.push(frameElement);
const box = await frameElement.boundingBox(progress);
const style = await progress.race(frameElement.evaluateInUtility(([injected, iframe]) => injected.describeIFrameStyle(iframe), {}).catch(e => 'error:notconnected' as const));
if (!box || style === 'error:notconnected')
return 'error:notconnected';
if (style === 'transformed') {
// We cannot translate coordinates when iframe has any transform applied.
// The best we can do right now is to skip the hitPoint check,
// and solely rely on the event interceptor.
return { framePoint: undefined };
}
// Translate from viewport coordinates to frame coordinates.
const pointInFrame = { x: point.x - box.x - style.left, y: point.y - box.y - style.top };
data.push({ frame, frameElement, pointInFrame });
frame = frame.parentFrame()!;
}
// Add main frame.
data.push({ frame, frameElement: null, pointInFrame: point });
for (let i = data.length - 1; i > 0; i--) {
const element = data[i - 1].frameElement!;
const point = data[i].pointInFrame;
// Hit target in the parent frame should hit the child frame element.
const hitTargetResult = await progress.race(element.evaluateInUtility(([injected, element, hitPoint]) => {
return injected.expectHitTarget(hitPoint, element);
}, point));
if (hitTargetResult !== 'done')
return hitTargetResult;
}
return { framePoint: data[0].pointInFrame };
} finally {
for (const frameElement of temporaryFrameElements)
frameElement.dispose();
}
}
}
export function throwRetargetableDOMError<T>(result: T | 'error:notconnected'): T {
if (result === 'error:notconnected')
throwElementIsNotAttached();
return result;
}
export function throwElementIsNotAttached(): never {
throw new Error('Element is not attached to the DOM');
}
export function assertDone(result: 'done'): void {
// This function converts 'done' to void and ensures typescript catches unhandled errors.
}
function roundPoint(point: types.Point): types.Point {
return {
x: (point.x * 100 | 0) / 100,
y: (point.y * 100 | 0) / 100,
};
}
function quadToRect(quad: types.Quad): types.Rect {
let minX = Infinity;
let minY = Infinity;
let maxX = -Infinity;
let maxY = -Infinity;
for (const point of quad) {
minX = Math.min(minX, point.x);
minY = Math.min(minY, point.y);
maxX = Math.max(maxX, point.x);
maxY = Math.max(maxY, point.y);
}
return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
}
function quadMiddlePoint(quad: types.Quad): types.Point {
const result = { x: 0, y: 0 };
for (const point of quad) {
result.x += point.x / 4;
result.y += point.y / 4;
}
return result;
}
function triangleArea(p1: types.Point, p2: types.Point, p3: types.Point): number {
return Math.abs(p1.x * (p2.y - p3.y) + p2.x * (p3.y - p1.y) + p3.x * (p1.y - p2.y)) / 2;
}
function isPointInsideQuad(point: types.Point, quad: types.Quad): boolean {
const area1 = triangleArea(point, quad[0], quad[1]) + triangleArea(point, quad[1], quad[2]) + triangleArea(point, quad[2], quad[3]) + triangleArea(point, quad[3], quad[0]);
const area2 = triangleArea(quad[0], quad[1], quad[2]) + triangleArea(quad[1], quad[2], quad[3]);
// Check that point is inside the quad.
if (Math.abs(area1 - area2) > 0.1)
return false;
// Check that point is not on the right/bottom edge, because clicking
// there does not actually click the element.
return point.x < Math.max(quad[0].x, quad[1].x, quad[2].x, quad[3].x) &&
point.y < Math.max(quad[0].y, quad[1].y, quad[2].y, quad[3].y);
}
function findIntegerPointInsideQuad(quad: types.Quad): types.Point | undefined {
// Try all four rounding directions of the middle point.
const point = quadMiddlePoint(quad);
point.x = Math.floor(point.x);
point.y = Math.floor(point.y);
if (isPointInsideQuad(point, quad))
return point;
point.x += 1;
if (isPointInsideQuad(point, quad))
return point;
point.y += 1;
if (isPointInsideQuad(point, quad))
return point;
point.x -= 1;
if (isPointInsideQuad(point, quad))
return point;
}
export const kUnableToAdoptErrorMessage = 'Unable to adopt element handle from a different document';