Skip to content

Finding Elements with the Accessibility Tree

Learn how to inspect page structure with a11yTree() and use the results to find and interact with elements.


  • How to get a page’s accessibility tree
  • How to use tree output to build selectors for find()
  • everything and root options
  • When to use semantic selectors vs CSS selectors

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')

The accessibility tree tells you what’s on the page. You can then use find() to locate and interact with those elements.

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 namefind() parameter
aria-label attributelabel
aria-labelledby referencelabel
<label for="id"> elementlabel
Visible text contenttext
alt attribute (images)alt
placeholder attributeplaceholder
title attributetitle
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 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')

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 it
const 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)

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.


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)

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 page
const tree = 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
vibe.find({ css: '#user' }).fill('alice')
// 4. Click using the name discovered from the tree
vibe.find({ role: 'button', label: btn.name }).click()
// 5. Read state using CSS selectors
console.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')

FieldTypeDescription
rolestringARIA role (e.g. “button”, “link”, “heading”)
namestringAccessible name (from aria-label, <label>, etc.)
valuestring | numberCurrent value (inputs, sliders)
descriptionstringAccessible description
childrenA11yNode[]Child nodes
disabledbooleanWhether the element is disabled
checkedboolean | ‘mixed’Checkbox/radio state
pressedboolean | ‘mixed’Toggle button state
selectedbooleanWhether the element is selected
expandedbooleanWhether a collapsible is open
focusedbooleanWhether the element has focus
requiredbooleanWhether the field is required
readonlybooleanWhether the field is read-only
levelnumberHeading level (1-6)
valueminnumberMinimum value (sliders, spinbuttons)
valuemaxnumberMaximum value (sliders, spinbuttons)
ParameterWhat it matches
roleARIA role
textVisible text content (innerText)
labelExplicit label: aria-label, aria-labelledby, <label for>
placeholderPlaceholder attribute
altAlt attribute (images)
titleTitle attribute
testiddata-testid attribute
xpathXPath expression
nearCSS selector of a nearby element
timeoutMax wait time in ms
Use CSS selectors when…Use semantic selectors when…
Reading element state (text, value, etc.)Interacting (click, fill, check)
You know the exact HTML structureFinding by role and label (like a user would)
Targeting by class name or IDThe HTML structure might change

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
vibe.find({ role: 'button', label: 'Submit' })
// RIGHT: use text for text-content-derived names
vibe.find({ role: 'button', text: 'Submit' })

Use root to scope to a section:

const navTree = vibe.a11yTree({ root: 'nav' })

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().

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.

