API ReferenceJavaLocator
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: 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)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. timeoutMs (default 10 000) covers the whole resolution; closing the returned page releases its session without closing the parent tab.
public Page frame()
public Page frame(CommandOptions options)Example
Page frame = page.locator("#checkout-frame").frame(new CommandOptions(10_000));
frame.locator("input[name=email]").fill("buyer@example.com");
Page nested = frame.locator("iframe").frame();