blob: 4d7b74210eafa7058a6fc59986fc85a72119d516 [file] [edit]
// Licensed to the Software Freedom Conservancy (SFC) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The SFC licenses this file
// to you 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.
'use strict'
/**
* @fileoverview Accessibility snapshots computed in the page (ADR 18205).
*
* The tree is computed by the `accessibility-snapshot` atom of `@selenium/atoms`,
* run over WebDriver BiDi in a sandbox realm so page scripts cannot interfere
* with it. The atom's wire entry hands the tree back as one JSON string beside
* the element and frame references, so this module holds only what is the
* binding's: the public node type and its text form, the mapping of references
* to WebElement, and frame stitching across browsing contexts.
*
* The output is *computed* from the DOM following WAI-ARIA, html-aam and
* accname; it is not the browser's own accessibility tree and can differ from
* it at the edges.
*/
const path = require('node:path')
const { getBidiConnection } = require('./bidi_connection')
const error = require('./error')
const logging = require('./logging')
const log_ = logging.getLogger(`${logging.Type.DRIVER}.accessibility`)
/** The order the text form writes states in (ADR 18205 §1). */
const STATE_ORDER = ['checked', 'pressed', 'expanded', 'selected', 'level', 'disabled', 'focused']
/** The sandbox realm the atom runs in: page scripts cannot reach its prototypes. */
const SANDBOX = 'selenium'
const SERIALIZATION_OPTIONS = { maxDomDepth: 0 }
const STALE_MESSAGE = 'the snapshot root is no longer attached to a document'
/**
* One node of an accessibility snapshot.
*/
class AccessibilityNode {
/**
* @param {{role: string, name: string, description: (string|undefined),
* value: (string|undefined), url: (string|undefined),
* states: (!Object<string, (boolean|number|string)>|undefined),
* element: (?WebElement|undefined), children: (!Array<!AccessibilityNode>|undefined)}} fields
*/
constructor({
role,
name,
description = '',
value = undefined,
url = undefined,
states = {},
element = null,
children = [],
}) {
/** The WAI-ARIA role token; `"text"` for text leaves and `"iframe"` for frames, under which the frame's own tree is attached. @type {string} */
this.role = role
/** The computed accessible name, `""` when there is none. @type {string} */
this.name = name
/** The computed accessible description, `""` when there is none. @type {string} */
this.description = description
/**
* The current value for textbox, searchbox, combobox and range roles;
* `undefined` where the role has none. A password field's value is masked.
* @type {(string|undefined)}
*/
this.value = value
/**
* The resolved `href` of a `link` whose element has one; `undefined` for
* every other node. Not rendered in the text form.
* @type {(string|undefined)}
*/
this.url = url
/**
* `checked`, `pressed`, `expanded`, `selected`, `level`, `disabled` and
* `focused`, each present only when it applies; new keys may be added in any
* release, so ignore keys you do not recognise.
* @type {!Object<string, (boolean|number|string)>}
*/
this.states = states
/**
* The element the node is backed by, usable for further commands, or `null`
* for text leaves. An element inside a child frame can be used through
* classic commands only once the driver has switched to that frame.
* @type {?WebElement}
*/
this.element = element
/** The child nodes, `[]` for leaves. @type {!Array<!AccessibilityNode>} */
this.children = children
}
/**
* Renders the tree as text, one node per line.
*
* The line grammar is `- role "name" [state] [state=value]: value`, children
* indented two spaces, text leaves written as `- text: content`. An empty
* name is left out, as is an absent or empty value; a `true` state is written
* bare, a `false` one left out, any other value spelled. A line break or
* backslash in a value is escaped so a node never spans two lines. The
* description and element references are not rendered.
*
* @return {string} The text form, without a trailing newline.
*/
toText() {
return [...lines(this, '')].join('\n')
}
}
function* lines(node, indent) {
yield indent + lineFor(node)
for (const child of node.children) {
yield* lines(child, indent + ' ')
}
}
function lineFor(node) {
if (node.role === 'text') {
return `- text: ${node.name}`
}
let out = `- ${node.role}`
if (node.name !== '') {
out += ` ${quote(node.name)}`
}
for (const key of STATE_ORDER) {
if (!(key in node.states)) continue
const state = node.states[key]
if (state === true) {
out += ` [${key}]`
} else if (state !== false) {
out += ` [${key}=${state}]`
}
}
if (node.value) {
out += `: ${oneLine(node.value)}`
}
return out
}
function quote(name) {
return '"' + name.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
}
function oneLine(value) {
return value.replace(/\\/g, '\\\\').replace(/\r/g, '\\r').replace(/\n/g, '\\n')
}
/**
* Builds the node tree from the atom's wire form.
*
* @param {!Object} data The parsed JSON of the tree: the node's fields, with
* `element` an index into `elements` and, on a frame node, `frame` an index
* the binding resolves to the frame's own tree.
* @param {!Array<!WebElement>} elements The elements the tree references, in the atom's order.
* @param {function(number): !Promise<!Array<!AccessibilityNode>>} frameChildren The
* children of a frame node, from its `frame` index: the frame's document, or
* nothing when it cannot be reached.
* @return {!Promise<!AccessibilityNode>} The node, with its subtree.
*/
async function nodeFromWire(data, elements, frameChildren) {
const children = []
if ('frame' in data) {
children.push(...(await frameChildren(data.frame)))
} else {
for (const child of data.children) {
children.push(await nodeFromWire(child, elements, frameChildren))
}
}
return new AccessibilityNode({
role: data.role,
name: data.name,
description: data.description ?? '',
value: data.value,
url: data.url,
states: { ...data.states },
element: data.element === undefined ? null : elements[data.element],
children,
})
}
let atomModule = null
/**
* The atom's wire entry as a function declaration: the module built by
* lib/atoms/make-atoms-module.js wraps the bundle in a function whose source
* `String()` returns, which `script.callFunction` can take as is.
* @return {string}
*/
function atomDeclaration() {
if (atomModule === null) {
try {
atomModule = require('./atoms/accessibility-snapshot.js')
} catch {
try {
atomModule = require(
path.resolve('../../../bazel-bin/javascript/selenium-webdriver/lib/atoms/accessibility-snapshot.js'),
)
} catch (ex) {
log_.severe(ex)
throw new Error(
'Failed to import atoms module accessibility-snapshot.js. If running in dev mode, you need to run' +
' `bazel build //javascript/selenium-webdriver/lib/atoms:accessibility_snapshot` from the project' +
' root first.',
{ cause: ex },
)
}
}
}
return String(atomModule)
}
/** A shared id that the targeted document does not own. */
class NoSuchNode extends Error {}
/** Whether an error says a frame or its document is gone, rather than that a command failed. */
function frameUnreachable(e) {
const message = String(e?.message ?? e)
return e instanceof NoSuchNode || message.includes('no such frame') || message.includes('no such node')
}
/** The entries of an `object` remote value by property name. */
function objectFields(value) {
if (!value || value.type !== 'object') {
throw new error.WebDriverError(`accessibility snapshot: expected an object remote value, got ${value?.type}`)
}
// A property name is written as a plain string, or as a string remote value.
return new Map((value.value ?? []).map(([key, entry]) => [typeof key === 'string' ? key : stringValue(key), entry]))
}
function stringValue(value) {
return String(value?.value ?? '')
}
function sharedIdOf(node) {
if (node?.type !== 'node' || !node.sharedId) {
throw new error.WebDriverError('accessibility snapshot: expected a node reference in the elements list')
}
return node.sharedId
}
/** The browsing context id of a `window` remote value; null for a frame with no reachable context. */
function contextOf(window) {
return window?.type === 'window' ? (window.value?.context ?? null) : null
}
/**
* Takes snapshots for one driver: runs the atom in each document and stitches
* child frames into the tree.
*/
class AccessibilitySnapshotter {
/**
* @param {!WebDriver} driver The driver to snapshot through.
* @param {function(string): !WebElement} elementFactory Makes the element for a shared id.
*/
constructor(driver, elementFactory) {
this.driver_ = driver
this.elementFactory_ = elementFactory
}
/**
* Snapshots the whole page, or the subtree under `root`.
*
* @param {?WebElement} root The element whose subtree to snapshot, or null for
* the page of the current window's top-level browsing context.
* @param {{interestingOnly: (boolean|undefined)}=} options With `interestingOnly`
* true, the default, unnamed generic and presentational elements produce no
* node and their children take their place; with false every rendered
* element produces a node.
* @return {!Promise<!AccessibilityNode>} The snapshot, with every reachable
* child frame's tree attached under its `iframe` node.
* @throws {error.UnsupportedOperationError} When the session has no BiDi connection.
* @throws {error.StaleElementReferenceError} When `root` no longer belongs to a document.
*/
async snapshot(root, { interestingOnly = true } = {}) {
const caps = await this.driver_.getCapabilities()
if (!caps.get('webSocketUrl')) {
throw new error.UnsupportedOperationError(
'getAccessibilitySnapshot() requires a WebDriver BiDi session; enable it with options.enableBidi()' +
' before building the driver',
)
}
const top = await this.driver_.getWindowHandle()
if (!root) {
const node = await this.snapshotContext_(top, null, interestingOnly)
if (node === null) {
throw new error.WebDriverError('accessibility snapshot: the script returned nothing')
}
return node
}
// The element may live in any frame of the window. Chromium resolves its shared
// id only in the document that owns it; Firefox resolves it in any document of
// the browsing context group, so the atom checks ownership itself and each
// context is tried until the owner is found.
const rootId = await root.getId()
for (const context of await this.contexts_(top)) {
let node
try {
node = await this.snapshotContext_(context, rootId, interestingOnly)
} catch (e) {
if (!(e instanceof NoSuchNode)) throw e
continue
}
if (node !== null) return node
}
throw new error.StaleElementReferenceError(STALE_MESSAGE)
}
/**
* Sends one BiDi command over the driver's connection and returns its result.
* The call here returns node remote values by the hundred, whose attribute
* maps the generated domain modules would validate one by one.
* @private
*/
async send_(method, params) {
const bidi = await getBidiConnection(this.driver_)
const response = await bidi.send({ method, params })
if (response.error) {
throw new Error(`${response.error}: ${response.message}`)
}
return response.result
}
/**
* The snapshot of `context`, or null when another document owns the root.
* @private
*/
async snapshotContext_(context, rootId, interestingOnly = true) {
// The flag goes first, so a whole-page call sends no placeholder for a root.
const args = [{ type: 'boolean', value: interestingOnly }]
if (rootId) args.push({ sharedId: rootId })
const result = await this.call_(context, args)
if (result.type === 'null') return null
const fields = objectFields(result)
if (fields.has('error')) {
// The only error the atom reports as data: the root left its document.
throw new error.StaleElementReferenceError(STALE_MESSAGE)
}
const elements = (fields.get('elements')?.value ?? []).map((node) => this.elementFactory_(sharedIdOf(node)))
const windows = (fields.get('windows')?.value ?? []).map(contextOf)
return nodeFromWire(JSON.parse(stringValue(fields.get('json'))), elements, (index) =>
this.stitch_(windows[index], interestingOnly),
)
}
/**
* Runs the atom's wire entry in the sandbox of `context` and returns the remote value of its result.
* @private
*/
async call_(context, args) {
let raw
try {
raw = await this.send_('script.callFunction', {
functionDeclaration: `(interestingOnly, root) => (${atomDeclaration()})(root, { interestingOnly })`,
awaitPromise: false,
target: { context, sandbox: SANDBOX },
arguments: args,
resultOwnership: 'none',
serializationOptions: SERIALIZATION_OPTIONS,
})
} catch (e) {
// The BiDi "no such node" error: the document of this context does not own
// the root's shared id, either because the root lives in another frame or
// because its document is gone.
if (String(e?.message).includes('no such node')) {
throw new NoSuchNode(e.message)
}
throw e
}
if (raw.type === 'exception') {
const text = String(raw.exceptionDetails?.text ?? raw.exceptionDetails)
throw new error.WebDriverError(`accessibility snapshot failed in the page: ${text}`)
}
return raw.result
}
/**
* The document of a frame as the frame node's one child, or no children when unreachable.
* @private
*/
async stitch_(context, interestingOnly) {
if (!context) return []
try {
const document = await this.snapshotContext_(context, null, interestingOnly)
return document === null ? [] : [document]
} catch (e) {
// Gone between discovery and the call, or mid-navigation: the frame stays
// a leaf (ADR §1). Anything else is a real failure.
if (!frameUnreachable(e)) throw e
log_.finer(`accessibility snapshot: frame ${context} not reachable: ${e}`)
return []
}
}
/** The window's browsing contexts, top-level first, then each frame depth-first. */
async contexts_(top) {
const contexts = [top]
const tree = await this.send_('browsingContext.getTree', { root: top })
const stack = [...(tree.contexts ?? [])]
while (stack.length) {
const info = stack.shift()
if (info.context !== top) contexts.push(info.context)
stack.unshift(...(info.children ?? []))
}
return contexts
}
}
module.exports = { AccessibilityNode, AccessibilitySnapshotter, nodeFromWire }