Locators

page.goto("https://example.com/login")

page.getByLabel("Email").fill("ada@example.com")
page.getByLabel("Password").fill("correct horse")
page.getByRole("button", name = "Sign in").click()

val paid = page.locator("table tr").filter(hasText = "Paid")
println(paid.count())
println(page.getByTestId("balance").textContent())

A Locator is a lazy description of how to find elements. Creating one does nothing in the page; the selector is resolved again every time you call an action or query on it, so a locator stays valid across re-renders. Playwright: same model.

Locators come from any ElementFinder: Page, Locator (scoped to its matches) and FrameLocator (scoped to an iframe). Snapshot refs from snapshots (@e3) are plain selectors, so agent output and handwritten code use the same API.

FindersCopy Anchor Link

Every ElementFinder (Page, Locator, FrameLocator) has these methods. Each returns a Locator; nothing is resolved until you act on it.

Text matching is the same for all String finders:

• Default: case-insensitive substring, with whitespace collapsed ("sign in" matches Sign In now).
• exact = true: the whole whitespace-normalised string, case-sensitive.
• Regex: tested against the whitespace-normalised text. RegexOption.IGNORE_CASE, MULTILINE and DOT_MATCHES_ALL become the JavaScript flags i, m and s.

getByTestId(String) is the exception. It is an exact, case-sensitive match on data-testid. You can't change the test id attribute. Playwright: selectors.setTestIdAttribute has no equivalent.

getByRoleCopy Anchor Link

page.getByRole("button", name = "Save").click()
page.getByRole("checkbox", name = "Subscribe", checked = false).check()
page.getByRole("heading", level = 2).first().textContent()
page.getByRole("link", name = Regex("^Docs")).click()
page.getByRole("tab", selected = true).innerText()

How roles and names are computed depends on the backend:

Explicit roles and common HTML elements give the same results on every backend. Unusual markup (for example aria-owns or <section> without a label) may differ.

getByRole("input") is a KMPwright extension: it matches any textbox, searchbox, combobox, spinbutton or listbox, plus every input, textarea and select element.

Selector syntaxCopy Anchor Link

locator(selector) accepts these engines. A selector without a recognised engine= prefix is CSS.

label=, placeholder=, alt= and title= use the same text rules as text=: plain value for a substring, "quoted" for exact, /regex/flags for a regex.

The command-compatible aliases text:Sign in and exact_text=Sign in are also supported. Prefer the getBy* finders in Kotlin workflows.

Text matching detailsCopy Anchor Link

text= matches against the element's rendered text (innerText; for <input type=button|submit|reset>, its value). It returns the deepest elements that match: if a <button> and its parent <div> both contain "Save", only the button is returned. Text inside script, style, noscript, head, template and title is ignored.

Role attributesCopy Anchor Link

role= takes attribute filters in square brackets, the same ones getByRole builds:

Shadow DOMCopy Anchor Link

Open shadow roots are pierced by every engine except XPath:

• CSS runs querySelectorAll on the document and separately on each open shadow root. A single CSS selector can't cross a shadow boundary: my-card button does not match a button inside my-card's shadow root. Chain instead: my-card >> button.
• text=, role=, label=, placeholder=, alt=, title= and testid= walk open shadow trees.
• Closed shadow roots are never pierced.

Snapshot refsCopy Anchor Link

page.locator("@e3") targets the element that page.snapshot() labelled e3. e3, ref=e3 and ref=@e3 are equivalent when they make up the whole selector or a whole >> part of it. A ref is not re-resolved by role or name. It points at that exact DOM node, and matches nothing once the node is detached or a new document is loaded. Take a new snapshot after the page changes.

Inside locator.locator(...) and filters, write the ref=e3 form. Refs only match within the scope of the parent locator.

Invalid selectorsCopy Anchor Link

Syntax errors fail right away with a KmpwrightException whose message starts with Invalid selector. KMPwright does not retry them until the timeout. This covers malformed CSS, a bad XPath expression, an invalid regular expression and unparseable role= attributes.

Composing locatorsCopy Anchor Link

val row = page.locator("tr")
    .filter(hasText = "Ada Lovelace")
    .filter(has = page.getByRole("button", name = "Edit"))
row.getByRole("button", name = "Edit").click()

val items = page.getByRole("listitem")
items.first().click()
items.nth(-2).click()            // second to last
items.filter(hasNotText = "archived").count()
items.filter(hasText = Regex("^Q[1-4]")).count()

val submit = page.getByRole("button").and(page.locator("[type=submit]"))
val dismiss = page.getByText("Close").or(page.getByLabel("Dismiss"))

for (item in items.all()) println(item.innerText())

has, hasNot, and and or take a Locator from the same page. A locator from another page throws KmpwrightException. The has/hasNot locator is evaluated relative to each candidate, so page.getByRole("button") inside filter(has = …) means "a button inside this element".

Steps keep their order. locator("li").nth(1).locator("a") searches inside the second li, and locator("li a").nth(1) takes the second link overall.

StrictnessCopy Anchor Link

KMPwright enforces Playwright-style strict mode by default (KmpwrightConfig.strictSelectors = true). An operation that needs one element fails immediately with Strict mode violation: '<selector>' resolved to N elements (…). Use first(), last(), nth() or a more specific selector. when the locator matches more than one element. Strict operations:

• every action (click, fill, press, check, …),
• single-element queries (textContent, innerText, innerHTML, getAttribute, inputValue, boundingBox, isVisible, isEnabled, isChecked, isEditable, isFocused, evaluate, …).

These operations work on all matches and are never strict: count(), all(), allTextContents(), allInnerTexts(). waitFor(state) checks the first match.

To act on the first match instead of failing, call first(). To turn strictness off globally, set KmpwrightConfig(strictSelectors = false). Every single-element operation then uses the first match.

Reading element stateCopy Anchor Link

Queries run once and return. They don't auto-wait, except where noted. To wait for a state, use assertions (expect(locator).toBeVisible()) or waitFor.

Opacity is ignored by isVisible(): an opacity: 0 element with a size counts as visible. Playwright: same.

waitFor uses TimeoutConfig.waitForSelector when timeoutMs is null. The other queries take no timeout.

The DOM-reading queries (textContent, innerText, innerHTML, getAttribute, inputValue, count, all*, boundingBox) throw when KmpwrightConfig.allowDomExtraction = false. evaluate throws when allowEval = false.

Page shortcutsCopy Anchor Link

The same queries exist on Page, taking a selector:

page.textContent("#total")              // waits for the element to be attached
page.getAttribute("a.next", "href")
page.inputValue("#email")
page.isVisible("#banner")               // no waiting
page.count("li")
page.waitForSelector("#results", SelectorState.Visible)

textContent, innerText, innerHTML, getAttribute and inputValue on Page first wait for the element to be attached. They take an optional timeoutMs, which defaults to TimeoutConfig.waitForSelector. isVisible, isHidden, isEnabled, isDisabled, isChecked, isEditable and count don't wait.

RelatedCopy Anchor Link