Selectors

10 selector types for targeting elements by purpose, not position

BAP uses semantic selectors that describe elements by their purpose instead of their DOM position. They survive layout changes, dynamic content updates, and A/B tests.

Selector Types

Type	Syntax	Example	When to use
Stable ref	@<ref>	@submitBtn	Refs returned by bap observe — most precise
Positional ref	e<N>	e15	From snapshot refs (playwright-cli compatible)
Role	role:<role>:"<name>"	role:button:"Submit"	Interactive elements by ARIA role — most reliable
Text	text:"<content>"	text:"Sign in"	By visible text content
Label	label:"<text>"	label:"Email"	Form inputs by associated label
Placeholder	placeholder:"<text>"	placeholder:"Search..."	Inputs by placeholder attribute
Test ID	testid:"<id>"	testid:"submit-btn"	By data-testid — most stable for apps that use them
CSS	css:<selector>	css:.btn-primary	CSS selector (fallback)
XPath	xpath:<path>	xpath://button[@type]	XPath selector (fallback)
Coordinates	coords:<x>,<y>	coords:100,200	Click by pixel coordinates (last resort)

Priority and Recommendations

1. Start with stable refs from observe

   Run bap observe and use the exact @ref values it returns. These are the most precise selectors because they map to a specific element in the registry.

   bap observe
   # Output: @ep44e3j  button  "Submit"
   bap click @ep44e3j
   
2. Use semantic selectors when the target is obvious

   Role selectors are the most reliable for interactive elements. Label selectors are best for form fields.

   bap click role:button:"Submit"
   bap fill label:"Email" "[e-mail]"
   
3. Fall back to text selectors for links and content

   bash bap click text:"Learn more" bap click text:"Next page"

4. Use CSS/XPath only when semantic selectors cannot match

   bap click css:.custom-widget-btn
   bap click xpath://div[@class='grid']//button[2]
   

Using Selectors in Commands

Single commands

bap click role:button:"Submit"
bap fill label:"Email" "[e-mail]"
bap hover text:"Learn more"
bap click @ep44e3j
bap click e15

In composite actions (bap act)

The step syntax is action:selector=value for fill/type and action:selector for click/check/hover:

bap act fill:label:"Email"="[e-mail]" \
        fill:label:"Password"="secret123" \
        click:role:button:"Sign in"

In the TypeScript SDK

import { role, text, label, testId } from "@browseragentprotocol/client";

await client.click(role("button", "Submit"));
await client.fill(label("Email"), "[e-mail]");
await client.click(text("Sign in"));
await client.click(testId("submit-button"));

In the Python SDK

from browseragentprotocol import role, text, label, test_id

await client.click(role("button", "Submit"))
await client.fill(label("Email"), "[e-mail]")
await client.click(text("Sign in"))
await client.click(test_id("submit-button"))

In MCP tools

selector: "role:button:Submit"
selector: "text:Sign in"
selector: "label:Email address"
selector: "testid:submit-button"
selector: "ref:@submitBtn"

Role Selector Examples

The role selector uses ARIA roles, which cover most interactive elements:

role:button:"Submit"         # Buttons
role:textbox:"Email"         # Text inputs
role:link:"Home"             # Links
role:heading:"Welcome"       # Headings
role:checkbox:"Remember me"  # Checkboxes
role:combobox:"Country"      # Dropdowns
role:searchbox:"Search"      # Search inputs
role:listitem:"Item 1"       # List items

Disambiguation

When multiple elements match a selector, BAP returns the first visible, interactive match. To disambiguate:

1. Use a more specific role (e.g., role:button:"Submit" instead of text:"Submit")
2. Run bap observe --max=100 to see all candidates and use the exact @ref
3. Combine with CSS if needed: css:#login-form button[type=submit]

Identical elements (e.g., six “Add to cart” buttons) produce ambiguous text:Add to cart selectors. Use the specific @ref from bap observe or a CSS selector with an ID to target the right one.

Fallback Behavior

If a semantic selector does not match, BAP returns a clear error message with the closest matches found on the page, helping the agent self-correct.