Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

20.0 KB
Raw Blame
/**
 * 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;
}