count
Returns the number of elements matching this locator.For assertions, prefer expect(locator).toHaveCount() to avoid flakiness.
Return value
first
Returns locator to the first matching element. Upstream docsReturn value
last
Returns locator to the last matching element. Upstream docsReturn value
nth
Returns locator to the nth matching element.Index is zero-based. Negative indices count from the end (-1 is last).
Zero-based index
Return value
locator
Creates a locator matching descendants of this element.Accepts CSS, XPath, or text selectors. Can also accept another locator.
Selector or locator to match descendants
Return value
filter
Narrows the locator with additional filters.Supports has, hasNot, hasText, hasNotText, and visible options.
Multiple filters can be chained.
Return value
all
Returns array of locators pointing to all matching elements.Does not wait for elements. Use with caution on dynamic lists.
Wait for the list to stabilize before calling.
Return value
getByRole
Locates elements by their ARIA role.Matches by implicit ARIA role (e.g., <button>) or explicit role attribute.
Options include name, checked, disabled, expanded, etc.
ARIA role to match
Return value
getByText
Locates elements containing the specified text.Matches case-insensitively by default. Use exact: true for exact match.
Text or pattern to match
Return value
getByLabel
Locates form elements by their associated label text.Matches <label> text, aria-label, or aria-labelledby.
Label text or pattern
Return value
getByPlaceholder
Locates input elements by their placeholder text. Upstream docsPlaceholder text or pattern
Return value
getByAltText
Locates elements by their alt attribute (typically images). Upstream docsAlt text or pattern
Return value
getByTitle
Locates elements by their title attribute. Upstream docsTitle attribute text or pattern
Return value
getByTestId
Locates elements by their test ID attribute.Default attribute is data-testid. Can be configured via selectors.setTestIdAttribute().
Test ID value or pattern
Return value
frameLocator
Returns a FrameLocator for an iframe within this element.Use to interact with content inside iframes.
CSS selector for iframe
Return value