Skip to content

Selectors

How vibium turns a selector into an element. Three kinds: CSS, pierce combinators for shadow DOM, and semantic locators.

find is the exception among selector-taking commands: its bare string is a natural-language description, and CSS is explicit (vibium find css ..., find({ css }), find(css=...)). It also takes a reference image. See Vibium Find: Natural Language by Default. click, fill, count, and the rest take the selectors below as before.

For which commands accept a selector, see API Reference.


Any CSS selector the browser accepts.

CLI
vibium find css "button.primary"
vibium find css "#login input[type=password]"
vibium click "nav a:nth-child(2)"
JavaScript
await vibe.find({ css: 'button.primary' });
Python
vibe.find(css="button.primary")
Java
vibe.find(new SelectorOptions().css("button.primary"));

CSS selectors do not cross shadow boundaries. Use a pierce combinator for that.


Shadow roots are invisible to querySelector, so a component’s internals need an explicit hop.

CombinatorMeaning
>>Cross one shadow boundary — the host’s own shadow root
>>>Cross any depth of nested shadow roots below the host
CLI
# <my-card> has a shadow root containing <p>shadow text</p>
vibium find css "my-card >> p"
# <my-card> contains <nested-el>, which has its own shadow root
vibium find css "my-card >>> #deep"
JavaScript
const p = await vibe.find({ css: 'my-card >> p' });
const btn = await vibe.find({ css: 'outer-host >>> button' });
const all = await vibe.findAll({ css: 'my-card >> li' });
Python
p = vibe.find(css="my-card >> p")
btn = vibe.find(css="outer-host >>> button")
items = vibe.find_all(css="my-card >> li")
Java
Element p = vibe.find(new SelectorOptions().css("my-card >> p"));
Element btn = vibe.find(new SelectorOptions().css("outer-host >>> button"));
List<Element> all = vibe.findAll(new SelectorOptions().css("my-card >> li"));

The syntax matches Playwright (>>) and Selenium 4 (>>>).

Each combinator hops from the elements matched so far, so they can be chained:

app-shell >> side-nav >> button

Combinators may be mixed — outer >>> mid >> button searches deeply for mid, then takes exactly one hop into it.

Anywhere a selector is accepted — find, findAll, click, fill, text, is, and map --selector.

Terminal window
vibium fill "my-form >> #email" "a@b.com"
vibium click "my-form >> button"
vibium text "my-card >> p"
vibium map --selector "my-card >> .content"
  • A selector with no >> is passed straight to querySelectorAll, so ordinary CSS is unaffected.
  • Only open shadow roots are reachable. attachShadow({ mode: 'closed' }) hides its contents from any script, vibium included.
  • Whitespace is optional: my-card>>p and my-card >> p are the same.
  • > (CSS child) and >> (pierce) are distinct — div > p stays a normal CSS child selector.
  • vibium map traverses shadow roots automatically; you do not need a combinator to see component internals in its output.

Find by what an element is rather than where it sits. Available as find subcommands on the CLI and as an options object in the clients.

LocatorMatches
roleARIA role, explicit or implicit (<button> → button)
textVisible text content, substring match
labelAccessible name — aria-label, aria-labelledby, <label for>, or an input’s value for submit/reset/button
placeholderplaceholder attribute
altalt attribute
titletitle attribute
testiddata-testid attribute
xpathXPath expression
CLI
vibium find role button
vibium find role button --name "Log in"
vibium find text "Sign In"
vibium find testid "submit-btn"
JavaScript
await vibe.find({ role: 'button', label: 'Log in' });
await vibe.find({ testid: 'submit-btn' });
Python
vibe.find(role="button", label="Log in")
vibe.find(testid="submit-btn")
Java
vibe.find(new SelectorOptions().role("button").label("Log in"));
vibe.find(new SelectorOptions().testid("submit-btn"));

Locators combine — { role: 'button', text: 'Save' } requires both. When several elements match, the one with the shortest text wins, so an exact match beats a container that happens to include it.


scope (clients) restricts a search to a subtree. It accepts pierce combinators too. On the CLI, map --selector scopes the map. CLI find has no scope option.

Terminal window
vibium map --selector "#sidebar"
vibium map --selector "my-card >> .content"

Element objects scope automatically — element.find(...) searches within that element.