Coming from Playwright

KMPwright uses Playwright's JavaScript names and shapes wherever Kotlin allows. If you know Playwright, most code translates line by line:

// await page.goto('https://example.com');
page.goto("https://example.com")
// await page.getByRole('button', { name: 'Save' }).click();
page.getByRole("button", name = "Save").click()
// await expect(page.getByText('Saved')).toBeVisible();
expect(page.getByText("Saved")).toBeVisible()
// await page.route('**/api/**', r => r.fulfill({ json: { ok: true } }));
page.route("**/api/**") { route -> route.fulfill(json = """{"ok":true}""") }

The naming rules, in order:

1. Playwright JS names and shapes.
2. Playwright Java names where the JS name is a Kotlin keyword: route.resume() for route.continue().
3. agent-browser names for agent features: snapshot(), @e3 refs, setAllowedDomains, runCommand.
4. Kotlin idioms only where needed: suspend instead of Promises, named parameters instead of option objects, flows instead of page.on(...), timeoutMs: Long?, use {} for cleanup.

Playwright option objects become Kotlin named parameters with the same names: page.screenshot({ fullPage: true }) is page.screenshot(fullPage = true), and locator.click({ button: 'right', force: true }) is locator.click(button = MouseButton.Right, force = true). Every timeout becomes timeoutMs: Long? (milliseconds; null uses the configured default), and every delay becomes delayMs.

The tables below list every Playwright API with a KMPwright counterpart. "—" means there is none. Snippets assume page: Page.

Browser, context and page lifecycleCopy Anchor Link

Navigation and waitsCopy Anchor Link

Locators and getBy*Copy Anchor Link

locator, frameLocator and the getBy* finders are available on Page, Locator and FrameLocator (the shared ElementFinder interface). Text arguments match case-insensitively as substrings unless exact = true.

Locator actions and queriesCopy Anchor Link

Actions wait for the element to be attached, visible, enabled, stable and hit-testable (fill: editable) and retry until timeoutMs (default TimeoutConfig.action). force = true skips the checks.

AssertionsCopy Anchor Link

expect(locator) returns LocatorAssertions; expect(page) returns PageAssertions. Each assertion re-reads until it holds or timeoutMs (default TimeoutConfig.waitForSelector) passes, then throws KmpwrightTimeoutException. Use .not to negate.

NetworkCopy Anchor Link

Cookies, storage and storage stateCopy Anchor Link

EmulationCopy Anchor Link

Input devicesCopy Anchor Link

Coordinates are viewport CSS pixels. Mouse input is Partial on Android and iOS (PageCapability.MouseInput); CDP uses trusted input events.

DialogsCopy Anchor Link

FramesCopy Anchor Link

CDP resolves same-process and cross-process (out-of-process) frames. Mobile WebViews are limited to same-origin frames.

Downloads and file chooserCopy Anchor Link

Screenshots and PDFCopy Anchor Link

Tracing and videoCopy Anchor Link

Differences to keep in mindCopy Anchor Link

suspend instead of await. Every operation that touches the page is a suspend function. There are no Promises to forget to await, but you need a coroutine scope.

use {} instead of try/finally. Browser, BrowserContext, Page and LaunchedBrowser have use { }, which closes them when the block ends, even when it throws or is cancelled, like Kotlin's Closeable.use and Ktor's HttpClient.use:

browser.newPage().use { page ->
    page.goto("https://example.com")
    page.screenshot(fullPage = true)
}

State as flows. page.url and page.title are StateFlows you can read (.value) or collect. page.events exposes hot SharedFlows (console, navigation, loadState, dialog, request, response, download, fileChooser) instead of page.on(...). Subscribe before you trigger the action, or use the action-scoped helpers (waitForNavigation { }, waitForResponse(url) { }, …), which subscribe for you.

Options are named parameters. page.goto(url, waitUntil = LoadState.DOMContentLoaded). Kotlin's named and default arguments replace option objects; the names match Playwright's, except timeout → timeoutMs, delay → delayMs and screenshot type → format. timeoutMs comes after the other options (only a trailing lambda follows it).

Timeouts are timeoutMs: Long?. null (the default) means "use the configured default" from KmpwrightConfig.timeouts: navigation for navigations, action for locator actions, waitForSelector for assertions, default for everything else. All four default to 30 000 ms. Timeouts throw KmpwrightTimeoutException; other failures throw KmpwrightException.

Strict selectors. By default a locator action that matches more than one element fails, like Playwright. KmpwrightConfig(strictSelectors = false) relaxes this.

No element handles. Everything goes through lazy locators. page.evaluate takes an expression string; locator.evaluate takes a function string such as "el => el.value".

String URL patterns. route, unroute, waitForURL, waitForRequest, waitForResponse, waitForNavigation(url = …), waitForDownload and expect(page).toHaveURL use Playwright's URL glob over the full URL; a string without glob characters is an exact URL. A regex: prefix makes the string a regular expression where there is no Regex overload (such as waitForDownload). Prefer the Regex overloads where they exist.

Capabilities instead of "it just works". Check what the backend can do before you depend on it:

page.requireCapabilities(PageCapability.Downloads)                    // fails fast if not Supported
page.requireCapabilities(PageCapability.RouteInterception.require(SupportLevel.Partial))
val level = page.capabilities().supportLevel(PageCapability.VideoRecording)
val why = page.capabilities().notes                                   // human-readable gaps

Not supportedCopy Anchor Link

• Firefox and WebKit desktop browsers. The JVM backend is Chromium over CDP; mobile backends are the system WebViews.
• A test runner. There is no @playwright/test equivalent (fixtures, projects, retries, reporters); use your own test framework and call expect.
• Codegen, the inspector, page.pause(), Playwright trace viewer files.
• Element handles, evaluateHandle, exposeFunction, exposeBinding.
• route.fetch, routeFromHAR, WebSocket routing.
• Context options without a runtime setter: locale, timezoneId, permissions, reducedMotion.
• Visual assertions (toHaveScreenshot). page.visualDiff(expected, actual) compares two ScreenshotResults.

Mobile WebView limitationsCopy Anchor Link

On Android WebView and iOS WKWebView, KMPwright runs inside an app's view rather than a browser it controls, so:

• Input is synthesized as DOM events, not trusted OS input. Mouse and (on iOS) keyboard input are Partial.
• Routing covers what the platform exposes: Android shouldInterceptRequest; iOS fetch/XHR through a bridge plus optional custom-scheme interception. Neither sees every request a desktop browser would.
• No downloads, file chooser, setInputFiles, tracing, profiling, video or screencast.
• Network emulation is offline-only.
• Android has no isolated browser contexts; cookies are shared by every WebView in the process.
• Frames are limited to same-origin documents.

See Capabilities for the full matrix and each backend's notes.