blob: 21114eeae1702f26ff2903b3c4657da0a15454b7 [file] [view] [edit]
# @selenium/atoms
Browser injection atoms for Selenium WebDriver, published as TypeScript-typed
ES modules.
Atoms are small, self-contained functions that run inside the page under
automation. They encode the browser-compatibility behaviour that the W3C
WebDriver specification leaves to implementations — what "displayed" means, how
`getAttribute` reconciles attributes with IDL properties, and how a locator
resolves to elements. Selenium's own language bindings inject the same logic,
compiled to an IIFE; this package exposes it to other JavaScript tooling that
needs to match Selenium's behaviour exactly.
## Installation
```sh
npm install @selenium/atoms
```
This is an ES-module-only package and requires Node.js 18 or newer.
## Usage
```js
import { getAttribute, findElements, isDisplayed } from '@selenium/atoms'
```
Each atom is also available as its own subpath export, so a bundler can tree
shake down to just the one you need:
```js
import getAttribute from '@selenium/atoms/get-attribute'
import findElements from '@selenium/atoms/find-elements'
import isDisplayed from '@selenium/atoms/is-displayed'
```
### API
```ts
getAttribute(element: Element, attribute: string): string | null
findElements(target: Record<string, unknown>, root?: Document | Element | ShadowRoot): Element[]
isDisplayed(element: Element, ignoreOpacity?: boolean): boolean
```
`findElements` takes a locator object keyed by strategy, matching the WebDriver
wire format:
```js
findElements({ css: '.result' })
findElements({ 'link text': 'Continue' }, shadowRoot)
```
### Accessibility snapshot
```ts
accessibilitySnapshot(root?: Element | Document, options?: SnapshotOptions): AccessibilityNode
interface SnapshotOptions {
interestingOnly?: boolean // default true: prune unnamed generic and presentational nodes
}
interface AccessibilityNode {
role: string // WAI-ARIA role; "text" for text leaves
name: string // accessible name, "" when none
description: string // accessible description, "" when none
value?: string // textbox, searchbox, combobox and range roles
url?: string // the resolved href, on links that have one
states: Record<string, boolean | number | 'mixed'>
element?: Element // absent on text leaves
children: AccessibilityNode[]
}
```
```js
import accessibilitySnapshot from '@selenium/atoms/accessibility-snapshot'
const tree = accessibilitySnapshot() // the whole document
const dialog = accessibilitySnapshot(dialogElement) // one subtree
const full = accessibilitySnapshot(undefined, { interestingOnly: false }) // nothing pruned
```
The snapshot is *computed* by script from the DOM, following WAI-ARIA 1.2,
html-aam and accname 1.2. It is not the browser's own accessibility tree, and
it can differ from it at the edges. Elements that are hidden in the accname
sense are left out; generic wrappers are pruned and their children hoisted
unless `interestingOnly` is `false`, which keeps every rendered element as a
node with the role it has (Puppeteer's `accessibility.snapshot({ interestingOnly:
false })`); text an ancestor's name was computed from is not repeated as leaves.
A `link` node whose element has an `href` carries it, resolved, as `url`. Frames are
reported as `iframe` leaves with no children, whatever role attribute they
carry, since a child document is another browsing context the page cannot
reach; callers that can reach it stitch its snapshot in. Keys in `states` are
`checked`, `pressed`, `expanded`, `selected`, `level`, `disabled` and
`focused`; new keys may be added in any release, so ignore keys you do not
recognise. A password field's `value` is masked, one bullet per character, as
the browser's own tree exposes it.
`accessibilitySnapshotWire(root?: Element, options?: SnapshotOptions)` returns the same snapshot in the
shape the Selenium bindings fetch over WebDriver BiDi: `{ json, elements,
windows }`, the tree as JSON text with each `element` replaced by an index into
`elements` and each frame node given a `frame` index into `windows` (the
frame's content window), so a binding parses one string and maps two arrays
instead of decoding a nested remote value. It answers `null` for a root this
document does not own (one owned by another document, or a `null` root, which
is how Firefox hands over a shared id of another document's node) and
`{ error: 'detached' }` for a root no longer in its document. Page scripts have
no reason to use it over `accessibilitySnapshot`.
The atoms operate on the DOM of the document they are evaluated in, so they must
run in the page rather than in the driver process — for example via
`Runtime.evaluate` over CDP, `script.callFunction` over WebDriver BiDi, or
Selenium's own `executeScript`.
## Versioning
This package is released from the Selenium monorepo and shares its version with
the `selenium-webdriver` npm package.
## License
Apache-2.0. See `LICENSE` and `NOTICE`.