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.
vibium find css "button.primary"vibium find css "#login input[type=password]"vibium click "nav a:nth-child(2)"await vibe.find({ css: 'button.primary' });vibe.find(css="button.primary")vibe.find(new SelectorOptions().css("button.primary"));CSS selectors do not cross shadow boundaries. Use a pierce combinator for that.
Pierce combinators
Section titled “Pierce combinators”Shadow roots are invisible to querySelector, so a component’s internals need an explicit hop.
| Combinator | Meaning |
|---|---|
>> | Cross one shadow boundary — the host’s own shadow root |
>>> | Cross any depth of nested shadow roots below the host |
# <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 rootvibium find css "my-card >>> #deep"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' });p = vibe.find(css="my-card >> p")btn = vibe.find(css="outer-host >>> button")items = vibe.find_all(css="my-card >> li")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 (>>>).
Chaining
Section titled “Chaining”Each combinator hops from the elements matched so far, so they can be chained:
app-shell >> side-nav >> buttonCombinators may be mixed — outer >>> mid >> button searches deeply for mid, then takes exactly one hop into it.
Where they work
Section titled “Where they work”Anywhere a selector is accepted — find, findAll, click, fill, text, is, and map --selector.
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 toquerySelectorAll, 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>>pandmy-card >> pare the same. >(CSS child) and>>(pierce) are distinct —div > pstays a normal CSS child selector.vibium maptraverses shadow roots automatically; you do not need a combinator to see component internals in its output.
Semantic locators
Section titled “Semantic locators”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.
| Locator | Matches |
|---|---|
role | ARIA role, explicit or implicit (<button> → button) |
text | Visible text content, substring match |
label | Accessible name — aria-label, aria-labelledby, <label for>, or an input’s value for submit/reset/button |
placeholder | placeholder attribute |
alt | alt attribute |
title | title attribute |
testid | data-testid attribute |
xpath | XPath expression |
vibium find role buttonvibium find role button --name "Log in"vibium find text "Sign In"vibium find testid "submit-btn"await vibe.find({ role: 'button', label: 'Log in' });await vibe.find({ testid: 'submit-btn' });vibe.find(role="button", label="Log in")vibe.find(testid="submit-btn")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.
vibium map --selector "#sidebar"vibium map --selector "my-card >> .content"Element objects scope automatically — element.find(...) searches within that element.