Locator

A Locator is a lazy reference to the elements matching a selector, like Playwright's Locator. It resolves again on every call, so it survives re-renders. Create one from a Page, Locator or FrameLocator.

val row = page.getByRole("row").filter(hasText = "Invoice 42")
row.getByRole("button", name = "Pay").click()
expect(row.locator(".status")).toHaveText("Paid")

page.snapshot(interactive = true)
page.locator("@e3").fill("hello")                 // snapshot ref
page.frameLocator("#checkout").getByLabel("Card number").fill("4242 4242 4242 4242")

Every action is suspend. Options are named parameters (click(button = MouseButton.Right, force = true)); timeoutMs = null uses TimeoutConfig.action for actions and TimeoutConfig.waitForSelector for waitFor. Source: Locator.kt.

Selector enginesCopy Anchor Link

locator(selector) accepts:

An unparsable selector fails with an "Invalid selector …" message.

ActionabilityCopy Anchor Link

Actions wait until the element is ready and retry until their timeout, like Playwright:

force = true skips the visible, enabled, stable and hit-target checks. When the timeout expires, the KmpwrightTimeoutException names the last failing check, for example Element #save is not enabled after 30000ms while trying to click: <button id="save" disabled>. See Errors.

With KmpwrightConfig.strictSelectors = true (default), single-element operations fail when the selector matches more than one element: "Strict mode violation: '.item' resolved to 3 elements (…). Use first(), last(), nth() or a more specific selector." Multi-element methods (count, all, allTextContents, allInnerTexts) never are strict.

On Android and iOS, locator actions run as DOM events inside the page. On the JVM with InputMode.Hybrid, click, dblclick, tap, hover, fill, pressSequentially, press and dragTo use native CDP input. See InputMode.

Locator actionsCopy Anchor Link

Locator queriesCopy Anchor Link

These read the current state and do not wait for the element. Playwright's locator.textContent() and friends wait for an element first; in KMPwright use waitFor() first, the Page.textContent(selector) extensions (which wait for Attached), or a web-first assertion.

Content reads need KmpwrightConfig.allowDomExtraction.

Narrowing and combiningCopy Anchor Link

All non-suspending; they return a new Locator.

has, hasNot, and and or need locators from the same page ("… needs a locator created by the same page").

ElementFinderCopy Anchor Link

Shared by Page, Locator and FrameLocator. On a Locator, results are scoped to its matches. Text arguments match case-insensitively as substrings unless exact = true.

All getBy* methods return Locator and are non-suspending.

FrameLocatorCopy Anchor Link

Locates elements inside an iframe, like Playwright's FrameLocator. It is an ElementFinder, so it has locator, frameLocator (nested frames) and every getBy*. page.mainFrame() returns the main frame as a FrameLocator.

ParametersCopy Anchor Link

click and dblclick parametersCopy Anchor Link

dblclick has no clickCount.

tap parametersCopy Anchor Link

force and timeoutMsCopy Anchor Link

fill, clear, hover, check, uncheck, setChecked, selectOption and setInputFiles take only these two after their required arguments:

press and pressSequentially parametersCopy Anchor Link

Key names follow Playwright: "Enter", "Tab", "ArrowDown", "Shift+Tab", "Control+A". KeyboardModifiers has the constants SHIFT, CONTROL, ALT, META, CAPS_LOCK.

dragTo parametersCopy Anchor Link

Also used by page.dragAndDrop(source, target, ...).

scrollIntoViewIfNeeded parametersCopy Anchor Link

highlight parametersCopy Anchor Link

Value typesCopy Anchor Link

RelatedCopy Anchor Link

• Locators guide
• Assertions
• Page for the page.click(selector) conveniences.