API Reference PythonLocator

Locator

Every action and query method on Page (click, fill, hover, press, focus, highlight, count, text_content, inner_text, wait_for) is also available directly on a Locator, scoped to whatever it resolves to. What's below is what a Locator adds: building one semantically instead of by raw selector, and narrowing it once built.

get_by_role

MethodSince v0.1.3

Finds elements by ARIA role, with keyword-only attribute filters. TextMatcher accepts a str or a compiled re.Pattern.

def get_by_role(self, role: str, *, name: TextMatcher | None = None, exact: bool = False, checked: bool | None = None, disabled: bool | None = None, expanded: bool | None = None, include_hidden: bool = False, level: int | None = None, pressed: bool | None = None, selected: bool | None = None) -> Locator

Example

page.get_by_role("button", name=re.compile(r"^Save"), pressed=False)

get_by_text / get_by_label / get_by_placeholder / get_by_alt_text / get_by_title

MethodSince v0.1.3

Finds elements by visible text, associated label, placeholder, alt text, or title attribute — same keyword-only exact flag on each.

def get_by_text(self, text: TextMatcher, *, exact: bool = False) -> Locator

get_by_test_id

MethodSince v0.1.3

Finds elements by test-id attribute.

def get_by_test_id(self, text: TextMatcher) -> Locator

filter

MethodSince v0.1.3

Narrows a locator by a required or forbidden descendant (has/has_not, same page only), by text, or by visibility.

def filter(self, *, has: Locator | None = None, has_not: Locator | None = None, has_text: TextMatcher | None = None, has_not_text: TextMatcher | None = None, visible: bool | None = None) -> Locator

Example

page.locator('article').filter(has=inner, visible=True)

not_

MethodSince v0.1.3

Excludes elements also matched by other (must share the same page). Named not_ since not is a Python keyword.

def not_(self, other: Locator) -> Locator

Example

all_buttons.not_(page.get_by_text('Cancel')).first

nth / first / last

MethodSince v0.1.3

Selects one match by position — nth accepts negative indices; first/last are properties shorthand for nth(0)/nth(-1).

def nth(self, index: int) -> Locator
first -> Locator  # property
last -> Locator  # property

locator

MethodSince v0.0.33

Chains a nested raw selector under this locator.

def locator(self, selector: str) -> Locator

← PreviousPage Next →Hooks