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.
npm install @selenium/atoms
This is an ES-module-only package and requires Node.js 18 or newer.
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:
import getAttribute from '@selenium/atoms/get-attribute' import findElements from '@selenium/atoms/find-elements' import isDisplayed from '@selenium/atoms/is-displayed'
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:
findElements({ css: '.result' }) findElements({ 'link text': 'Continue' }, shadowRoot)
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[] }
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.
This package is released from the Selenium monorepo and shares its version with the selenium-webdriver npm package.
Apache-2.0. See LICENSE and NOTICE.