Finding Elements with the Accessibility Tree
JavaScript
Section titled “JavaScript”Learn how to inspect page structure with a11yTree() and use the results to find and interact with elements.
What You’ll Learn
Section titled “What You’ll Learn”- How to get a page’s accessibility tree
- How to use tree output to build selectors for
find() everythingandrootoptions- When to use semantic selectors vs CSS selectors
Getting the Tree
Section titled “Getting the Tree”a11yTree() returns the page’s accessibility tree — a structured view of every element as assistive technology sees it.
Sync:
const { browser } = require('vibium/sync')
const bro = browser.start()const vibe = bro.page()vibe.go('https://example.com')
const tree = vibe.a11yTree()console.log(JSON.stringify(tree, null, 2))
bro.stop()Async:
const { browser } = require('vibium')
async function main() { const bro = await browser.start() const vibe = await bro.page() await vibe.go('https://example.com')
const tree = await vibe.a11yTree() console.log(JSON.stringify(tree, null, 2))
await bro.stop()}
main()Here’s an example of what the tree looks like for a login form:
{ "role": "WebArea", "name": "Login", "children": [ { "role": "heading", "level": 1 }, { "role": "textbox", "name": "Username" }, { "role": "textbox", "name": "Password" }, { "role": "checkbox", "name": "Remember me", "checked": false }, { "role": "button", "name": "Sign in" } ]}Each node has a role (what the element is). Nodes with explicit labels (aria-label, <label for>, etc.) also have a name. Some nodes have state properties like checked, disabled, or expanded.
Two helper functions used throughout this tutorial:
function findByRole(node, role) { if (node.role === role) return node for (const child of node.children || []) { const found = findByRole(child, role) if (found) return found } return null}
function collectRoles(node) { const roles = [node.role] if (node.children) { for (const child of node.children) roles.push(...collectRoles(child)) } return roles}await vibe.setContent(` <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>`)
const tree = await vibe.a11yTree()
assert.strictEqual(tree.role, 'WebArea')assert.ok(Array.isArray(tree.children), 'tree should have children')
const roles = collectRoles(tree)assert.ok(roles.includes('heading'), 'should have heading')assert.ok(roles.includes('textbox'), 'should have textbox')assert.ok(roles.includes('button'), 'should have button')vibe.setContent(` <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>`)
const tree = vibe.a11yTree()
assert.strictEqual(tree.role, 'WebArea')assert.ok(Array.isArray(tree.children), 'tree should have children')await vibe.setContent(` <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>`)
const tree = await vibe.a11yTree()
const textbox = findByRole(tree, 'textbox')assert.ok(textbox, 'tree should have textbox')assert.strictEqual(textbox.name, 'Username')
const button = findByRole(tree, 'button')assert.ok(button, 'tree should have button')assert.strictEqual(button.name, 'Sign in')From Tree to Action
Section titled “From Tree to Action”The accessibility tree tells you what’s on the page. You can then use find() to locate and interact with those elements.
Semantic selectors
Section titled “Semantic selectors”find() accepts semantic options that correspond to what you see in the tree:
// Tree shows: { role: "button", name: "Sign in" }// The name comes from aria-label, so use label:vibe.find({ role: 'button', label: 'Sign in' }).click()
// For buttons/links where the name comes from text content, use text:vibe.find({ role: 'button', text: 'Submit' }).click()Which parameter maps to the tree’s name? It depends on the source:
| Source of the name | find() parameter |
|---|---|
aria-label attribute | label |
aria-labelledby reference | label |
<label for="id"> element | label |
| Visible text content | text |
alt attribute (images) | alt |
placeholder attribute | placeholder |
title attribute | title |
await vibe.setContent(` <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>`)
await vibe.find({ role: 'button', label: 'Sign in' }).click()
const result = await vibe.find({ css: '#result' })assert.strictEqual(await result.text(), 'signed in')vibe.setContent(` <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>`)
vibe.find({ role: 'button', label: 'Sign in' }).click()
assert.strictEqual(vibe.find({ css: '#result' }).text(), 'signed in')await vibe.setContent(` <div id="result">waiting</div> <button onclick="document.getElementById('result').textContent='done'">Submit</button>`)
await vibe.find({ role: 'button', text: 'Submit' }).click()
const result = await vibe.find({ css: '#result' })assert.strictEqual(await result.text(), 'done')vibe.setContent(` <div id="result">waiting</div> <button onclick="document.getElementById('result').textContent='done'">Submit</button>`)
vibe.find({ role: 'button', text: 'Submit' }).click()
assert.strictEqual(vibe.find({ css: '#result' }).text(), 'done')CSS selectors
Section titled “CSS selectors”CSS selectors always work for both finding and reading element state:
await vibe.setContent(` <label for="user">Username</label> <input id="user" type="text" />`)
await vibe.find({ css: '#user' }).fill('alice')
const input = await vibe.find({ css: '#user' })assert.strictEqual(await input.value(), 'alice')vibe.setContent(` <label for="user">Username</label> <input id="user" type="text" />`)
vibe.find({ css: '#user' }).fill('alice')
assert.strictEqual(vibe.find({ css: '#user' }).value(), 'alice')await vibe.setContent('<h1>Welcome</h1>')
const heading = await vibe.find({ css: 'h1' })assert.strictEqual(await heading.text(), 'Welcome')vibe.setContent('<h1>Welcome</h1>')
assert.strictEqual(vibe.find({ css: 'h1' }).text(), 'Welcome')Using tree data in code
Section titled “Using tree data in code”You can read the tree programmatically and use its data to drive actions — useful for scripts and AI agents that discover page structure at runtime.
await vibe.setContent(` <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>`)
const tree = await vibe.a11yTree()
// Discover the button's name from the tree, then click itconst btn = findByRole(tree, 'button')assert.ok(btn, 'tree should contain a button')assert.strictEqual(btn.name, 'Sign in')
await vibe.find({ role: 'button', label: btn.name }).click()
const result = await vibe.find({ css: '#result' })assert.strictEqual(await result.text(), 'signed in')vibe.setContent(` <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>`)
const tree = vibe.a11yTree()
const btn = findByRole(tree, 'button')assert.ok(btn, 'tree should contain a button')assert.strictEqual(btn.name, 'Sign in')
vibe.find({ role: 'button', label: btn.name }).click()assert.strictEqual(vibe.find({ css: '#result' }).text(), 'signed in')The tree also exposes element state. For example, you can check whether a checkbox is already checked:
await vibe.setContent(` <label><input type="checkbox" checked /> Remember me</label>`)
const tree = await vibe.a11yTree()
const checkbox = findByRole(tree, 'checkbox')assert.ok(checkbox, 'tree should contain a checkbox')assert.strictEqual(checkbox.checked, true, 'checkbox should be checked')You can use the tree state to decide whether to click:
await vibe.setContent('<input type="checkbox" aria-label="Remember me" />')
const tree = await vibe.a11yTree()const checkbox = findByRole(tree, 'checkbox')assert.ok(checkbox, 'tree should contain a checkbox')assert.strictEqual(checkbox.checked, false, 'should start unchecked')
if (!checkbox.checked) { await vibe.find({ role: 'checkbox', label: checkbox.name }).click()}
const tree2 = await vibe.a11yTree()const checkbox2 = findByRole(tree2, 'checkbox')assert.strictEqual(checkbox2.checked, true, 'should now be checked')vibe.setContent('<input type="checkbox" aria-label="Remember me" />')
const tree = vibe.a11yTree()const checkbox = findByRole(tree, 'checkbox')assert.strictEqual(checkbox.checked, false)
if (!checkbox.checked) { vibe.find({ role: 'checkbox', label: checkbox.name }).click()}
const tree2 = vibe.a11yTree()const checkbox2 = findByRole(tree2, 'checkbox')assert.strictEqual(checkbox2.checked, true)Scoping with root
Section titled “Scoping with root”On complex pages, the full tree can be large. Use root to inspect just one section:
await vibe.setContent(` <h1>Title</h1> <nav><a href="/a">Link A</a><a href="/b">Link B</a></nav>`)
const navTree = await vibe.a11yTree({ root: 'nav' })
const roles = collectRoles(navTree)assert.ok(roles.includes('link'), 'nav tree should include links')assert.ok(!roles.includes('heading'), 'nav tree should not include heading outside root')vibe.setContent(` <h1>Title</h1> <nav><a href="/a">Link A</a></nav>`)
const navTree = vibe.a11yTree({ root: 'nav' })
const roles = collectRoles(navTree)assert.ok(roles.includes('link'), 'nav tree should include links')assert.ok(!roles.includes('heading'), 'should not include heading outside root')The root parameter accepts a CSS selector. The tree will only include that element and its descendants.
Filtering with everything
Section titled “Filtering with everything”By default, a11yTree() hides generic container nodes (divs, spans with no semantic role). This keeps the output focused on meaningful elements.
Set everything: true to see all nodes:
await vibe.setContent('<div><span>hello</span></div>')
const fullTree = await vibe.a11yTree({ everything: true })assert.ok(collectRoles(fullTree).includes('generic'), 'should include generic nodes')vibe.setContent('<div><span>hello</span></div>')
const fullTree = vibe.a11yTree({ everything: true })assert.ok(collectRoles(fullTree).includes('generic'), 'should include generic nodes')await vibe.setContent('<div><span>hello</span></div>')
const tree = await vibe.a11yTree()assert.ok(!collectRoles(tree).includes('generic'), 'should filter generic nodes')When to use everything: true:
- Debugging layout issues where you need to see the full DOM structure
- When elements you expect aren’t appearing in the default tree
When to keep the default:
- Most of the time — the filtered tree is much easier to read
- When looking for interactive elements (buttons, links, inputs)
Practical Workflow
Section titled “Practical Workflow”Here’s the full pattern: inspect the tree, then use what you learn to find and interact with elements.
Sync:
const { browser } = require('vibium/sync')
const bro = browser.start()const vibe = bro.page()
vibe.setContent(` <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>`)
// 1. Inspect the tree to understand the pageconst tree = vibe.a11yTree()
// 2. Find the button in the tree and read its namefunction findByRole(node, role) { if (node.role === role) return node for (const child of node.children || []) { const found = findByRole(child, role) if (found) return found } return null}const btn = findByRole(tree, 'button')console.log(`Found: ${btn.role} "${btn.name}"`) // Found: button "Sign in"
// 3. Fill inputs using CSS selectorsvibe.find({ css: '#user' }).fill('alice')
// 4. Click using the name discovered from the treevibe.find({ role: 'button', label: btn.name }).click()
// 5. Read state using CSS selectorsconsole.log('Heading:', vibe.find({ css: 'h1' }).text())
bro.stop()Async:
const { browser } = require('vibium')
async function main() { const bro = await browser.start() const vibe = await bro.page()
await vibe.setContent(` <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button> `)
// 1. Inspect the tree to understand the page const tree = await vibe.a11yTree()
// 2. Find the button in the tree and read its name function findByRole(node, role) { if (node.role === role) return node for (const child of node.children || []) { const found = findByRole(child, role) if (found) return found } return null } const btn = findByRole(tree, 'button') console.log(`Found: ${btn.role} "${btn.name}"`) // Found: button "Sign in"
// 3. Fill inputs using CSS selectors await vibe.find({ css: '#user' }).fill('alice')
// 4. Click using the name discovered from the tree await vibe.find({ role: 'button', label: btn.name }).click()
// 5. Read state using CSS selectors console.log('Heading:', await vibe.find({ css: 'h1' }).text())
await bro.stop()}
main()await vibe.setContent(` <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in" onclick="document.getElementById('user').value='submitted'">Log In</button>`)
const tree = await vibe.a11yTree()assert.strictEqual(tree.role, 'WebArea')
const btn = findByRole(tree, 'button')assert.strictEqual(btn.name, 'Sign in')
await vibe.find({ css: '#user' }).fill('alice')await vibe.find({ role: 'button', label: btn.name }).click()
const heading = await vibe.find({ css: 'h1' })assert.strictEqual(await heading.text(), 'Welcome')vibe.setContent(` <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>`)
const tree = vibe.a11yTree()assert.strictEqual(tree.role, 'WebArea')
const btn = findByRole(tree, 'button')
vibe.find({ css: '#user' }).fill('alice')vibe.find({ role: 'button', label: btn.name }).click()
assert.strictEqual(vibe.find({ css: 'h1' }).text(), 'Welcome')Reference
Section titled “Reference”a11yTree() Node Fields
Section titled “a11yTree() Node Fields”| Field | Type | Description |
|---|---|---|
role | string | ARIA role (e.g. “button”, “link”, “heading”) |
name | string | Accessible name (from aria-label, <label>, etc.) |
value | string | number | Current value (inputs, sliders) |
description | string | Accessible description |
children | A11yNode[] | Child nodes |
disabled | boolean | Whether the element is disabled |
checked | boolean | ‘mixed’ | Checkbox/radio state |
pressed | boolean | ‘mixed’ | Toggle button state |
selected | boolean | Whether the element is selected |
expanded | boolean | Whether a collapsible is open |
focused | boolean | Whether the element has focus |
required | boolean | Whether the field is required |
readonly | boolean | Whether the field is read-only |
level | number | Heading level (1-6) |
valuemin | number | Minimum value (sliders, spinbuttons) |
valuemax | number | Maximum value (sliders, spinbuttons) |
find() Selector Options
Section titled “find() Selector Options”| Parameter | What it matches |
|---|---|
role | ARIA role |
text | Visible text content (innerText) |
label | Explicit label: aria-label, aria-labelledby, <label for> |
placeholder | Placeholder attribute |
alt | Alt attribute (images) |
title | Title attribute |
testid | data-testid attribute |
xpath | XPath expression |
near | CSS selector of a nearby element |
timeout | Max wait time in ms |
CSS vs Semantic Selectors
Section titled “CSS vs Semantic Selectors”| Use CSS selectors when… | Use semantic selectors when… |
|---|---|
| Reading element state (text, value, etc.) | Interacting (click, fill, check) |
| You know the exact HTML structure | Finding by role and label (like a user would) |
| Targeting by class name or ID | The HTML structure might change |
Troubleshooting
Section titled “Troubleshooting””Element not found” with label
Section titled “”Element not found” with label”label only matches explicit labelling mechanisms (aria-label, aria-labelledby, <label for>). It does not match text content. If the element’s name comes from its visible text (buttons, links, headings), use text instead:
// WRONG: "Submit" comes from text content, not aria-labelvibe.find({ role: 'button', label: 'Submit' })
// RIGHT: use text for text-content-derived namesvibe.find({ role: 'button', text: 'Submit' })Tree is too large
Section titled “Tree is too large”Use root to scope to a section:
const navTree = vibe.a11yTree({ root: 'nav' })Tree node has no name
Section titled “Tree node has no name”The name field only appears when the element has an explicit accessible name (via aria-label, <label>, alt, placeholder, or title). Elements whose name comes only from text content (like <h1>Title</h1>) may not show name in the tree. The tree still shows their role, which you can use with find().
Everything shows as “generic”
Section titled “Everything shows as “generic””Elements without semantic roles (plain divs, spans) appear as “generic” in the tree. This usually means the page lacks proper semantic HTML or ARIA attributes.
Python
Section titled “Python”Learn how to inspect page structure with a11y_tree() and use the results to find and interact with elements.
What You’ll Learn
Section titled “What You’ll Learn”- How to get a page’s accessibility tree
- How to use tree output to build selectors for
find() - Filtering with
everythingand scoping withroot - When to use semantic selectors vs CSS selectors
Getting the Tree
Section titled “Getting the Tree”a11y_tree() returns the page’s accessibility tree — a structured view of every element as assistive technology sees it.
Sync:
from vibium import browser
bro = browser.start()vibe = bro.page()vibe.go("https://example.com")
tree = vibe.a11y_tree()print(tree)
bro.stop()Async:
import asynciofrom vibium.async_api import browser
async def main(): bro = await browser.start() vibe = await bro.page() await vibe.go("https://example.com")
tree = await vibe.a11y_tree() print(tree)
await bro.stop()
asyncio.run(main())Here’s an example of what the tree looks like for a login form:
{ "role": "WebArea", "name": "Login", "children": [ {"role": "heading", "level": 1}, {"role": "textbox", "name": "Username"}, {"role": "textbox", "name": "Password"}, {"role": "checkbox", "name": "Remember me", "checked": False}, {"role": "button", "name": "Sign in"} ]}Each node has a role (what the element is). Nodes with explicit labels (aria-label, <label for>, etc.) also have a name. Some nodes have state properties like checked, disabled, or expanded.
Two helper functions used throughout this tutorial:
def find_by_role(node, role): if node["role"] == role: return node for child in node.get("children", []): found = find_by_role(child, role) if found: return found return None
def collect_roles(node): roles = [node["role"]] for child in node.get("children", []): roles.extend(collect_roles(child)) return rolesawait vibe.set_content(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>""")
tree = await vibe.a11y_tree()
assert tree["role"] == "WebArea"assert isinstance(tree.get("children"), list), "tree should have children"
roles = collect_roles(tree)assert "heading" in roles, "should have heading"assert "textbox" in roles, "should have textbox"assert "button" in roles, "should have button"vibe.set_content(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>""")
tree = vibe.a11y_tree()
assert tree["role"] == "WebArea"assert isinstance(tree.get("children"), list), "tree should have children"await vibe.set_content(""" <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>""")
tree = await vibe.a11y_tree()
textbox = find_by_role(tree, "textbox")assert textbox, "tree should have textbox"assert textbox["name"] == "Username"
button = find_by_role(tree, "button")assert button, "tree should have button"assert button["name"] == "Sign in"From Tree to Action
Section titled “From Tree to Action”The accessibility tree tells you what’s on the page. You can then use find() to locate and interact with those elements.
Semantic selectors
Section titled “Semantic selectors”find() accepts semantic keyword arguments that correspond to what you see in the tree:
# Tree shows: {"role": "button", "name": "Sign in"}# The name comes from aria-label, so use label:vibe.find(role="button", label="Sign in").click()
# For buttons/links where the name comes from text content, use text:vibe.find(role="button", text="Submit").click()Which parameter maps to the tree’s name? It depends on the source:
| Source of the name | find() parameter |
|---|---|
aria-label attribute | label |
aria-labelledby reference | label |
<label for="id"> element | label |
| Visible text content | text |
alt attribute (images) | alt |
placeholder attribute | placeholder |
title attribute | title |
await vibe.set_content(""" <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>""")
el = await vibe.find(role="button", label="Sign in")await el.click()
result = await vibe.find(css="#result")assert await result.text() == "signed in"vibe.set_content(""" <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>""")
vibe.find(role="button", label="Sign in").click()
assert vibe.find(css="#result").text() == "signed in"await vibe.set_content(""" <div id="result">waiting</div> <button onclick="document.getElementById('result').textContent='done'">Submit</button>""")
el = await vibe.find(role="button", text="Submit")await el.click()
result = await vibe.find(css="#result")assert await result.text() == "done"vibe.set_content(""" <div id="result">waiting</div> <button onclick="document.getElementById('result').textContent='done'">Submit</button>""")
vibe.find(role="button", text="Submit").click()
assert vibe.find(css="#result").text() == "done"CSS selectors
Section titled “CSS selectors”CSS selectors always work for both finding and reading element state:
await vibe.set_content(""" <label for="user">Username</label> <input id="user" type="text" />""")
inp = await vibe.find(css="#user")await inp.fill("alice")
inp = await vibe.find(css="#user")assert await inp.value() == "alice"vibe.set_content(""" <label for="user">Username</label> <input id="user" type="text" />""")
vibe.find(css="#user").fill("alice")
assert vibe.find(css="#user").value() == "alice"await vibe.set_content("<h1>Welcome</h1>")
heading = await vibe.find(css="h1")assert await heading.text() == "Welcome"vibe.set_content("<h1>Welcome</h1>")
assert vibe.find(css="h1").text() == "Welcome"Using tree data in code
Section titled “Using tree data in code”You can read the tree programmatically and use its data to drive actions — useful for scripts and AI agents that discover page structure at runtime.
await vibe.set_content(""" <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>""")
tree = await vibe.a11y_tree()
# Discover the button's name from the tree, then click itbtn = find_by_role(tree, "button")assert btn, "tree should contain a button"assert btn["name"] == "Sign in"
el = await vibe.find(role="button", label=btn["name"])await el.click()
result = await vibe.find(css="#result")assert await result.text() == "signed in"vibe.set_content(""" <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button>""")
tree = vibe.a11y_tree()
btn = find_by_role(tree, "button")assert btn, "tree should contain a button"assert btn["name"] == "Sign in"
vibe.find(role="button", label=btn["name"]).click()assert vibe.find(css="#result").text() == "signed in"The tree also exposes element state. For example, you can check whether a checkbox is already checked:
await vibe.set_content(""" <label><input type="checkbox" checked /> Remember me</label>""")
tree = await vibe.a11y_tree()
checkbox = find_by_role(tree, "checkbox")assert checkbox, "tree should contain a checkbox"assert checkbox.get("checked") is True, "checkbox should be checked"You can use the tree state to decide whether to click:
await vibe.set_content('<input type="checkbox" aria-label="Remember me" />')
tree = await vibe.a11y_tree()checkbox = find_by_role(tree, "checkbox")assert checkbox, "tree should contain a checkbox"assert checkbox.get("checked") is False, "should start unchecked"
if not checkbox.get("checked"): el = await vibe.find(role="checkbox", label=checkbox["name"]) await el.click()
tree2 = await vibe.a11y_tree()checkbox2 = find_by_role(tree2, "checkbox")assert checkbox2.get("checked") is True, "should now be checked"vibe.set_content('<input type="checkbox" aria-label="Remember me" />')
tree = vibe.a11y_tree()checkbox = find_by_role(tree, "checkbox")assert checkbox.get("checked") is False
if not checkbox.get("checked"): vibe.find(role="checkbox", label=checkbox["name"]).click()
tree2 = vibe.a11y_tree()checkbox2 = find_by_role(tree2, "checkbox")assert checkbox2.get("checked") is TrueScoping with root
Section titled “Scoping with root”On complex pages, the full tree can be large. Use root to inspect just one section:
await vibe.set_content(""" <h1>Title</h1> <nav><a href="/a">Link A</a><a href="/b">Link B</a></nav>""")
nav_tree = await vibe.a11y_tree(root="nav")
roles = collect_roles(nav_tree)assert "link" in roles, "nav tree should include links"assert "heading" not in roles, "nav tree should not include heading outside root"vibe.set_content(""" <h1>Title</h1> <nav><a href="/a">Link A</a></nav>""")
nav_tree = vibe.a11y_tree(root="nav")
roles = collect_roles(nav_tree)assert "link" in roles, "nav tree should include links"assert "heading" not in roles, "should not include heading outside root"The root parameter accepts a CSS selector. The tree will only include that element and its descendants.
Filtering with everything
Section titled “Filtering with everything”By default, a11y_tree() hides generic container nodes (divs, spans with no semantic role). This keeps the output focused on meaningful elements.
Set everything=True to see all nodes:
await vibe.set_content("<div><span>hello</span></div>")
full_tree = await vibe.a11y_tree(everything=True)assert "generic" in collect_roles(full_tree), "should include generic nodes"vibe.set_content("<div><span>hello</span></div>")
full_tree = vibe.a11y_tree(everything=True)assert "generic" in collect_roles(full_tree), "should include generic nodes"await vibe.set_content("<div><span>hello</span></div>")
tree = await vibe.a11y_tree()assert "generic" not in collect_roles(tree), "should filter generic nodes"When to use everything=True:
- Debugging layout issues where you need to see the full DOM structure
- When elements you expect aren’t appearing in the default tree
When to keep the default:
- Most of the time — the filtered tree is much easier to read
- When looking for interactive elements (buttons, links, inputs)
Practical Workflow
Section titled “Practical Workflow”Here’s the full pattern: inspect the tree, then use what you learn to find and interact with elements.
Sync:
from vibium import browser
bro = browser.start()vibe = bro.page()
vibe.set_content(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>""")
# 1. Inspect the tree to understand the pagetree = vibe.a11y_tree()
# 2. Find the button in the tree and read its namedef find_by_role(node, role): if node["role"] == role: return node for child in node.get("children", []): found = find_by_role(child, role) if found: return found return None
btn = find_by_role(tree, "button")print(f'Found: {btn["role"]} "{btn["name"]}"') # Found: button "Sign in"
# 3. Fill inputs using CSS selectorsvibe.find(css="#user").fill("alice")
# 4. Click using the name discovered from the treevibe.find(role="button", label=btn["name"]).click()
# 5. Read state using CSS selectorsprint("Heading:", vibe.find(css="h1").text())
bro.stop()Async:
import asynciofrom vibium.async_api import browser
async def main(): bro = await browser.start() vibe = await bro.page()
await vibe.set_content(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button> """)
# 1. Inspect the tree to understand the page tree = await vibe.a11y_tree()
# 2. Find the button in the tree and read its name def find_by_role(node, role): if node["role"] == role: return node for child in node.get("children", []): found = find_by_role(child, role) if found: return found return None
btn = find_by_role(tree, "button") print(f'Found: {btn["role"]} "{btn["name"]}"')
# 3. Fill inputs using CSS selectors inp = await vibe.find(css="#user") await inp.fill("alice")
# 4. Click using the name discovered from the tree el = await vibe.find(role="button", label=btn["name"]) await el.click()
# 5. Read state using CSS selectors heading = await vibe.find(css="h1") print("Heading:", await heading.text())
await bro.stop()
asyncio.run(main())await vibe.set_content(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in" onclick="document.getElementById('user').value='submitted'">Log In</button>""")
tree = await vibe.a11y_tree()assert tree["role"] == "WebArea"
btn = find_by_role(tree, "button")assert btn["name"] == "Sign in"
inp = await vibe.find(css="#user")await inp.fill("alice")el = await vibe.find(role="button", label=btn["name"])await el.click()
heading = await vibe.find(css="h1")assert await heading.text() == "Welcome"vibe.set_content(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button>""")
tree = vibe.a11y_tree()assert tree["role"] == "WebArea"
btn = find_by_role(tree, "button")
vibe.find(css="#user").fill("alice")vibe.find(role="button", label=btn["name"]).click()
assert vibe.find(css="h1").text() == "Welcome"Reference
Section titled “Reference”a11y_tree() Node Fields
Section titled “a11y_tree() Node Fields”The return value is a dict. Possible keys:
| Field | Type | Description |
|---|---|---|
role | str | ARIA role (e.g. “button”, “link”, “heading”) |
name | str | Accessible name (from aria-label, <label>, etc.) |
value | str | int | float | Current value (inputs, sliders) |
description | str | Accessible description |
children | list[dict] | Child nodes |
disabled | bool | Whether the element is disabled |
checked | bool | “mixed” | Checkbox/radio state |
pressed | bool | “mixed” | Toggle button state |
selected | bool | Whether the element is selected |
expanded | bool | Whether a collapsible is open |
focused | bool | Whether the element has focus |
required | bool | Whether the field is required |
readonly | bool | Whether the field is read-only |
level | int | Heading level (1-6) |
valuemin | int | float | Minimum value (sliders, spinbuttons) |
valuemax | int | float | Maximum value (sliders, spinbuttons) |
find() Keyword Arguments
Section titled “find() Keyword Arguments”| Parameter | What it matches |
|---|---|
role | ARIA role |
text | Visible text content (innerText) |
label | Explicit label: aria-label, aria-labelledby, <label for> |
placeholder | Placeholder attribute |
alt | Alt attribute (images) |
title | Title attribute |
testid | data-testid attribute |
xpath | XPath expression |
near | CSS selector of a nearby element |
timeout | Max wait time in ms |
CSS vs Semantic Selectors
Section titled “CSS vs Semantic Selectors”| Use CSS selectors when… | Use semantic selectors when… |
|---|---|
| Reading element state (text, value, etc.) | Interacting (click, fill, check) |
| You know the exact HTML structure | Finding by role and label (like a user would) |
| Targeting by class name or ID | The HTML structure might change |
Troubleshooting
Section titled “Troubleshooting””Element not found” with label
Section titled “”Element not found” with label”label only matches explicit labelling mechanisms (aria-label, aria-labelledby, <label for>). It does not match text content. If the element’s name comes from its visible text (buttons, links, headings), use text instead:
# WRONG: "Submit" comes from text content, not aria-labelvibe.find(role="button", label="Submit")
# RIGHT: use text for text-content-derived namesvibe.find(role="button", text="Submit")Tree is too large
Section titled “Tree is too large”Use root to scope to a section:
nav_tree = vibe.a11y_tree(root="nav")Tree node has no name
Section titled “Tree node has no name”The name field only appears when the element has an explicit accessible name (via aria-label, <label>, alt, placeholder, or title). Elements whose name comes only from text content (like <h1>Title</h1>) may not show name in the tree. The tree still shows their role, which you can use with find().
Everything shows as “generic”
Section titled “Everything shows as “generic””Elements without semantic roles (plain divs, spans) appear as “generic” in the tree. This usually means the page lacks proper semantic HTML or ARIA attributes.
Python-specific notes
Section titled “Python-specific notes”- Method name is
a11y_tree()(snake_case), nota11yTree() - The tree is a Python dict, not a JavaScript object — access fields with
tree["role"], nottree.role
Learn how to inspect page structure with a11yTree() and use the results to find and interact with elements.
What You’ll Learn
Section titled “What You’ll Learn”- How to get a page’s accessibility tree
- How to use tree output to build selectors for
find() - Filtering with
everythingand scoping withroot - When to use semantic selectors vs CSS selectors
Getting the Tree
Section titled “Getting the Tree”a11yTree() returns the page’s accessibility tree: a structured view of every element as assistive technology sees it.
import com.vibium.Vibium;import com.vibium.types.A11yNode;
public class Tree { public static void main(String[] args) { var bro = Vibium.start(); var vibe = bro.page(); vibe.go("https://example.com");
A11yNode tree = vibe.a11yTree(); System.out.println(tree.role()); // WebArea
bro.stop(); }}The tree is an A11yNode. Read it with accessor methods such as role(), name(), and children(). This helper prints one line per node:
static void printTree(A11yNode node, String indent) { StringBuilder line = new StringBuilder(indent + node.role()); if (node.name() != null && !node.name().isEmpty()) line.append(" name=\"").append(node.name()).append('"'); if (node.level() != null) line.append(" level=").append(node.level()); if (node.checked() != null) line.append(" checked=").append(node.checked()); System.out.println(line); if (node.children() != null) { for (A11yNode child : node.children()) { printTree(child, indent + " "); } }}For a login form it prints:
WebArea name="Login" heading name="Login" level=1 textbox name="Username" textbox name="Password" checkbox name="Remember me" checked=false button name="Sign in"Each node has a role() (what the element is). Nodes with explicit labels (aria-label, <label for>, etc.) also have a name(). Some nodes have state such as checked(), disabled(), or expanded(). An accessor returns null when the node does not have that property, and children() is null for a node with no children.
Two helper methods used throughout this tutorial:
static A11yNode findByRole(A11yNode node, String role) { if (role.equals(node.role())) { return node; } if (node.children() != null) { for (A11yNode child : node.children()) { A11yNode found = findByRole(child, role); if (found != null) { return found; } } } return null;}
static List<String> collectRoles(A11yNode node) { List<String> roles = new ArrayList<>(); roles.add(node.role()); if (node.children() != null) { for (A11yNode child : node.children()) { roles.addAll(collectRoles(child)); } } return roles;}The examples below assume these imports:
import com.vibium.types.A11yNode;import com.vibium.types.A11yOptions;import com.vibium.types.SelectorOptions;import java.util.ArrayList;import java.util.List;vibe.setContent(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button> """);
A11yNode tree = vibe.a11yTree();
tree.role(); // "WebArea"collectRoles(tree); // [WebArea, heading, textbox, button]
findByRole(tree, "textbox").name(); // "Username"findByRole(tree, "button").name(); // "Sign in"From Tree to Action
Section titled “From Tree to Action”The accessibility tree tells you what’s on the page. You can then use find() to locate and interact with those elements.
Semantic selectors
Section titled “Semantic selectors”find() takes a SelectorOptions whose builder methods correspond to what you see in the tree:
// Tree shows: button name="Sign in"// The name comes from aria-label, so use label:vibe.find(new SelectorOptions().role("button").label("Sign in")).click();
// For buttons/links where the name comes from text content, use text:vibe.find(new SelectorOptions().role("button").text("Submit")).click();Which method maps to the tree’s name()? It depends on the source:
| Source of the name | SelectorOptions method |
|---|---|
aria-label attribute | label |
aria-labelledby reference | label |
<label for="id"> element | label |
| Visible text content | text |
alt attribute (images) | alt |
placeholder attribute | placeholder |
title attribute | title |
vibe.setContent(""" <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button> """);
vibe.find(new SelectorOptions().role("button").label("Sign in")).click();
vibe.find(new SelectorOptions().css("#result")).text(); // "signed in"vibe.setContent(""" <div id="result">waiting</div> <button onclick="document.getElementById('result').textContent='done'">Submit</button> """);
vibe.find(new SelectorOptions().role("button").text("Submit")).click();
vibe.find(new SelectorOptions().css("#result")).text(); // "done"CSS selectors
Section titled “CSS selectors”CSS selectors always work for both finding and reading element state:
vibe.setContent(""" <label for="user">Username</label> <input id="user" type="text" /> """);
vibe.find(new SelectorOptions().css("#user")).fill("alice");
vibe.find(new SelectorOptions().css("#user")).value(); // "alice"vibe.setContent("<h1>Welcome</h1>");
vibe.find(new SelectorOptions().css("h1")).text(); // "Welcome"Using tree data in code
Section titled “Using tree data in code”You can read the tree programmatically and use its data to drive actions. This is useful for scripts and AI agents that discover page structure at runtime.
vibe.setContent(""" <div id="result">not clicked</div> <button aria-label="Sign in" onclick="document.getElementById('result').textContent='signed in'">Log In</button> """);
A11yNode btn = findByRole(vibe.a11yTree(), "button");btn.name(); // "Sign in"
vibe.find(new SelectorOptions().role("button").label(btn.name())).click();vibe.find(new SelectorOptions().css("#result")).text(); // "signed in"The tree also exposes element state. checked() returns a string: "true", "false", or "mixed". You can use it to decide whether to click:
vibe.setContent("<input type=\"checkbox\" aria-label=\"Remember me\" />");
A11yNode checkbox = findByRole(vibe.a11yTree(), "checkbox");checkbox.checked(); // "false"
if (!"true".equals(checkbox.checked())) { vibe.find(new SelectorOptions().role("checkbox").label(checkbox.name())).click();}
findByRole(vibe.a11yTree(), "checkbox").checked(); // "true"Scoping with root
Section titled “Scoping with root”On complex pages, the full tree can be large. Use root to inspect just one section:
vibe.setContent(""" <h1>Title</h1> <nav><a href="/a">Link A</a></nav> """);
A11yNode navTree = vibe.a11yTree(new A11yOptions().root("nav"));
collectRoles(navTree); // [WebArea, link], no headingroot accepts a CSS selector. The tree will only include that element and its descendants.
Filtering with everything
Section titled “Filtering with everything”By default, a11yTree() hides generic container nodes (divs, spans with no semantic role). This keeps the output focused on meaningful elements.
Set everything(true) to see all nodes:
vibe.setContent("<div><span>hello</span></div>");
A11yNode fullTree = vibe.a11yTree(new A11yOptions().everything(true));collectRoles(fullTree).contains("generic"); // truecollectRoles(vibe.a11yTree()).contains("generic"); // falseWhen to use everything(true):
- Debugging layout issues where you need to see the full DOM structure
- When elements you expect aren’t appearing in the default tree
When to keep the default:
- Most of the time. The filtered tree is much easier to read
- When looking for interactive elements (buttons, links, inputs)
Practical Workflow
Section titled “Practical Workflow”Here’s the full pattern: inspect the tree, then use what you learn to find and interact with elements.
import com.vibium.Vibium;import com.vibium.types.A11yNode;import com.vibium.types.SelectorOptions;
public class Workflow { static A11yNode findByRole(A11yNode node, String role) { if (role.equals(node.role())) { return node; } if (node.children() != null) { for (A11yNode child : node.children()) { A11yNode found = findByRole(child, role); if (found != null) { return found; } } } return null; }
public static void main(String[] args) { var bro = Vibium.start(); var vibe = bro.page();
vibe.setContent(""" <h1>Welcome</h1> <label for="user">Username</label> <input id="user" type="text" /> <button aria-label="Sign in">Log In</button> """);
// 1. Inspect the tree to understand the page A11yNode tree = vibe.a11yTree();
// 2. Find the button in the tree and read its name A11yNode btn = findByRole(tree, "button"); System.out.println("Found: " + btn.role() + " \"" + btn.name() + "\""); // Found: button "Sign in"
// 3. Fill inputs using CSS selectors vibe.find(new SelectorOptions().css("#user")).fill("alice");
// 4. Click using the name discovered from the tree vibe.find(new SelectorOptions().role("button").label(btn.name())).click();
// 5. Read state using CSS selectors System.out.println("Heading: " + vibe.find(new SelectorOptions().css("h1")).text()); // Heading: Welcome
bro.stop(); }}Reference
Section titled “Reference”A11yNode Accessors
Section titled “A11yNode Accessors”a11yTree() returns an A11yNode. Each accessor returns null when the node does not have that property.
| Accessor | Type | Description |
|---|---|---|
role() | String | ARIA role (e.g. “button”, “link”, “heading”) |
name() | String | Accessible name (from aria-label, <label>, etc.) |
value() | String | Current value (inputs, sliders) |
description() | String | Accessible description |
children() | List<A11yNode> | Child nodes, or null when there are none |
disabled() | Boolean | Whether the element is disabled |
checked() | String | Checkbox/radio state: “true”, “false”, or “mixed” |
pressed() | Boolean | Toggle button state |
selected() | Boolean | Whether the element is selected |
expanded() | Boolean | Whether a collapsible is open |
focused() | Boolean | Whether the element has focus |
multiselectable() | Boolean | Whether more than one item can be selected |
level() | Integer | Heading level (1-6) |
SelectorOptions Methods
Section titled “SelectorOptions Methods”| Method | What it matches |
|---|---|
role | ARIA role |
text | Visible text content (innerText) |
label | Explicit label: aria-label, aria-labelledby, <label for> |
placeholder | Placeholder attribute |
alt | Alt attribute (images) |
title | Title attribute |
testid | data-testid attribute |
xpath | XPath expression |
near | CSS selector of a nearby element |
css | CSS selector |
timeout | Max wait time in ms |
CSS vs Semantic Selectors
Section titled “CSS vs Semantic Selectors”| Use CSS selectors when… | Use semantic selectors when… |
|---|---|
| Reading element state (text, value, etc.) | Interacting (click, fill, check) |
| You know the exact HTML structure | Finding by role and label (like a user would) |
| Targeting by class name or ID | The HTML structure might change |
Troubleshooting
Section titled “Troubleshooting””Element not found” with label
Section titled “”Element not found” with label”label only matches explicit labelling mechanisms (aria-label, aria-labelledby, <label for>). It does not match text content. If the element’s name comes from its visible text (buttons, links, headings), use text instead:
// WRONG: "Submit" comes from text content, not aria-label.// Throws ElementNotFoundException.vibe.find(new SelectorOptions().role("button").label("Submit"));
// RIGHT: use text for text-content-derived namesvibe.find(new SelectorOptions().role("button").text("Submit"));Tree is too large
Section titled “Tree is too large”Use root to scope to a section:
A11yNode navTree = vibe.a11yTree(new A11yOptions().root("nav"));Everything shows as “generic”
Section titled “Everything shows as “generic””Elements without semantic roles (plain divs, spans) appear as “generic” in the tree. This usually means the page lacks proper semantic HTML or ARIA attributes.
Java-specific notes
Section titled “Java-specific notes”- Options are builder objects:
new A11yOptions().root("nav"),new SelectorOptions().role("button") - The tree is an
A11yNode. Read fields with accessor methods (tree.role()), not field access checked()is a String, so compare with"true".equals(node.checked())children()isnullfor a leaf node, so check before iterating