Accessibility Selectors

Accessibility selectors find elements by their semantic attributes — ARIA roles, labels, text content, and other user-facing properties. They are more resilient than CSS selectors because they target what the user sees, not implementation details.

All methods are available on both Page and Frame, and return a *Locator for chaining.

GetByRole

Find elements by their ARIA role. Matches both explicit role attributes and implicit roles from HTML semantics.

page.GetByRole("button").Click()
page.GetByRole("link").First().Text()
page.GetByRole("heading").Count()

Implicit Role Mapping

Common HTML elements are matched by their implicit ARIA role:

Filter by Name

Use WithName to filter by the element's accessible name (text content, aria-label, or aria-labelledby):

page.GetByRole("button", bonk.WithName("Submit")).Click()

For an exact name match, pass Exact():

page.GetByRole("button", bonk.WithName("Submit", bonk.Exact())).Click()

Without Exact(), name matching is substring-based — "Submit" matches both "Submit" and "Submit Form".

GetByLabel

Find form controls by their associated label. Checks <label> elements (both for attribute and nested inputs), aria-label, and aria-labelledby.

page.GetByLabel("Email").Fill("user@example.com")
page.GetByLabel("Password").Fill("secret")
page.GetByLabel("Remember me").Click()

Works with all label association patterns:

// <label for="email">Email</label><input id="email">
page.GetByLabel("Email")

// <label>Username <input type="text"></label>
page.GetByLabel("Username")

// <input aria-label="Search">
page.GetByLabel("Search")

GetByText

Find elements by their visible text content. Matches elements that directly own the text (not ancestors that contain it deep in their subtree).

page.GetByText("Welcome back").Text()
page.GetByText("Sign in").Click()

Default matching is substring. Use Exact() for exact match:

page.GetByText("Hello", bonk.Exact())

GetByPlaceholder

Find elements by their placeholder attribute:

page.GetByPlaceholder("Search...").Fill("bonk go")
page.GetByPlaceholder("Enter email", bonk.Exact()).Fill("a@b.com")

GetByTestID

Find elements by their data-testid attribute. Always uses exact matching:

page.GetByTestID("submit-button").Click()
page.GetByTestID("user-avatar").Screenshot("avatar.png")

GetByAltText

Find elements by their alt attribute:

page.GetByAltText("Company Logo").Screenshot("logo.png")
page.GetByAltText("Logo").Attribute("src")  // substring match

GetByTitle

Find elements by their title attribute:

page.GetByTitle("Close dialog").Click()
page.GetByTitle("Close", bonk.Exact()).Click()

Text Matching

All text-based selectors (except GetByTestID) default to substring matching. Pass bonk.Exact() to require an exact match (after trimming whitespace):

Chaining

All methods return a *Locator, so the full Locator API is available:

page.GetByRole("listitem").Count()
page.GetByRole("listitem").First().Text()
page.GetByRole("listitem").Nth(2).Click()
page.GetByRole("button", bonk.WithName("Save")).WaitFor()

Frames

All methods work on frames too:

frame, _ := page.Frame("content")
frame.GetByRole("button").Click()
frame.GetByLabel("Search").Fill("query")

When to Use Which