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 * as aria from '@isomorphic/ariaSnapshot';
import { renderAriaSnapshotAsYaml } from '@isomorphic/ariaSnapshotRenderer';
import { normalizeWhiteSpace, truncateDataUrl } from '@isomorphic/stringUtils';
import { distillAriaSnapshot } from './ariaSnapshotDistiller';
import { computeBox, getElementComputedStyle, isElementVisible } from './domUtils';
import * as roleUtils from './roleUtils';
export type AriaSnapshot = {
root: aria.AriaNode;
info: Map<string, { element: Element, nameFromContentRefs: string[] }>;
refs: Map<Element, string>;
iframeRefs: string[];
};
type AriaRef = {
role: string;
name: string;
ref: string;
};
let lastRef = 0;
export type AriaTreeOptions = {
mode: 'ai' | 'default' | 'codegen' | 'autoexpect';
refPrefix?: string;
doNotRenderActive?: boolean;
depth?: number;
boxes?: boolean;
};
type InternalOptions = {
visibility: 'aria' | 'ariaOrVisible' | 'ariaAndVisible',
refs: 'all' | 'interactable' | 'none',
refPrefix?: string,
includeGenericRole?: boolean,
renderCursorPointer?: boolean,
renderActive?: boolean,
renderBoxes?: boolean,
};
function toInternalOptions(options: AriaTreeOptions): InternalOptions {
const renderBoxes = options.boxes;
if (options.mode === 'ai') {
// For AI consumption.
return {
visibility: 'ariaOrVisible',
refs: 'interactable',
refPrefix: options.refPrefix,
includeGenericRole: true,
renderActive: !options.doNotRenderActive,
renderCursorPointer: true,
renderBoxes,
};
}
if (options.mode === 'autoexpect') {
// To auto-generate assertions on visible elements.
return { visibility: 'ariaAndVisible', refs: 'none', renderBoxes };
}
// To match aria snapshot. In 'codegen' mode, the generated tree is the same,
// strings are converted to regexes when serializing to yaml.
return { visibility: 'aria', refs: 'none', renderBoxes };
}
export function generateAriaTree(rootElement: Element, publicOptions: AriaTreeOptions): AriaSnapshot {
const options = toInternalOptions(publicOptions);
const visited = new Set<Node>();
// For each node, the elements that contributed to its accessible name.
const nameSourceElements = new Map<aria.AriaNode, Set<Element> | undefined>();
const snapshot: AriaSnapshot = {
root: { role: 'fragment', name: '', children: [], props: {}, box: computeBox(rootElement), receivesPointerEvents: true },
info: new Map<string, { element: Element, nameFromContentRefs: string[] }>(),
refs: new Map<Element, string>(),
iframeRefs: [],
};
setAriaNodeElement(snapshot.root, rootElement);
const visit = (ariaNode: aria.AriaNode, node: Node, parentElementVisible: boolean) => {
if (visited.has(node))
return;
visited.add(node);
if (node.nodeType === Node.TEXT_NODE && node.nodeValue) {
if (!parentElementVisible)
return;
// Text nodes that are not rendered are neither visible nor exposed to aria,
// so they are skipped regardless of the visibility option.
if (roleUtils.isTextNodeNotRendered(node as Text))
return;
const text = node.nodeValue;
// <textarea>AAA</textarea> should not report AAA as a child of the textarea.
if (ariaNode.role !== 'textbox' && text)
ariaNode.children.push(node.nodeValue || '');
return;
}
if (node.nodeType !== Node.ELEMENT_NODE)
return;
const element = node as Element;
const isElementVisibleForAria = !roleUtils.isElementHiddenForAria(element);
let visible = isElementVisibleForAria;
if (options.visibility === 'ariaOrVisible')
visible = isElementVisibleForAria || isElementVisible(element);
if (options.visibility === 'ariaAndVisible')
visible = isElementVisibleForAria && isElementVisible(element);
// Optimization: if we only consider aria visibility, we can skip child elements because
// they will not be visible for aria as well. The only exception is the topmost modal dialog
// that escapes inertness of its ancestors.
if (options.visibility === 'aria' && !visible && !roleUtils.containsTopmostModalDialog(element))
return;
const ariaChildren: Element[] = [];
if (element.hasAttribute('aria-owns')) {
const ids = element.getAttribute('aria-owns')!.split(/\s+/);
for (const id of ids) {
const ownedElement = rootElement.ownerDocument.getElementById(id);
if (ownedElement)
ariaChildren.push(ownedElement);
}
}
const childAriaNode = visible ? toAriaNode(element, options, nameSourceElements) : null;
if (childAriaNode && element.getAttribute('aria-hidden')?.toLowerCase() === 'true')
childAriaNode.props['aria-hidden'] = 'true';
let elementInfo: { element: Element, nameFromContentRefs: string[] } | undefined;
if (childAriaNode) {
if (childAriaNode.ref) {
elementInfo = { element, nameFromContentRefs: [] };
snapshot.info.set(childAriaNode.ref, elementInfo);
snapshot.refs.set(element, childAriaNode.ref);
if (childAriaNode.role === 'iframe')
snapshot.iframeRefs.push(childAriaNode.ref);
}
ariaNode.children.push(childAriaNode);
}
processElement(childAriaNode || ariaNode, element, ariaChildren, visible);
// Now that the subtree is processed, every descendant that contributed to this node's
// accessible name has its ref assigned, so we can resolve those refs as the name's origins.
if (elementInfo) {
for (const contributor of nameSourceElements.get(childAriaNode!) || []) {
const ref = snapshot.refs.get(contributor);
if (ref && ref !== childAriaNode!.ref)
elementInfo.nameFromContentRefs.push(ref);
}
}
};
function processElement(ariaNode: aria.AriaNode, element: Element, ariaChildren: Element[], parentElementVisible: boolean) {
// Surround every element with spaces for the sake of concatenated text nodes.
const display = getElementComputedStyle(element)?.display || 'inline';
const treatAsBlock = (display !== 'inline' || element.nodeName === 'BR') ? ' ' : '';
if (treatAsBlock)
ariaNode.children.push(treatAsBlock);
ariaNode.children.push(roleUtils.getCSSContent(element, '::before') || '');
const assignedNodes = element.nodeName === 'SLOT' ? (element as HTMLSlotElement).assignedNodes() : [];
if (assignedNodes.length) {
for (const child of assignedNodes)
visit(ariaNode, child, parentElementVisible);
} else {
for (let child = element.firstChild; child; child = child.nextSibling) {
if (!(child as Element | Text).assignedSlot)
visit(ariaNode, child, parentElementVisible);
}
if (element.shadowRoot) {
for (let child = element.shadowRoot.firstChild; child; child = child.nextSibling)
visit(ariaNode, child, parentElementVisible);
}
}
for (const child of ariaChildren)
visit(ariaNode, child, parentElementVisible);
ariaNode.children.push(roleUtils.getCSSContent(element, '::after') || '');
if (treatAsBlock)
ariaNode.children.push(treatAsBlock);
if (ariaNode.children.length === 1 && ariaNode.name === ariaNode.children[0])
ariaNode.children = [];
if (ariaNode.role === 'link' && element.hasAttribute('href')) {
const href = element.getAttribute('href')!;
ariaNode.props['url'] = truncateDataUrl(href);
}
if (ariaNode.role === 'textbox' && element.hasAttribute('placeholder') && element.getAttribute('placeholder') !== ariaNode.name) {
const placeholder = element.getAttribute('placeholder')!;
ariaNode.props['placeholder'] = placeholder;
}
}
roleUtils.beginAriaCaches();
try {
visit(snapshot.root, rootElement, true);
} finally {
roleUtils.endAriaCaches();
}
distillAriaSnapshot(snapshot, publicOptions);
return snapshot;
}
function computeAriaRef(ariaNode: aria.AriaNode, options: InternalOptions) {
if (options.refs === 'none')
return;
if (options.refs === 'interactable' && (!ariaNode.box.visible || !ariaNode.receivesPointerEvents))
return;
const element = ariaNodeElement(ariaNode);
let ariaRef = (element as any)._ariaRef as AriaRef | undefined;
if (!ariaRef || ariaRef.role !== ariaNode.role || ariaRef.name !== ariaNode.name) {
ariaRef = { role: ariaNode.role, name: ariaNode.name, ref: (options.refPrefix ?? '') + 'e' + (++lastRef) };
(element as any)._ariaRef = ariaRef;
}
ariaNode.ref = ariaRef.ref;
}
function toAriaNode(element: Element, options: InternalOptions, nameSourceElements: Map<aria.AriaNode, Set<Element> | undefined>): aria.AriaNode | null {
const active = element.ownerDocument.activeElement === element && element.ownerDocument.hasFocus();
if (element.nodeName === 'IFRAME' || element.nodeName === 'FRAME') {
const ariaNode: aria.AriaNode = {
role: 'iframe',
name: '',
children: [],
props: {},
box: computeBox(element),
receivesPointerEvents: true,
active
};
setAriaNodeElement(ariaNode, element);
computeAriaRef(ariaNode, options);
return ariaNode;
}
const defaultRole = options.includeGenericRole ? 'generic' : null;
const role = roleUtils.getAriaRole(element) ?? defaultRole;
if (!role || role === 'presentation' || role === 'none')
return null;
const name = roleUtils.getElementAccessibleName(element, false);
const receivesPointerEvents = roleUtils.receivesPointerEvents(element);
const box = computeBox(element);
if (role === 'generic' && box.inline && element.childNodes.length === 1 && element.childNodes[0].nodeType === Node.TEXT_NODE)
return null;
const result: aria.AriaNode = {
role,
name: normalizeWhiteSpace(name.text),
children: [],
props: {},
box,
receivesPointerEvents,
active
};
setAriaNodeElement(result, element);
nameSourceElements.set(result, name.elements);
computeAriaRef(result, options);
if (roleUtils.kAriaCheckedRoles.includes(role))
result.checked = roleUtils.getAriaChecked(element);
if (roleUtils.kAriaDisabledRoles.includes(role))
result.disabled = roleUtils.getAriaDisabled(element);
if (roleUtils.kAriaExpandedRoles.includes(role))
result.expanded = roleUtils.getAriaExpanded(element);
if (roleUtils.kAriaInvalidRoles.includes(role)) {
const invalid = roleUtils.getAriaInvalid(element);
result.invalid = invalid === 'false' ? false : invalid === 'true' ? true : invalid;
}
if (roleUtils.kAriaLevelRoles.includes(role))
result.level = roleUtils.getAriaLevel(element);
if (roleUtils.kAriaPressedRoles.includes(role))
result.pressed = roleUtils.getAriaPressed(element);
if (roleUtils.kAriaSelectedRoles.includes(role))
result.selected = roleUtils.getAriaSelected(element);
if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
if (element.type !== 'checkbox' && element.type !== 'radio' && element.type !== 'file')
result.children = [element.value];
}
return result;
}
function matchesStringOrRegex(text: string, template: aria.AriaRegex | string | undefined): boolean {
if (!template)
return true;
if (!text)
return false;
if (typeof template === 'string')
return text === template;
return !!text.match(new RegExp(template.pattern));
}
function matchesTextValue(text: string, template: aria.AriaTextValue | undefined) {
if (!template?.normalized)
return true;
if (!text)
return false;
if (text === template.normalized)
return true;
// Accept pattern as value.
if (text === template.raw)
return true;
const regex = cachedRegex(template);
if (regex)
return !!text.match(regex);
return false;
}
const cachedRegexSymbol = Symbol('cachedRegex');
function cachedRegex(template: aria.AriaTextValue): RegExp | null {
if ((template as any)[cachedRegexSymbol] !== undefined)
return (template as any)[cachedRegexSymbol];
const { raw } = template;
const canBeRegex = raw.startsWith('/') && raw.endsWith('/') && raw.length > 1;
let regex: RegExp | null;
try {
regex = canBeRegex ? new RegExp(raw.slice(1, -1)) : null;
} catch (e) {
regex = null;
}
(template as any)[cachedRegexSymbol] = regex;
return regex;
}
export type MatcherReceived = {
raw: string;
regex: string;
};
export function matchesExpectAriaTemplate(rootElement: Element, template: aria.AriaTemplateNode): { matches: aria.AriaNode[], received: MatcherReceived } {
const snapshot = generateAriaTree(rootElement, { mode: 'default' });
const matches = matchesNodeDeep(snapshot.root, template, false, false);
const { json } = renderAriaTreeAsJSON(snapshot, { mode: 'default' });
return {
matches,
received: {
raw: renderAriaSnapshotAsYaml(json),
regex: renderAriaSnapshotAsYaml(json, { convertStringsToRegex: true }),
}
};
}
export function getAllElementsMatchingExpectAriaTemplate(rootElement: Element, template: aria.AriaTemplateNode): Element[] {
const root = generateAriaTree(rootElement, { mode: 'default' }).root;
const matches = matchesNodeDeep(root, template, true, false);
return matches.map(n => ariaNodeElement(n));
}
function matchesNode(node: aria.AriaNode | string, template: aria.AriaTemplateNode, isDeepEqual: boolean): boolean {
if (typeof node === 'string' && template.kind === 'text')
return matchesTextValue(node, template.text);
if (node === null || typeof node !== 'object' || template.kind !== 'role')
return false;
if (template.role !== 'fragment' && template.role !== node.role)
return false;
if (template.checked !== undefined && template.checked !== node.checked)
return false;
if (template.disabled !== undefined && template.disabled !== node.disabled)
return false;
if (template.expanded !== undefined && template.expanded !== node.expanded)
return false;
if (template.invalid !== undefined && template.invalid !== node.invalid)
return false;
if (template.level !== undefined && template.level !== node.level)
return false;
if (template.pressed !== undefined && template.pressed !== node.pressed)
return false;
if (template.selected !== undefined && template.selected !== node.selected)
return false;
if (!matchesStringOrRegex(node.name, template.name))
return false;
if (!matchesTextValue(node.props.url, template.props?.url))
return false;
// Proceed based on the container mode.
if (template.containerMode === 'contain')
return containsList(node.children || [], template.children || []);
if (template.containerMode === 'equal')
return listEqual(node.children || [], template.children || [], false);
if (template.containerMode === 'deep-equal' || isDeepEqual)
return listEqual(node.children || [], template.children || [], true);
return containsList(node.children || [], template.children || []);
}
function listEqual(children: (aria.AriaNode | string)[], template: aria.AriaTemplateNode[], isDeepEqual: boolean): boolean {
if (template.length !== children.length)
return false;
for (let i = 0; i < template.length; ++i) {
if (!matchesNode(children[i], template[i], isDeepEqual))
return false;
}
return true;
}
function containsList(children: (aria.AriaNode | string)[], template: aria.AriaTemplateNode[]): boolean {
if (template.length > children.length)
return false;
const cc = children.slice();
const tt = template.slice();
for (const t of tt) {
let c = cc.shift();
while (c) {
if (matchesNode(c, t, false))
break;
c = cc.shift();
}
if (!c)
return false;
}
return true;
}
function matchesNodeDeep(root: aria.AriaNode, template: aria.AriaTemplateNode, collectAll: boolean, isDeepEqual: boolean): aria.AriaNode[] {
const results: aria.AriaNode[] = [];
const visit = (node: aria.AriaNode | string, parent: aria.AriaNode | null): boolean => {
if (matchesNode(node, template, isDeepEqual)) {
const result = typeof node === 'string' ? parent : node;
if (result)
results.push(result);
return !collectAll;
}
if (typeof node === 'string')
return false;
for (const child of node.children || []) {
if (visit(child, node))
return true;
}
return false;
};
visit(root, null);
return results;
}
export function renderAriaTreeAsJSON(ariaSnapshot: AriaSnapshot, publicOptions: AriaTreeOptions): { json: aria.AriaSnapshotJSON, iframeDepths: Record<string, number> } {
const options = toInternalOptions(publicOptions);
const iframeDepths: Record<string, number> = {};
const visit = (ariaNode: aria.AriaNode, depth: number, renderCursorPointer: boolean): aria.AriaNodeJSON => {
if (ariaNode.role === 'iframe' && ariaNode.ref)
iframeDepths[ariaNode.ref] = depth;
const node: aria.AriaNodeJSON = { role: ariaNode.role as aria.AriaNodeJSON['role'] };
if (ariaNode.name)
node.name = ariaNode.name;
if (ariaNode.checked === 'mixed' || ariaNode.checked === true)
node.checked = ariaNode.checked;
if (ariaNode.disabled)
node.disabled = true;
if (ariaNode.expanded)
node.expanded = true;
if (ariaNode.active && options.renderActive)
node.active = true;
if (ariaNode.invalid)
node.invalid = ariaNode.invalid;
if (ariaNode.level)
node.level = ariaNode.level;
if (ariaNode.pressed === 'mixed' || ariaNode.pressed === true)
node.pressed = ariaNode.pressed;
if (ariaNode.selected === true)
node.selected = true;
if (ariaNode.ref) {
node.ref = ariaNode.ref;
if (renderCursorPointer && aria.hasPointerCursor(ariaNode))
node.cursor = 'pointer';
}
if (options.renderBoxes) {
const element = ariaNodeElement(ariaNode);
if (element) {
const r = element.getBoundingClientRect();
node.box = { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
}
}
if (ariaNode.props.url !== undefined)
node.url = ariaNode.props.url;
if (ariaNode.props.placeholder !== undefined)
node.placeholder = ariaNode.props.placeholder;
if (ariaNode.props['aria-hidden'] !== undefined)
node.ariaHidden = true;
const singleTextChild = ariaNode.children.length === 1 && typeof ariaNode.children[0] === 'string' ? ariaNode.children[0] : undefined;
const isAtDepthLimit = !!publicOptions.depth && depth === publicOptions.depth;
if (singleTextChild !== undefined) {
node.text = singleTextChild;
} else if (!isAtDepthLimit && ariaNode.children.length) {
const inCursorPointer = !!ariaNode.ref && renderCursorPointer && aria.hasPointerCursor(ariaNode);
node.children = ariaNode.children.map(child => {
if (typeof child === 'string')
return child;
return visit(child, depth + 1, renderCursorPointer && !inCursorPointer);
});
}
return node;
};
const json: aria.AriaSnapshotJSON = [];
const nodesToRender = ariaSnapshot.root.role === 'fragment' ? ariaSnapshot.root.children : [ariaSnapshot.root];
for (const nodeToRender of nodesToRender) {
if (typeof nodeToRender === 'string')
json.push({ role: 'text', text: nodeToRender });
else
json.push(visit(nodeToRender, 0, !!options.renderCursorPointer));
}
return { json, iframeDepths };
}
const elementSymbol = Symbol('element');
function ariaNodeElement(ariaNode: aria.AriaNode): Element {
return (ariaNode as any)[elementSymbol];
}
function setAriaNodeElement(ariaNode: aria.AriaNode, element: Element) {
(ariaNode as any)[elementSymbol] = element;
}
export function findNewElement(from: aria.AriaNode | undefined, to: aria.AriaNode): Element | undefined {
const node = aria.findNewNode(from, to);
return node ? ariaNodeElement(node) : undefined;
}