/** * @license * Copyright 2023 Google Inc. * SPDX-License-Identifier: Apache-2.0 */ import type {Protocol} from 'devtools-protocol'; import type {Frame} from '../api/Frame.js'; import {getQueryHandlerAndSelector} from '../common/GetQueryHandler.js'; import {LazyArg} from '../common/LazyArg.js'; import type { AwaitableIterable, ElementFor, EvaluateFuncWith, HandleFor, HandleOr, NodeFor, } from '../common/types.js'; import type {KeyInput} from '../common/USKeyboardLayout.js'; import {isString, withSourcePuppeteerURLIfNone} from '../common/util.js'; import {assert} from '../util/assert.js'; import {AsyncIterableUtil} from '../util/AsyncIterableUtil.js'; import {throwIfDisposed} from '../util/decorators.js'; import {_isElementHandle} from './ElementHandleSymbol.js'; import type { KeyboardTypeOptions, KeyPressOptions, MouseClickOptions, TouchHandle, } from './Input.js'; import {JSHandle} from './JSHandle.js'; import type {Locator} from './locators/locators.js'; import {NodeLocator} from './locators/locators.js'; import type { QueryOptions, ScreenshotOptions, WaitForSelectorOptions, } from './Page.js'; /** * @public */ export type Quad = [Point, Point, Point, Point]; /** * @public */ export interface BoxModel { content: Quad; padding: Quad; border: Quad; margin: Quad; width: number; height: number; } /** * @public */ export interface BoundingBox extends Point { /** * the width of the element in pixels. */ width: number; /** * the height of the element in pixels. */ height: number; } /** * @public */ export interface Offset { /** * x-offset for the clickable point relative to the top-left corner of the border box. */ x: number; /** * y-offset for the clickable point relative to the top-left corner of the border box. */ y: number; } /** * @public */ export interface ClickOptions extends MouseClickOptions { /** * Offset for the clickable point relative to the top-left corner of the border box. */ offset?: Offset; /** * An experimental debugging feature. If true, inserts an element into the * page to highlight the click location for 10 seconds. Might not work on all * pages and does not persist across navigations. * * @experimental */ debugHighlight?: boolean; } /** * @public */ export interface Point { x: number; y: number; } /** * @public */ export interface ElementScreenshotOptions extends ScreenshotOptions { /** * @defaultValue `true` */ scrollIntoView?: boolean; } /** * A given method will have it's `this` replaced with an isolated version of * `this` when decorated with this decorator. * * All changes of isolated `this` are reflected on the actual `this`. * * @internal */ export function bindIsolatedHandle>( target: (this: This, ...args: any[]) => Promise, _: unknown, ): typeof target { return async function (...args) { // If the handle is already isolated, then we don't need to adopt it // again. if (this.realm === this.frame.isolatedRealm()) { return await target.call(this, ...args); } let adoptedThis: This; if (this['isolatedHandle']) { adoptedThis = this['isolatedHandle']; } else { this['isolatedHandle'] = adoptedThis = await this.frame .isolatedRealm() .adoptHandle(this); } const result = await target.call(adoptedThis, ...args); // If the function returns `adoptedThis`, then we return `this`. if (result === adoptedThis) { return this; } // If the function returns a handle, transfer it into the current realm. if (result instanceof JSHandle) { return await this.realm.transferHandle(result); } // If the function returns an array of handlers, transfer them into the // current realm. if (Array.isArray(result)) { await Promise.all( result.map(async (item, index, result) => { if (item instanceof JSHandle) { result[index] = await this.realm.transferHandle(item); } }), ); } if (result instanceof Map) { await Promise.all( [...result.entries()].map(async ([key, value]) => { if (value instanceof JSHandle) { result.set(key, await this.realm.transferHandle(value)); } }), ); } return result; }; } /** * ElementHandle represents an in-page DOM element. * * @remarks * ElementHandles can be created with the {@link Page.$} method. * * ```ts * import puppeteer from 'puppeteer'; * * const browser = await puppeteer.launch(); * const page = await browser.newPage(); * await page.goto('https://example.com'); * const hrefElement = await page.$('a'); * await hrefElement.click(); * // ... * ``` * * ElementHandle prevents the DOM element from being garbage-collected unless the * handle is {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed * when their associated frame is navigated away or the parent * context gets destroyed. * * ElementHandle instances can be used as arguments in {@link Page.$eval} and * {@link Page.evaluate} methods. * * If you're using TypeScript, ElementHandle takes a generic argument that * denotes the type of element the handle is holding within. For example, if you * have a handle to a `` element matching `selector`, the method * throws an error. * * @example * * ```ts * handle.select('blue'); // single selection * handle.select('red', 'green', 'blue'); // multiple selections * ``` * * @param values - Values of options to select. If the ` element.'); } const selectedValues = new Set(); if (!element.multiple) { for (const option of element.options) { option.selected = false; } for (const option of element.options) { if (values.has(option.value)) { option.selected = true; selectedValues.add(option.value); break; } } } else { for (const option of element.options) { option.selected = values.has(option.value); if (option.selected) { selectedValues.add(option.value); } } } element.dispatchEvent(new Event('input', {bubbles: true})); element.dispatchEvent(new Event('change', {bubbles: true})); return [...selectedValues.values()]; }, values); } /** * Sets the value of an * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input | input element} * to the given file paths. * * @remarks This will not validate whether the file paths exists. Also, if a * path is relative, then it is resolved against the * {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}. * For locals script connecting to remote chrome environments, paths must be * absolute. */ abstract uploadFile( this: ElementHandle, ...paths: string[] ): Promise; /** * @internal */ abstract queryAXTree( name?: string, role?: string, ): AwaitableIterable>; /** * This method scrolls element into view if needed, and then uses * {@link Touchscreen.tap} to tap in the center of the element. * If the element is detached from DOM, the method throws an error. */ @throwIfDisposed() @bindIsolatedHandle async tap(this: ElementHandle): Promise { await this.scrollIntoViewIfNeeded(); const {x, y} = await this.clickablePoint(); await this.frame.page().touchscreen.tap(x, y); } /** * This method scrolls the element into view if needed, and then * starts a touch in the center of the element. * @returns A {@link TouchHandle} representing the touch that was started */ @throwIfDisposed() @bindIsolatedHandle async touchStart(this: ElementHandle): Promise { await this.scrollIntoViewIfNeeded(); const {x, y} = await this.clickablePoint(); return await this.frame.page().touchscreen.touchStart(x, y); } /** * This method scrolls the element into view if needed, and then * moves the touch to the center of the element. * @param touch - An optional {@link TouchHandle}. If provided, this touch * will be moved. If not provided, the first active touch will be moved. */ @throwIfDisposed() @bindIsolatedHandle async touchMove( this: ElementHandle, touch?: TouchHandle, ): Promise { await this.scrollIntoViewIfNeeded(); const {x, y} = await this.clickablePoint(); if (touch) { return await touch.move(x, y); } await this.frame.page().touchscreen.touchMove(x, y); } @throwIfDisposed() @bindIsolatedHandle async touchEnd(this: ElementHandle): Promise { await this.scrollIntoViewIfNeeded(); await this.frame.page().touchscreen.touchEnd(); } /** * Calls {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus | focus} on the element. */ @throwIfDisposed() @bindIsolatedHandle async focus(): Promise { await this.evaluate(element => { if (!(element instanceof HTMLElement)) { throw new Error('Cannot focus non-HTMLElement'); } return element.focus(); }); } /** * Focuses the element, and then sends a `keydown`, `keypress`/`input`, and * `keyup` event for each character in the text. * * To press a special key, like `Control` or `ArrowDown`, * use {@link ElementHandle.press}. * * @example * * ```ts * await elementHandle.type('Hello'); // Types instantly * await elementHandle.type('World', {delay: 100}); // Types slower, like a user * ``` * * @example * An example of typing into a text field and then submitting the form: * * ```ts * const elementHandle = await page.$('input'); * await elementHandle.type('some text'); * await elementHandle.press('Enter'); * ``` * * @param options - Delay in milliseconds. Defaults to 0. */ @throwIfDisposed() @bindIsolatedHandle async type( text: string, options?: Readonly, ): Promise { await this.focus(); await this.frame.page().keyboard.type(text, options); } /** * Focuses the element, and then uses {@link Keyboard.down} and {@link Keyboard.up}. * * @remarks * If `key` is a single character and no modifier keys besides `Shift` * are being held down, a `keypress`/`input` event will also be generated. * The `text` option can be specified to force an input event to be generated. * * **NOTE** Modifier keys DO affect `elementHandle.press`. Holding down `Shift` * will type the text in upper case. * * @param key - Name of key to press, such as `ArrowLeft`. * See {@link KeyInput} for a list of all key names. */ @throwIfDisposed() @bindIsolatedHandle async press( key: KeyInput, options?: Readonly, ): Promise { await this.focus(); await this.frame.page().keyboard.press(key, options); } async #clickableBox(): Promise { const boxes = await this.evaluate(element => { if (!(element instanceof Element)) { return null; } return [...element.getClientRects()].map(rect => { return {x: rect.x, y: rect.y, width: rect.width, height: rect.height}; }); }); if (!boxes?.length) { return null; } await this.#intersectBoundingBoxesWithFrame(boxes); let frame = this.frame; let parentFrame: Frame | null | undefined; while ((parentFrame = frame?.parentFrame())) { using handle = await frame.frameElement(); if (!handle) { throw new Error('Unsupported frame type'); } const parentBox = await handle.evaluate(element => { // Element is not visible. if (element.getClientRects().length === 0) { return null; } const rect = element.getBoundingClientRect(); const style = window.getComputedStyle(element); return { left: rect.left + parseInt(style.paddingLeft, 10) + parseInt(style.borderLeftWidth, 10), top: rect.top + parseInt(style.paddingTop, 10) + parseInt(style.borderTopWidth, 10), }; }); if (!parentBox) { return null; } for (const box of boxes) { box.x += parentBox.left; box.y += parentBox.top; } await handle.#intersectBoundingBoxesWithFrame(boxes); frame = parentFrame; } const box = boxes.find(box => { return box.width >= 1 && box.height >= 1; }); if (!box) { return null; } return { x: box.x, y: box.y, height: box.height, width: box.width, }; } async #intersectBoundingBoxesWithFrame(boxes: BoundingBox[]) { const {documentWidth, documentHeight} = await this.frame .isolatedRealm() .evaluate(() => { return { documentWidth: document.documentElement.clientWidth, documentHeight: document.documentElement.clientHeight, }; }); for (const box of boxes) { intersectBoundingBox(box, documentWidth, documentHeight); } } /** * This method returns the bounding box of the element (relative to the main frame), * or `null` if the element is {@link https://drafts.csswg.org/css-display-4/#box-generation | not part of the layout} * (example: `display: none`). */ @throwIfDisposed() @bindIsolatedHandle async boundingBox(): Promise { const box = await this.evaluate(element => { if (!(element instanceof Element)) { return null; } // Element is not visible. if (element.getClientRects().length === 0) { return null; } const rect = element.getBoundingClientRect(); return {x: rect.x, y: rect.y, width: rect.width, height: rect.height}; }); if (!box) { return null; } const offset = await this.#getTopLeftCornerOfFrame(); if (!offset) { return null; } return { x: box.x + offset.x, y: box.y + offset.y, height: box.height, width: box.width, }; } /** * This method returns boxes of the element, * or `null` if the element is {@link https://drafts.csswg.org/css-display-4/#box-generation | not part of the layout} * (example: `display: none`). * * @remarks * * Boxes are represented as an array of points; * Each Point is an object `{x, y}`. Box points are sorted clock-wise. */ @throwIfDisposed() @bindIsolatedHandle async boxModel(): Promise { const model = await this.evaluate(element => { if (!(element instanceof Element)) { return null; } // Element is not visible. if (element.getClientRects().length === 0) { return null; } const rect = element.getBoundingClientRect(); const style = window.getComputedStyle(element); const offsets = { padding: { left: parseInt(style.paddingLeft, 10), top: parseInt(style.paddingTop, 10), right: parseInt(style.paddingRight, 10), bottom: parseInt(style.paddingBottom, 10), }, margin: { left: -parseInt(style.marginLeft, 10), top: -parseInt(style.marginTop, 10), right: -parseInt(style.marginRight, 10), bottom: -parseInt(style.marginBottom, 10), }, border: { left: parseInt(style.borderLeft, 10), top: parseInt(style.borderTop, 10), right: parseInt(style.borderRight, 10), bottom: parseInt(style.borderBottom, 10), }, }; const border: Quad = [ {x: rect.left, y: rect.top}, {x: rect.left + rect.width, y: rect.top}, {x: rect.left + rect.width, y: rect.top + rect.height}, {x: rect.left, y: rect.top + rect.height}, ]; const padding = transformQuadWithOffsets(border, offsets.border); const content = transformQuadWithOffsets(padding, offsets.padding); const margin = transformQuadWithOffsets(border, offsets.margin); return { content, padding, border, margin, width: rect.width, height: rect.height, }; function transformQuadWithOffsets( quad: Quad, offsets: {top: number; left: number; right: number; bottom: number}, ): Quad { return [ { x: quad[0].x + offsets.left, y: quad[0].y + offsets.top, }, { x: quad[1].x - offsets.right, y: quad[1].y + offsets.top, }, { x: quad[2].x - offsets.right, y: quad[2].y - offsets.bottom, }, { x: quad[3].x + offsets.left, y: quad[3].y - offsets.bottom, }, ]; } }); if (!model) { return null; } const offset = await this.#getTopLeftCornerOfFrame(); if (!offset) { return null; } for (const attribute of [ 'content', 'padding', 'border', 'margin', ] as const) { for (const point of model[attribute]) { point.x += offset.x; point.y += offset.y; } } return model; } async #getTopLeftCornerOfFrame() { const point = {x: 0, y: 0}; let frame = this.frame; let parentFrame: Frame | null | undefined; while ((parentFrame = frame?.parentFrame())) { using handle = await frame.frameElement(); if (!handle) { throw new Error('Unsupported frame type'); } const parentBox = await handle.evaluate(element => { // Element is not visible. if (element.getClientRects().length === 0) { return null; } const rect = element.getBoundingClientRect(); const style = window.getComputedStyle(element); return { left: rect.left + parseInt(style.paddingLeft, 10) + parseInt(style.borderLeftWidth, 10), top: rect.top + parseInt(style.paddingTop, 10) + parseInt(style.borderTopWidth, 10), }; }); if (!parentBox) { return null; } point.x += parentBox.left; point.y += parentBox.top; frame = parentFrame; } return point; } /** * This method scrolls element into view if needed, and then uses * {@link Page.(screenshot:2) } to take a screenshot of the element. * If the element is detached from DOM, the method throws an error. */ async screenshot( options: Readonly & {encoding: 'base64'}, ): Promise; async screenshot(options?: Readonly): Promise; @throwIfDisposed() @bindIsolatedHandle async screenshot( this: ElementHandle, options: Readonly = {}, ): Promise { const {scrollIntoView = true, clip} = options; const page = this.frame.page(); // Only scroll the element into view if the user wants it. if (scrollIntoView) { await this.scrollIntoViewIfNeeded(); } const elementClip = await this.#nonEmptyVisibleBoundingBox(); const [pageLeft, pageTop] = await this.evaluate(() => { if (!window.visualViewport) { throw new Error('window.visualViewport is not supported.'); } return [ window.visualViewport.pageLeft, window.visualViewport.pageTop, ] as const; }); elementClip.x += pageLeft; elementClip.y += pageTop; if (clip) { elementClip.x += clip.x; elementClip.y += clip.y; elementClip.height = clip.height; elementClip.width = clip.width; } return await page.screenshot({...options, clip: elementClip}); } async #nonEmptyVisibleBoundingBox() { const box = await this.boundingBox(); assert(box, 'Node is either not visible or not an HTMLElement'); assert(box.width !== 0, 'Node has 0 width.'); assert(box.height !== 0, 'Node has 0 height.'); return box; } /** * @internal */ protected async assertConnectedElement(): Promise { const error = await this.evaluate(async element => { if (!element.isConnected) { return 'Node is detached from document'; } if (element.nodeType !== Node.ELEMENT_NODE) { return 'Node is not of type HTMLElement'; } return; }); if (error) { throw new Error(error); } } /** * @internal */ protected async scrollIntoViewIfNeeded( this: ElementHandle, ): Promise { if ( await this.isIntersectingViewport({ threshold: 1, }) ) { return; } await this.scrollIntoView(); } /** * Resolves to true if the element is visible in the current viewport. If an * element is an SVG, we check if the svg owner element is in the viewport * instead. See https://crbug.com/963246. * * @param options - Threshold for the intersection between 0 (no intersection) and 1 * (full intersection). Defaults to 1. */ @throwIfDisposed() @bindIsolatedHandle async isIntersectingViewport( this: ElementHandle, options: { threshold?: number; } = {}, ): Promise { await this.assertConnectedElement(); // eslint-disable-next-line @puppeteer/use-using -- Returns `this`. const handle = await this.#asSVGElementHandle(); using target = handle && (await handle.#getOwnerSVGElement()); return await ((target ?? this) as ElementHandle).evaluate( async (element, threshold) => { const visibleRatio = await new Promise(resolve => { const observer = new IntersectionObserver(entries => { resolve(entries[0]!.intersectionRatio); observer.disconnect(); }); observer.observe(element); }); return threshold === 1 ? visibleRatio === 1 : visibleRatio > threshold; }, options.threshold ?? 0, ); } /** * Scrolls the element into view using either the automation protocol client * or by calling element.scrollIntoView. */ @throwIfDisposed() @bindIsolatedHandle async scrollIntoView(this: ElementHandle): Promise { await this.assertConnectedElement(); await this.evaluate(async (element): Promise => { element.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant', }); }); } /** * Creates a locator based on an ElementHandle. This would not allow * refreshing the element handle if it is stale but it allows re-using other * locator pre-conditions. */ @throwIfDisposed() asLocator(this: ElementHandle): Locator { return NodeLocator.createFromHandle(this.frame, this); } /** * Returns true if an element is an SVGElement (included svg, path, rect * etc.). */ async #asSVGElementHandle( this: ElementHandle, ): Promise | null> { if ( await this.evaluate(element => { return element instanceof SVGElement; }) ) { return this as ElementHandle; } else { return null; } } async #getOwnerSVGElement( this: ElementHandle, ): Promise> { // SVGSVGElement.ownerSVGElement === null. return await this.evaluateHandle(element => { if (element instanceof SVGSVGElement) { return element; } return element.ownerSVGElement!; }); } /** * If the element is a form input, you can use {@link ElementHandle.autofill} * to test if the form is compatible with the browser's autofill * implementation. Throws an error if the form cannot be autofilled. * * @remarks * * Currently, Puppeteer supports auto-filling credit card information only and * in Chrome in the new headless and headful modes only. * * ```ts * // Select an input on the credit card form. * const name = await page.waitForSelector('form #name'); * // Trigger autofill with the desired data. * await name.autofill({ * creditCard: { * number: '4444444444444444', * name: 'John Smith', * expiryMonth: '01', * expiryYear: '2030', * cvc: '123', * }, * }); * ``` */ abstract autofill(data: AutofillData): Promise; /** * When connected using Chrome DevTools Protocol, it returns a * DOM.BackendNodeId for the element. */ abstract backendNodeId(): Promise; } /** * Supported autofill address field names. * * @public */ export const enum AutofillAddressField { NameFirst = 'NAME_FIRST', NameMiddle = 'NAME_MIDDLE', NameLast = 'NAME_LAST', NameFull = 'NAME_FULL', EmailAddress = 'EMAIL_ADDRESS', PhoneHomeNumber = 'PHONE_HOME_NUMBER', PhoneHomeCityAndNumber = 'PHONE_HOME_CITY_AND_NUMBER', PhoneHomeWholeNumber = 'PHONE_HOME_WHOLE_NUMBER', AddressHomeLine1 = 'ADDRESS_HOME_LINE1', AddressHomeLine2 = 'ADDRESS_HOME_LINE2', AddressHomeStreetAddress = 'ADDRESS_HOME_STREET_ADDRESS', AddressHomeCity = 'ADDRESS_HOME_CITY', AddressHomeState = 'ADDRESS_HOME_STATE', AddressHomeZip = 'ADDRESS_HOME_ZIP', AddressHomeCountry = 'ADDRESS_HOME_COUNTRY', } /** * @public */ export type AutofillData = | { /** * See {@link https://chromedevtools.github.io/devtools-protocol/tot/Autofill/#type-CreditCard | Autofill.CreditCard}. */ creditCard: { number: string; name: string; expiryMonth: string; expiryYear: string; cvc: string; }; address?: never; } | { /** * See {@link https://chromedevtools.github.io/devtools-protocol/tot/Autofill/#type-Address | Autofill.Address}. */ address: { fields: Array<{ /** * The field type. * See {@link https://source.chromium.org/chromium/chromium/src/+/main:components/autofill/core/browser/field_types.cc} * for the full list of supported fields. */ name: AutofillAddressField | (string & Record); value: string; }>; }; creditCard?: never; }; function intersectBoundingBox( box: BoundingBox, width: number, height: number, ): void { box.width = Math.max( box.x >= 0 ? Math.min(width - box.x, box.width) : Math.min(width, box.width + box.x), 0, ); box.height = Math.max( box.y >= 0 ? Math.min(height - box.y, box.height) : Math.min(height, box.height + box.y), 0, ); box.x = Math.max(box.x, 0); box.y = Math.max(box.y, 0); }