Learn how to inspect page structure with a11y_tree() and use the results to find and interact with elements.


  • How to get a page’s accessibility tree
  • How to use tree output to build selectors for find()
  • Filtering with everything and scoping with root
  • When to use semantic selectors vs CSS selectors

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 asyncio
from 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 roles
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>
""")
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"

The accessibility tree tells you what’s on the page. You can then use find() to locate and interact with those elements.

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 namefind() parameter
aria-label attributelabel
aria-labelledby referencelabel
<label for="id"> elementlabel
Visible text contenttext
alt attribute (images)alt
placeholder attributeplaceholder
title attributetitle
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 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"

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 it
btn = 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 True

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.


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)

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 page
tree = 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"]}"') # Found: button "Sign in"
# 3. Fill inputs using CSS selectors
vibe.find(css="#user").fill("alice")
# 4. Click using the name discovered from the tree
vibe.find(role="button", label=btn["name"]).click()
# 5. Read state using CSS selectors
print("Heading:", vibe.find(css="h1").text())
bro.stop()

Async:

import asyncio
from 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"

The return value is a dict. Possible keys:

FieldTypeDescription
rolestrARIA role (e.g. “button”, “link”, “heading”)
namestrAccessible name (from aria-label, <label>, etc.)
valuestr | int | floatCurrent value (inputs, sliders)
descriptionstrAccessible description
childrenlist[dict]Child nodes
disabledboolWhether the element is disabled
checkedbool | “mixed”Checkbox/radio state
pressedbool | “mixed”Toggle button state
selectedboolWhether the element is selected
expandedboolWhether a collapsible is open
focusedboolWhether the element has focus
requiredboolWhether the field is required
readonlyboolWhether the field is read-only
levelintHeading level (1-6)
valueminint | floatMinimum value (sliders, spinbuttons)
valuemaxint | floatMaximum value (sliders, spinbuttons)
ParameterWhat it matches
roleARIA role
textVisible text content (innerText)
labelExplicit label: aria-label, aria-labelledby, <label for>
placeholderPlaceholder attribute
altAlt attribute (images)
titleTitle attribute
testiddata-testid attribute
xpathXPath expression
nearCSS selector of a nearby element
timeoutMax wait time in ms
Use CSS selectors when…Use semantic selectors when…
Reading element state (text, value, etc.)Interacting (click, fill, check)
You know the exact HTML structureFinding by role and label (like a user would)
Targeting by class name or IDThe HTML structure might change

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
vibe.find(role="button", label="Submit")
# RIGHT: use text for text-content-derived names
vibe.find(role="button", text="Submit")

Use root to scope to a section:

nav_tree = vibe.a11y_tree(root="nav")

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().

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.

  • Method name is a11y_tree() (snake_case), not a11yTree()
  • The tree is a Python dict, not a JavaScript object — access fields with tree["role"], not tree.role

Learn how to inspect page structure with a11yTree() and use the results to find and interact with elements.


  • How to get a page’s accessibility tree
  • How to use tree output to build selectors for find()
  • Filtering with everything and scoping with root
  • When to use semantic selectors vs CSS selectors

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"

The accessibility tree tells you what’s on the page. You can then use find() to locate and interact with those elements.

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 nameSelectorOptions method
aria-label attributelabel
aria-labelledby referencelabel
<label for="id"> elementlabel
Visible text contenttext
alt attribute (images)alt
placeholder attributeplaceholder
title attributetitle
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 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"

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"

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 heading

root accepts a CSS selector. The tree will only include that element and its descendants.


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"); // true
collectRoles(vibe.a11yTree()).contains("generic"); // false

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)

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();
}
}

a11yTree() returns an A11yNode. Each accessor returns null when the node does not have that property.

AccessorTypeDescription
role()StringARIA role (e.g. “button”, “link”, “heading”)
name()StringAccessible name (from aria-label, <label>, etc.)
value()StringCurrent value (inputs, sliders)
description()StringAccessible description
children()List<A11yNode>Child nodes, or null when there are none
disabled()BooleanWhether the element is disabled
checked()StringCheckbox/radio state: “true”, “false”, or “mixed”
pressed()BooleanToggle button state
selected()BooleanWhether the element is selected
expanded()BooleanWhether a collapsible is open
focused()BooleanWhether the element has focus
multiselectable()BooleanWhether more than one item can be selected
level()IntegerHeading level (1-6)
MethodWhat it matches
roleARIA role
textVisible text content (innerText)
labelExplicit label: aria-label, aria-labelledby, <label for>
placeholderPlaceholder attribute
altAlt attribute (images)
titleTitle attribute
testiddata-testid attribute
xpathXPath expression
nearCSS selector of a nearby element
cssCSS selector
timeoutMax wait time in ms
Use CSS selectors when…Use semantic selectors when…
Reading element state (text, value, etc.)Interacting (click, fill, check)
You know the exact HTML structureFinding by role and label (like a user would)
Targeting by class name or IDThe HTML structure might change

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 names
vibe.find(new SelectorOptions().role("button").text("Submit"));

Use root to scope to a section:

A11yNode navTree = vibe.a11yTree(new A11yOptions().root("nav"));

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.

  • 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() is null for a leaf node, so check before iterating