// Copyright (c) Microsoft Corporation. // Licensed under the MIT license. import * as frames from './frames'; import * as input from './input'; import * as js from './javascript'; import * as types from './types'; import * as injectedSource from './generated/injectedSource'; import * as cssSelectorEngineSource from './generated/cssSelectorEngineSource'; import * as xpathSelectorEngineSource from './generated/xpathSelectorEngineSource'; import { assert, helper } from './helper'; import Injected from './injected/injected'; export interface DOMWorldDelegate { keyboard: input.Keyboard; mouse: input.Mouse; frame: frames.Frame; isJavascriptEnabled(): boolean; isElement(remoteObject: any): boolean; contentFrame(handle: ElementHandle): Promise; boundingBox(handle: ElementHandle): Promise; screenshot(handle: ElementHandle, options?: any): Promise; ensurePointerActionPoint(handle: ElementHandle, relativePoint?: types.Point): Promise; setInputFiles(handle: ElementHandle, files: input.FilePayload[]): Promise; adoptElementHandle(handle: ElementHandle, to: DOMWorld): Promise; } type SelectorRoot = Element | ShadowRoot | Document; type ResolvedSelector = { root?: ElementHandle, selector: string, disposeRoot?: boolean }; type Selector = string | { root?: ElementHandle, selector: string }; export class DOMWorld { readonly context: js.ExecutionContext; readonly delegate: DOMWorldDelegate; private _injectedPromise?: Promise; constructor(context: js.ExecutionContext, delegate: DOMWorldDelegate) { this.context = context; this.delegate = delegate; } createHandle(remoteObject: any): ElementHandle | null { if (this.delegate.isElement(remoteObject)) return new ElementHandle(this.context, remoteObject); return null; } injected(): Promise { if (!this._injectedPromise) { const engineSources = [cssSelectorEngineSource.source, xpathSelectorEngineSource.source]; const source = ` new (${injectedSource.source})([ ${engineSources.join(',\n')} ]) `; this._injectedPromise = this.context.evaluateHandle(source); } return this._injectedPromise; } async adoptElementHandle(handle: ElementHandle): Promise { assert(handle.executionContext() !== this.context, 'Should not adopt to the same context'); return this.delegate.adoptElementHandle(handle, this); } private async _resolveSelector(selector: Selector): Promise { if (helper.isString(selector)) return { selector: normalizeSelector(selector) }; if (selector.root && selector.root.executionContext() !== this.context) { const root = await this.adoptElementHandle(selector.root); return { root, selector: normalizeSelector(selector.selector), disposeRoot: true }; } return { root: selector.root, selector: normalizeSelector(selector.selector) }; } async $(selector: Selector): Promise { const resolved = await this._resolveSelector(selector); const handle = await this.context.evaluateHandle( (injected: Injected, selector: string, root: SelectorRoot | undefined) => injected.querySelector(selector, root || document), await this.injected(), resolved.selector, resolved.root ); if (resolved.disposeRoot) await resolved.root.dispose(); if (!handle.asElement()) await handle.dispose(); return handle.asElement(); } async $$(selector: Selector): Promise { const resolved = await this._resolveSelector(selector); const arrayHandle = await this.context.evaluateHandle( (injected: Injected, selector: string, root: SelectorRoot | undefined) => injected.querySelectorAll(selector, root || document), await this.injected(), resolved.selector, resolved.root ); if (resolved.disposeRoot) await resolved.root.dispose(); const properties = await arrayHandle.getProperties(); await arrayHandle.dispose(); const result = []; for (const property of properties.values()) { const elementHandle = property.asElement(); if (elementHandle) result.push(elementHandle); else await property.dispose(); } return result; } $eval: types.$Eval = async (selector, pageFunction, ...args) => { const elementHandle = await this.$(selector); if (!elementHandle) throw new Error(`Error: failed to find element matching selector "${selectorToString(selector)}"`); const result = await elementHandle.evaluate(pageFunction, ...args as any); await elementHandle.dispose(); return result; } $$eval: types.$$Eval = async (selector, pageFunction, ...args) => { const resolved = await this._resolveSelector(selector); const arrayHandle = await this.context.evaluateHandle( (injected: Injected, selector: string, root: SelectorRoot | undefined) => injected.querySelectorAll(selector, root || document), await this.injected(), resolved.selector, resolved.root ); const result = await arrayHandle.evaluate(pageFunction, ...args as any); await arrayHandle.dispose(); return result; } } export class ElementHandle extends js.JSHandle { private readonly _world: DOMWorld; constructor(context: js.ExecutionContext, remoteObject: any) { super(context, remoteObject); assert(context._domWorld, 'Element handle should have a dom world'); this._world = context._domWorld; } asElement(): ElementHandle | null { return this; } async contentFrame(): Promise { return this._world.delegate.contentFrame(this); } async _scrollIntoViewIfNeeded() { const error = await this.evaluate(async (element, pageJavascriptEnabled) => { if (!element.isConnected) return 'Node is detached from document'; if (element.nodeType !== Node.ELEMENT_NODE) return 'Node is not of type HTMLElement'; // force-scroll if page's javascript is disabled. if (!pageJavascriptEnabled) { element.scrollIntoView({block: 'center', inline: 'center', behavior: 'instant'}); return false; } const visibleRatio = await new Promise(resolve => { const observer = new IntersectionObserver(entries => { resolve(entries[0].intersectionRatio); observer.disconnect(); }); observer.observe(element); // Firefox doesn't call IntersectionObserver callback unless // there are rafs. requestAnimationFrame(() => {}); }); if (visibleRatio !== 1.0) element.scrollIntoView({block: 'center', inline: 'center', behavior: 'instant'}); return false; }, this._world.delegate.isJavascriptEnabled()); if (error) throw new Error(error); } async _performPointerAction(action: (point: types.Point) => Promise, options?: input.PointerActionOptions): Promise { const point = await this._world.delegate.ensurePointerActionPoint(this, options ? options.relativePoint : undefined); let restoreModifiers: input.Modifier[] | undefined; if (options && options.modifiers) restoreModifiers = await this._world.delegate.keyboard._ensureModifiers(options.modifiers); await action(point); if (restoreModifiers) await this._world.delegate.keyboard._ensureModifiers(restoreModifiers); } hover(options?: input.PointerActionOptions): Promise { return this._performPointerAction(point => this._world.delegate.mouse.move(point.x, point.y), options); } click(options?: input.ClickOptions): Promise { return this._performPointerAction(point => this._world.delegate.mouse.click(point.x, point.y, options), options); } dblclick(options?: input.MultiClickOptions): Promise { return this._performPointerAction(point => this._world.delegate.mouse.dblclick(point.x, point.y, options), options); } tripleclick(options?: input.MultiClickOptions): Promise { return this._performPointerAction(point => this._world.delegate.mouse.tripleclick(point.x, point.y, options), options); } async select(...values: (string | ElementHandle | input.SelectOption)[]): Promise { const options = values.map(value => typeof value === 'object' ? value : { value }); for (const option of options) { if (option instanceof ElementHandle) continue; if (option.value !== undefined) assert(helper.isString(option.value), 'Values must be strings. Found value "' + option.value + '" of type "' + (typeof option.value) + '"'); if (option.label !== undefined) assert(helper.isString(option.label), 'Labels must be strings. Found label "' + option.label + '" of type "' + (typeof option.label) + '"'); if (option.index !== undefined) assert(helper.isNumber(option.index), 'Indices must be numbers. Found index "' + option.index + '" of type "' + (typeof option.index) + '"'); } return this.evaluate(input.selectFunction, ...options); } async fill(value: string): Promise { assert(helper.isString(value), 'Value must be string. Found value "' + value + '" of type "' + (typeof value) + '"'); const error = await this.evaluate(input.fillFunction); if (error) throw new Error(error); await this.focus(); await this._world.delegate.keyboard.sendCharacters(value); } async setInputFiles(...files: (string|input.FilePayload)[]) { const multiple = await this.evaluate((element: HTMLInputElement) => !!element.multiple); assert(multiple || files.length <= 1, 'Non-multiple file input can only accept single file!'); await this._world.delegate.setInputFiles(this, await input.loadFiles(files)); } async focus() { await this.evaluate(element => element.focus()); } async type(text: string, options: { delay: (number | undefined); } | undefined) { await this.focus(); await this._world.delegate.keyboard.type(text, options); } async press(key: string, options: { delay?: number; text?: string; } | undefined) { await this.focus(); await this._world.delegate.keyboard.press(key, options); } async boundingBox(): Promise { return this._world.delegate.boundingBox(this); } async screenshot(options: any = {}): Promise { return this._world.delegate.screenshot(this, options); } $(selector: string): Promise { return this._world.$({ root: this, selector }); } $$(selector: string): Promise { return this._world.$$({ root: this, selector }); } $eval: types.$Eval = (selector, pageFunction, ...args) => { return this._world.$eval({ root: this, selector }, pageFunction, ...args as any); } $$eval: types.$$Eval = (selector, pageFunction, ...args) => { return this._world.$$eval({ root: this, selector }, pageFunction, ...args as any); } $x(expression: string): Promise { return this._world.$$({ root: this, selector: 'xpath=' + expression }); } isIntersectingViewport(): Promise { return this.evaluate(async element => { const visibleRatio = await new Promise(resolve => { const observer = new IntersectionObserver(entries => { resolve(entries[0].intersectionRatio); observer.disconnect(); }); observer.observe(element); // Firefox doesn't call IntersectionObserver callback unless // there are rafs. requestAnimationFrame(() => {}); }); return visibleRatio > 0; }); } } function normalizeSelector(selector: string): string { const eqIndex = selector.indexOf('='); if (eqIndex !== -1 && selector.substring(0, eqIndex).trim().match(/^[a-zA-Z_0-9]+$/)) return selector; if (selector.startsWith('//')) return 'xpath=' + selector; return 'css=' + selector; } function selectorToString(selector: Selector): string { if (typeof selector === 'string') return selector; return `:scope >> ${selector.selector}`; } export type Task = (domWorld: DOMWorld) => Promise; export type Polling = 'raf' | 'mutation' | number; export type WaitForFunctionOptions = { polling?: Polling, timeout?: number }; export function waitForFunctionTask(pageFunction: Function | string, options: WaitForFunctionOptions, ...args: any[]) { const { polling = 'raf' } = options; if (helper.isString(polling)) assert(polling === 'raf' || polling === 'mutation', 'Unknown polling option: ' + polling); else if (helper.isNumber(polling)) assert(polling > 0, 'Cannot poll with non-positive interval: ' + polling); else throw new Error('Unknown polling options: ' + polling); const predicateBody = helper.isString(pageFunction) ? 'return (' + pageFunction + ')' : 'return (' + pageFunction + ')(...args)'; return async (domWorld: DOMWorld) => domWorld.context.evaluateHandle((injected: Injected, predicateBody: string, polling: Polling, timeout: number, ...args) => { const predicate = new Function('...args', predicateBody); if (polling === 'raf') return injected.pollRaf(predicate, timeout, ...args); if (polling === 'mutation') return injected.pollMutation(predicate, timeout, ...args); return injected.pollInterval(polling, predicate, timeout, ...args); }, await domWorld.injected(), predicateBody, polling, options.timeout, ...args); } export type WaitForSelectorOptions = { visible?: boolean, hidden?: boolean, timeout?: number }; export function waitForSelectorTask(selector: string, options: WaitForSelectorOptions): Task { const { visible: waitForVisible = false, hidden: waitForHidden = false } = options; selector = normalizeSelector(selector); return async (domWorld: DOMWorld) => domWorld.context.evaluateHandle((injected: Injected, selector: string, waitForVisible: boolean, waitForHidden: boolean, timeout: number) => { if (waitForVisible || waitForHidden) return injected.pollRaf(predicate, timeout); return injected.pollMutation(predicate, timeout); function predicate(): Element | boolean { const element = injected.querySelector(selector, document); if (!element) return waitForHidden; if (!waitForVisible && !waitForHidden) return element; const style = window.getComputedStyle(element); const isVisible = style && style.visibility !== 'hidden' && hasVisibleBoundingBox(); const success = (waitForVisible === isVisible || waitForHidden === !isVisible); return success ? element : false; function hasVisibleBoundingBox(): boolean { const rect = element.getBoundingClientRect(); return !!(rect.top || rect.bottom || rect.width || rect.height); } } }, await domWorld.injected(), selector, waitForVisible, waitForHidden, options.timeout); }