Accessibility snapshot with content-hash stable refs.
Walks the DOM tree via JavaScript injection and builds a YAML-like
accessibility tree with content-hash refs (deterministic across page states).
Elements are tagged with data-pw-ref attributes for later interaction.
Usage: (def snap (capture-snapshot page)) (:tree snap) ;; YAML-like string with [@eXXXXX] annotations (:refs snap) ;; {ref-id {:role :name :tag :bbox} ...} (resolve-ref page ref-id) ;; returns Locator for the element
Accessibility snapshot with content-hash stable refs.
Walks the DOM tree via JavaScript injection and builds a YAML-like
accessibility tree with content-hash refs (deterministic across page states).
Elements are tagged with `data-pw-ref` attributes for later interaction.
Usage:
(def snap (capture-snapshot page))
(:tree snap) ;; YAML-like string with [@eXXXXX] annotations
(:refs snap) ;; {ref-id {:role :name :tag :bbox} ...}
(resolve-ref page ref-id) ;; returns Locator for the element(capture-failure result)Returns an anomaly when a raw capture result cannot be parsed, else nil.
The capture is only trustworthy when the script actually ran and returned a tree slot. Two failures used to be indistinguishable from a blank page: an evaluate anomaly (a crashed or closed renderer) and a capture script that aborted (depth budget exceeded). Both are reported here so callers fail loudly instead of rendering an empty snapshot.
Params:
result - The raw value returned by the capture script evaluation.
Returns:
An anomaly map, or nil when result is a usable capture result.
Returns an anomaly when a raw capture result cannot be parsed, else nil. The capture is only trustworthy when the script actually ran and returned a tree slot. Two failures used to be indistinguishable from a blank page: an evaluate anomaly (a crashed or closed renderer) and a capture script that aborted (depth budget exceeded). Both are reported here so callers fail loudly instead of rendering an empty snapshot. Params: `result` - The raw value returned by the capture script evaluation. Returns: An anomaly map, or nil when `result` is a usable capture result.
(capture-full-snapshot page)Captures a snapshot of the page and all its iframes.
Combines main frame and iframe snapshots into a unified tree.
Params:
page - Playwright Page instance.
Returns: Map with :tree, :refs, :counter covering all frames, or the main frame's anomaly when that capture failed.
Captures a snapshot of the page and all its iframes. Combines main frame and iframe snapshots into a unified tree. Params: `page` - Playwright Page instance. Returns: Map with :tree, :refs, :counter covering all frames, or the main frame's anomaly when that capture failed.
(capture-script opts)Returns the capture-snapshot JS with optional flags injected.
When :scope is provided, the JS walks from the element matching
that CSS selector instead of document.body. If the selector matches nothing,
the JS returns an empty result.
When :styles is true, each ref'd element includes computed CSS styles
in kebab-case CSS property names. The :styles-detail option selects
the tier: 'minimal' (16 props), 'base' (31, default), or 'max' (44).
Scope can be a CSS selector or a snapshot ref (@e2yrjz).
Backend-neutral: the returned script is a self-executing expression that
works through Playwright page.evaluate and (wrapped in return (...))
through W3C WebDriver execute-script.
Returns the capture-snapshot JS with optional flags injected. When `:scope` is provided, the JS walks from the element matching that CSS selector instead of document.body. If the selector matches nothing, the JS returns an empty result. When `:styles` is true, each ref'd element includes computed CSS styles in kebab-case CSS property names. The `:styles-detail` option selects the tier: 'minimal' (16 props), 'base' (31, default), or 'max' (44). Scope can be a CSS selector or a snapshot ref (@e2yrjz). Backend-neutral: the returned script is a self-executing expression that works through Playwright `page.evaluate` and (wrapped in `return (...)`) through W3C WebDriver execute-script.
(capture-snapshot page)(capture-snapshot page opts)Captures an accessibility snapshot of the page with numbered refs.
Injects JavaScript to walk the DOM, compute ARIA roles and names, assign data-pw-ref attributes, and collect bounding boxes.
Params:
page - Playwright Page instance.
opts - Map, optional.
:scope - String. CSS selector or snapshot ref (@e2yrjz, e2yrjz) to scope the
snapshot to a subtree. When provided, only elements within the
matched element are included in the tree and refs.
If the selector matches nothing, returns an empty snapshot.
Returns: Map with: :tree - String. YAML-like accessibility tree with [@eXXXXX] annotations. :raw-tree - The raw nested tree structure from the accessibility snapshot JS. :refs - Map. {'e2yrjz' {:role 'button' :name 'Submit' :bbox {:x :y :width :height}} ...} :counter - Long. Total number of refs assigned.
Or an anomaly when the capture itself failed — a crashed or closed renderer, or a DOM nested deeper than the walker's documented depth budget.
Captures an accessibility snapshot of the page with numbered refs.
Injects JavaScript to walk the DOM, compute ARIA roles and names,
assign data-pw-ref attributes, and collect bounding boxes.
Params:
`page` - Playwright Page instance.
`opts` - Map, optional.
:scope - String. CSS selector or snapshot ref (@e2yrjz, e2yrjz) to scope the
snapshot to a subtree. When provided, only elements within the
matched element are included in the tree and refs.
If the selector matches nothing, returns an empty snapshot.
Returns:
Map with:
:tree - String. YAML-like accessibility tree with [@eXXXXX] annotations.
:raw-tree - The raw nested tree structure from the accessibility snapshot JS.
:refs - Map. {'e2yrjz' {:role 'button' :name 'Submit' :bbox {:x :y :width :height}} ...}
:counter - Long. Total number of refs assigned.
Or an anomaly when the capture itself failed — a crashed or closed renderer,
or a DOM nested deeper than the walker's documented depth budget.(capture-snapshot-for-frame _frame frame-ordinal)Captures an accessibility snapshot for a specific frame.
Refs are prefixed with the frame ordinal: f1_e1, f2_e3, etc.
Params:
frame - Playwright Frame instance.
frame-ordinal - Long. Frame index (1-based).
Returns: Same format as capture-snapshot, but with prefixed refs.
Captures an accessibility snapshot for a specific frame. Refs are prefixed with the frame ordinal: f1_e1, f2_e3, etc. Params: `frame` - Playwright Frame instance. `frame-ordinal` - Long. Frame index (1-based). Returns: Same format as capture-snapshot, but with prefixed refs.
(capture-webdriver driver)(capture-webdriver driver opts)Captures an accessibility snapshot through a W3C WebDriver session.
Reuses the same capture script as the Playwright adapter — the WebDriver
evaluate wrapper adds the return (...) required by execute-script
semantics. Viewport is read from the page via JavaScript because
WebDriver has no direct viewport API for web content.
Frames are NOT walked — this is a main-frame-only snapshot (iOS MVP).
Params:
driver - com.blockether.spel.webdriver WebDriverSession.
opts - Same options as capture-snapshot (:scope, :styles, ...).
Returns the same map shape as capture-snapshot, or an anomaly when the capture failed.
Captures an accessibility snapshot through a W3C WebDriver session. Reuses the same capture script as the Playwright adapter — the WebDriver evaluate wrapper adds the `return (...)` required by execute-script semantics. Viewport is read from the page via JavaScript because WebDriver has no direct viewport API for web content. Frames are NOT walked — this is a main-frame-only snapshot (iOS MVP). Params: `driver` - com.blockether.spel.webdriver WebDriverSession. `opts` - Same options as capture-snapshot (:scope, :styles, ...). Returns the same map shape as capture-snapshot, or an anomaly when the capture failed.
(clear-refs! page)Removes all data-pw-ref attributes from the page.
Params:
page - Playwright Page instance.
Removes all data-pw-ref attributes from the page. Params: `page` - Playwright Page instance.
(decode-capture-result result)Parses the capture script's JSON payload into a string-keyed map.
The script answers with a JSON string rather than an object: Playwright's serializer refuses to return an object nested more than a few hundred levels deep ("Cannot serialize result: object reference chain is too long"), so a page nested far below the walker's own depth budget could not be snapshotted at all. Anomalies and already-parsed maps pass through untouched.
Params:
result - The raw value returned by evaluating the capture script.
Returns:
A string-keyed map, an anomaly, or result unchanged.
Parses the capture script's JSON payload into a string-keyed map.
The script answers with a JSON string rather than an object: Playwright's
serializer refuses to return an object nested more than a few hundred levels
deep ("Cannot serialize result: object reference chain is too long"), so a
page nested far below the walker's own depth budget could not be snapshotted
at all. Anomalies and already-parsed maps pass through untouched.
Params:
`result` - The raw value returned by evaluating the capture script.
Returns:
A string-keyed map, an anomaly, or `result` unchanged.(diff-snapshots baseline current)Compares two accessibility snapshot strings line-by-line.
Returns a map with diff statistics and individual line changes.
Params:
baseline - String. The baseline snapshot text.
current - String. The current snapshot text.
Returns: {:added N :removed N :changed N :unchanged N :diff [" line" "- old" "+ new" ...]}.
Compares two accessibility snapshot strings line-by-line.
Returns a map with diff statistics and individual line changes.
Params:
`baseline` - String. The baseline snapshot text.
`current` - String. The current snapshot text.
Returns:
{:added N :removed N :changed N :unchanged N :diff [" line" "- old" "+ new" ...]}.(flatten-tree tree)Flattens a YAML-like tree string by stripping all leading whitespace. Each node appears at depth 0, removing the nested hierarchy.
Useful for AI agents that need a simple list of elements without nesting structure.
Params:
tree - String. YAML-like accessibility tree from capture-snapshot.
Returns: String with all lines at depth 0, or nil if tree is nil.
Flattens a YAML-like tree string by stripping all leading whitespace. Each node appears at depth 0, removing the nested hierarchy. Useful for AI agents that need a simple list of elements without nesting structure. Params: `tree` - String. YAML-like accessibility tree from capture-snapshot. Returns: String with all lines at depth 0, or nil if tree is nil.
(parse-capture-result result)(parse-capture-result result opts)Parses the raw JS capture result into the public snapshot map.
Backend-neutral: result is the map returned by the capture script — a
java.util.Map from Playwright evaluate or a Clojure map from WebDriver
execute-script (both string-keyed).
Params:
result - Map with "tree", "refs", "counter" keys.
opts - Map, optional:
:viewport - Map {:width :height} for the tree header.
:device - String device label for the tree header.
Returns: Map with :tree, :raw-tree, :refs, :counter, :viewport, :device.
Parses the raw JS capture result into the public snapshot map.
Backend-neutral: `result` is the map returned by the capture script — a
java.util.Map from Playwright evaluate or a Clojure map from WebDriver
execute-script (both string-keyed).
Params:
`result` - Map with "tree", "refs", "counter" keys.
`opts` - Map, optional:
:viewport - Map {:width :height} for the tree header.
:device - String device label for the tree header.
Returns:
Map with :tree, :raw-tree, :refs, :counter, :viewport, :device.(ref-bounding-box refs ref-id)Returns the bounding box for a ref from the last snapshot.
Params:
refs - Map of refs from capture-snapshot.
ref-id - String. Content-hash ref like "e2yrjz".
Returns: Map {:x :y :width :height} or nil.
Returns the bounding box for a ref from the last snapshot.
Params:
`refs` - Map of refs from capture-snapshot.
`ref-id` - String. Content-hash ref like "e2yrjz".
Returns:
Map {:x :y :width :height} or nil.(ref-css-selector ref-id)Returns the CSS selector for a snapshot ref id.
Accepts bare (e2yrjz) or prefixed (@e2yrjz) refs.
Backend-neutral — used by both Playwright and WebDriver ref resolution.
Returns the CSS selector for a snapshot ref id. Accepts bare (`e2yrjz`) or prefixed (`@e2yrjz`) refs. Backend-neutral — used by both Playwright and WebDriver ref resolution.
(resolve-ref page ref-id)Resolves a ref ID to a Playwright Locator.
The element must have been tagged with data-pw-ref during capture-snapshot.
Params:
page - Playwright Page instance.
ref-id - String. Bare ref ID without @ prefix (e.g. e2yrjz).
Returns: Locator instance for the element.
Resolves a ref ID to a Playwright Locator. The element must have been tagged with data-pw-ref during capture-snapshot. Params: `page` - Playwright Page instance. `ref-id` - String. Bare ref ID without @ prefix (e.g. e2yrjz). Returns: Locator instance for the element.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |