API ReferenceJavaLocator
Locator
Every action and query method on Page (click, fill, hover, press, focus, highlight, count, textContent, innerText, waitFor) is also available directly on a Locator, scoped to whatever it resolves to. What's below is what a Locator adds: building one via the WebLocators interface, and narrowing it once built.
getByRole
Finds elements by ARIA role. RoleOptions is a fluent, mutable builder (setName, setExact, setChecked, setDisabled, setExpanded, setIncludeHidden, setLevel, setPressed, setSelected).
default Locator getByRole(String role)
default Locator getByRole(String role, RoleOptions options)Example
Locator submit = page.getByRole("button", new RoleOptions().setName("Submit"));getByText / getByLabel / getByPlaceholder / getByAltText / getByTitle
Finds elements by visible text, associated label, placeholder, alt text, or title attribute. text accepts a String or a java.util.regex.Pattern.
default Locator getByText(Object text)
default Locator getByText(Object text, TextOptions options)getByTestId
Finds elements by test-id attribute.
default Locator getByTestId(Object text)
default Locator getByTestId(Object text, TextOptions options)Locator.filter
Narrows the locator by has/hasNot sub-locators (same page only) and/or hasText/hasNotText/visible, via the fluent LocatorFilterOptions builder.
public Locator filter(LocatorFilterOptions options)Example
page.locator(".card").filter(new LocatorFilterOptions().setHasText("Form Inputs"));Locator.not
Excludes elements also matched by other; throws IllegalArgumentException if the two locators belong to different pages.
public Locator not(Locator other)Locator.nth / first / last
Selects one match by position — nth accepts negative indices; first/last are shorthands for nth(0)/nth(-1).
public Locator nth(int index)
public Locator first()
public Locator last()Locator.locator
Builds a nested locator scoped inside this one.
public Locator locator(String childSelector)