/** * Copyright 2023 Google Inc. All rights reserved. * * 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 {Protocol} from 'devtools-protocol'; import {Frame} from '../api/Frame.js'; import {getQueryHandlerAndSelector} from '../common/GetQueryHandler.js'; import {WaitForSelectorOptions} from '../common/IsolatedWorld.js'; import {LazyArg} from '../common/LazyArg.js'; import { ElementFor, EvaluateFuncWith, HandleFor, HandleOr, NodeFor, } from '../common/types.js'; import {KeyInput} from '../common/USKeyboardLayout.js'; import { debugError, isString, withSourcePuppeteerURLIfNone, } from '../common/util.js'; import {assert} from '../util/assert.js'; import {AsyncIterableUtil} from '../util/AsyncIterableUtil.js'; import { KeyboardTypeOptions, KeyPressOptions, MouseClickOptions, } from './Input.js'; import {JSHandle} from './JSHandle.js'; import {ScreenshotOptions} 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; } /** * @public */ export interface Point { x: number; y: number; } /** * ElementHandle represents an in-page DOM element. * * @remarks * ElementHandles can be created with the {@link Page.$} method. * * ```ts * import puppeteer from 'puppeteer'; * * (async () => { * 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 origin frame gets navigated. * * 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. */ async uploadFile( this: ElementHandle, ...paths: string[] ): Promise; async uploadFile(this: ElementHandle): Promise { throw new Error('Not implemented'); } /** * 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. */ async tap(this: ElementHandle): Promise { await this.scrollIntoViewIfNeeded(); const {x, y} = await this.clickablePoint(); await this.frame.page().touchscreen.touchStart(x, y); await this.frame.page().touchscreen.touchEnd(); } async touchStart(this: ElementHandle): Promise { await this.scrollIntoViewIfNeeded(); const {x, y} = await this.clickablePoint(); await this.frame.page().touchscreen.touchStart(x, y); } async touchMove(this: ElementHandle): Promise { await this.scrollIntoViewIfNeeded(); const {x, y} = await this.clickablePoint(); await this.frame.page().touchscreen.touchMove(x, y); } 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. */ 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. */ 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. */ async press( key: KeyInput, options?: Readonly ): Promise { await this.focus(); await this.frame.page().keyboard.press(key, options); } async #clickableBox(): Promise { const adoptedThis = await this.frame.isolatedRealm().adoptHandle(this); const boxes = await adoptedThis.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}; }); }); void adoptedThis.dispose().catch(debugError); if (!boxes?.length) { return null; } await this.#intersectBoundingBoxesWithFrame(boxes); let frame: Frame | null | undefined = this.frame; let element: HandleFor | null | undefined; while ((element = await frame?.frameElement())) { try { element = await element.frame.isolatedRealm().transferHandle(element); const parentBox = await element.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 element.#intersectBoundingBoxesWithFrame(boxes); frame = frame?.parentFrame(); } finally { void element.dispose().catch(debugError); } } 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 not visible. */ async boundingBox(): Promise { const adoptedThis = await this.frame.isolatedRealm().adoptHandle(this); const box = await adoptedThis.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}; }); void adoptedThis.dispose().catch(debugError); 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 not visible. * * @remarks * * Boxes are represented as an array of points; * Each Point is an object `{x, y}`. Box points are sorted clock-wise. */ async boxModel(): Promise { const adoptedThis = await this.frame.isolatedRealm().adoptHandle(this); const model = await adoptedThis.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.bottom}, {x: rect.left, y: rect.top + rect.bottom}, ]; 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, }, ]; } }); void adoptedThis.dispose().catch(debugError); 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: Frame | null | undefined = this.frame; let element: HandleFor | null | undefined; while ((element = await frame?.frameElement())) { try { element = await element.frame.isolatedRealm().transferHandle(element); const parentBox = await element.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 = frame?.parentFrame(); } finally { void element.dispose().catch(debugError); } } return point; } /** * This method scrolls element into view if needed, and then uses * {@link Page.(screenshot:3) } to take a screenshot of the element. * If the element is detached from DOM, the method throws an error. */ async screenshot( this: ElementHandle, options?: ScreenshotOptions ): Promise; async screenshot(this: ElementHandle): Promise { throw new Error('Not implemented'); } /** * @internal */ protected async assertConnectedElement(): Promise { const error = await this.evaluate( async (element): Promise => { 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. */ async isIntersectingViewport( this: ElementHandle, options?: { threshold?: number; } ): Promise { await this.assertConnectedElement(); const {threshold = 0} = options ?? {}; const svgHandle = await this.#asSVGElementHandle(this); const intersectionTarget: ElementHandle = svgHandle ? await this.#getOwnerSVGElement(svgHandle) : this; try { return await intersectionTarget.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; }, threshold); } finally { if (intersectionTarget !== this) { await intersectionTarget.dispose(); } } } /** * Scrolls the element into view using either the automation protocol client * or by calling element.scrollIntoView. */ async scrollIntoView(this: ElementHandle): Promise { await this.assertConnectedElement(); await this.evaluate(async (element): Promise => { element.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant', }); }); } /** * Returns true if an element is an SVGElement (included svg, path, rect * etc.). */ async #asSVGElementHandle( handle: ElementHandle ): Promise | null> { if ( await handle.evaluate(element => { return element instanceof SVGElement; }) ) { return handle as ElementHandle; } else { return null; } } async #getOwnerSVGElement( handle: ElementHandle ): Promise> { // SVGSVGElement.ownerSVGElement === null. return await handle.evaluateHandle(element => { if (element instanceof SVGSVGElement) { return element; } return element.ownerSVGElement!; }); } /** * @internal */ abstract assertElementHasWorld(): asserts this; /** * 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; } /** * @public */ export interface AutofillData { creditCard: { // See https://chromedevtools.github.io/devtools-protocol/tot/Autofill/#type-CreditCard. number: string; name: string; expiryMonth: string; expiryYear: string; cvc: string; }; } 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 ); }