Skip to content

Locator

The core type in testing-widgets. A Locator is callable — locator() is shorthand for locator.get(). All queries are lazy and chainable.

import type { Locator, ByRoleOptions } from "testing-widgets";

Return a new scoped Locator. Support string or RegExp where noted.

locator.getByRole("button", { name: "Submit" })
locator.getByLabel("Email") // string | RegExp
locator.getByPlaceholder("Search") // string | RegExp
locator.getByText("Welcome") // string | RegExp
locator.getByTestId("hero")

ByRoleOptions: name, checked, disabled, expanded, selected, pressed — all optional.

MethodReturnsThrows?
get()elementyes
getAll()element[]yes (if none)
query()element | nullno
queryAll()element[]no
find()Promise<element>yes (async)
()elementyes (same as get())

All return Promise<void>.

MethodDescription
click()Click the element
fill(value)Fill input/textarea
check()Check checkbox/radio (idempotent)
uncheck()Uncheck checkbox/radio (idempotent)
selectOption(value)Select option(s) — accepts string | string[]
clear()Clear an input

All return promises.

MethodReturns
textContent()string | null
getAttribute(name)string | null
inputValue()string
isVisible()boolean
isEnabled()boolean
isChecked()boolean

Queries scope within the parent, so you can drill into nested elements:

const dialog = locator.getByRole("dialog", { name: "Confirm" });
const okBtn = dialog.getByRole("button", { name: "OK" });