API ReferenceGoLocator
Locator
Every action and query method on Page (Click, DblClick, Fill, Hover, Press, Focus, Highlight, Count, TextContent, InnerText, InputValue, SelectedOptions, SelectedText, IsChecked, GetAttribute, BoundingBox, WaitFor) is also available directly on a Locator, scoped to whatever it resolves to. What's below is what a Locator adds on top: building one semantically instead of by raw selector, and narrowing it once built.
GetByRole
Finds elements by ARIA role, with optional Name/Exact/Checked/Disabled/Expanded/Level/Pressed/Selected/IncludeHidden filters. Available on both *Tab and *Locator (chainable).
func (l *Tab) GetByRole(role string, options ...RoleOptions) *LocatorExample
page.GetByRole("button", allwright.RoleOptions{Name: "Submit"})GetByText / GetByLabel / GetByPlaceholder / GetByAltText / GetByTitle / GetByTestId
Finds elements by visible text, label, placeholder, alt text, title, or test-id attribute — text accepts a string or a TextPattern regex, with TextOptions.Exact for exact matching. Same signature shape on *Locator for chaining.
func (l *Tab) GetByText(text any, options ...TextOptions) *Locator(*Locator).Filter
Narrows a locator by requiring or forbidding a descendant (Has/HasNot, same page only), by text (HasText/HasNotText), or by Visible.
func (l *Locator) Filter(options LocatorFilterOptions) *Locator(*Locator).Not
Excludes elements also matched by other (must share the same page).
func (l *Locator) Not(other *Locator) *Locator(*Locator).Nth / First / Last
Selects one match by position — Nth accepts negative indices (from the end); First/Last are shorthands for Nth(0)/Nth(-1).
func (l *Locator) Nth(index int) *Locator
func (l *Locator) First() *Locator
func (l *Locator) Last() *Locator(*Locator).Locator
Chains a nested raw selector under this locator, scoping the search to its descendants.
func (l *Locator) Locator(selector string) *Locator(*Locator).Frame
Resolves this iframe — nested or cross-origin — to a normal *Page, waiting for exactly one match whose document is complete and has gone 200 ms without DOM mutations. Timeout (default 10s) covers the whole resolution; closing the returned page releases its session without closing the parent tab.
func (l *Locator) Frame(ctx context.Context, options ...CommandOptions) (*Page, error)Example
frame, err := page.Locator("#checkout-frame").Frame(ctx, allwright.CommandOptions{Timeout: 10 * time.Second})
frame.Locator("input[name=email]").Fill(ctx, "buyer@example.com")
nested, err := frame.Locator("iframe").Frame(ctx)