Page

Page is one browser tab or WebView, modeled on Playwright's Page plus agent-browser's agent features. Get one from browser.page(), browser.newPage() or context.newPage().

val page = browser.newPage()
page.goto("https://example.com")
page.click("text=More information")             // extension: page.locator(selector).click()
val response = page.waitForResponse("**/api/*") { click("#load") }
expect(page).toHaveTitle(Regex("Example"))

Conventions:

• Every operation is suspend unless marked otherwise below.
• A timeoutMs of null uses the matching TimeoutConfig default. Timeouts throw KmpwrightTimeoutException.
• Page extends ElementFinder, so it has locator, frameLocator and every getBy* method. They are listed on Locator.
• Members marked "CDP only" throw KmpwrightUnsupportedException on Android and iOS. See Capabilities.
• String URL parameters (route, unroute, waitForURL, waitForRequest, waitForResponse, waitForNavigation, waitForDownload, expect(page).toHaveURL) use Playwright's URL glob over the full URL: ** matches anything including /, * anything except /, {a,b} either alternative, \ escapes, and every other character (including ?) is literal. A string without glob characters is an exact URL ("https://example.com" equals https://example.com/); an empty string matches everything. Use "**/api/items" for a path on any host, the Regex overloads, or the KMPwright regex: prefix where only a String is accepted.

Source: Page.kt, PageConvenience.kt, PageWaits.kt.

PropertiesCopy Anchor Link

All non-suspending.

CapabilitiesCopy Anchor Link

See Capabilities.

NavigationCopy Anchor Link

NavigationResult(url: String, status: Int, ok: Boolean, error: String? = null): url is the final URL after redirects; status the HTTP status of the final response (200 for local documents such as setContent, 0 when the navigation failed); ok is Playwright's response.ok(): committed and status 200..299. A 404 or 500 page is committed with ok = false and error = null; error is set only when no document was committed (network error, policy, domain filter).

WaitingCopy Anchor Link

Action-scoped waits (extensions)Copy Anchor Link

Playwright's Promise.all([page.waitForX(), action()]) in one call: the wait subscribes before action runs, so a fast event cannot be missed. action has the page as receiver.

val nav = page.waitForNavigation { click("text=Next") }
val response = page.waitForResponse(Regex("/api/items")) { click("#load") }

Content and scriptsCopy Anchor Link

JsResult(value: String, type: String): value is the string itself for strings and JSON for everything else ("null" for null and undefined); type is the JavaScript typeof, with "null" for null and "array" for arrays. Playwright returns deserialized values; parse value yourself.

Agent featuresCopy Anchor Link

NetworkCopy Anchor Link

Route has request: Request and fulfill(status = 200, headers = emptyMap(), body = null, bodyBytes = null, contentType = null, json = null) (json is an already-serialized body that cannot be combined with body/bodyBytes; bodyBytes wins over body), abort(errorCode = "failed"), resume(url = null, method = null, headers = null, postData = null) (Playwright route.continue()) and fallback(). A handler decides once; a second decision throws "Route is already handled". Handlers are bounded by TimeoutConfig.handler. See Network.

Dialog helpers (extensions)Copy Anchor Link

DialogEvent(type: DialogType, message: String, defaultPrompt: String? = null) with DialogType Alert, Confirm, Prompt, BeforeUnload. DialogResponse is Accept, Dismiss or Text(text) (accepts a prompt with text). Without a handler, dialogs are dismissed on iOS and JVM and left to the WebView's own UI on Android.

Cookies and storage stateCopy Anchor Link

Cookie(name, value, domain, path = "/", expires: Double? = null, secure = false, httpOnly = false, sameSite: String? = null, hostOnly = !domain.startsWith(".")); expires is Unix epoch seconds, null for a session cookie.

EmulationCopy Anchor Link

ScrollingCopy Anchor Link

Tabs and lifecycleCopy Anchor Link

After close(), page operations throw KmpwrightException: "Page is closed".

Browser extensions for tabs (agent-browser tab): fun Browser.tabList(): List<TabInfo(index, url, page)>, fun Browser.switchToTab(index: Int): Page, suspend fun Browser.closeTab(index: Int). Out-of-range indexes throw "Tab index N out of range (0..M)".

Browser, BrowserContext, Page and LaunchedBrowser each have suspend inline fun <T> X.use(block: (X) -> T): T, which runs block and then closes the receiver even when block throws or the coroutine is cancelled (the close runs in NonCancellable), like Kotlin's Closeable.use and Ktor's HttpClient.use:

browser.newPage().use { page ->
    page.goto("https://example.com")
    page.click("button.submit")
}

Selector conveniences (extensions)Copy Anchor Link

Playwright's page.click(selector) family. Each one is page.locator(selector).<action>(...); selectors also accept snapshot refs (@e3, e3, ref=e3).

Queries wait for the element to be attached first (TimeoutConfig.waitForSelector when timeoutMs is null), like Playwright:

State checks do not wait:

Other public functions that take a PageCopy Anchor Link

PageEventsCopy Anchor Link

Hot, non-replaying SharedFlows. Subscribe before triggering the action, or use the action-scoped waits.

Collecting dialog does not register a dialog listener: on Android a dialog is only emitted while an onDialog handler or a waitForDialog is active.

PageError(name, message, stack: String? = null, location: SourceLocation? = null) has text ("Name: message", or the message when name is empty). ConsoleMessage.type is one of Playwright's values: log, debug, info, error, warning, dir, dirxml, table, trace, clear, startGroup, startGroupCollapsed, endGroup, assert, profile, profileEnd, count, timeEnd. PageMessageFilter is SinceNavigation or All.

Download has url, suggestedFilename, path(): String? and saveAs(path) (throws when no download path was set). FileChooser has isMultiple and setFiles(files) (an empty list cancels).

ParametersCopy Anchor Link

Options are Kotlin named parameters: Playwright's page.screenshot({ fullPage: true }) is page.screenshot(fullPage = true). Where a method takes timeoutMs: Long? = null, it follows the other parameters; only a trailing lambda (predicate, action) comes after it.

Navigation parametersCopy Anchor Link

goto, reload, goBack, goForward, setContent and waitForURL share these parameters:

waitForNavigation:

waitForEvent (after event):

screenshot parametersCopy Anchor Link

Locator.screenshot takes omitBackground, quality, format, scale and timeoutMs (no fullPage, clip or annotate).

ScreenshotResult(bytes, width, height, annotations: List<Annotation(ref, role, name, box)>). ScreenshotResult.toRgbaImage(): RgbaImage? decodes it.

pdf parametersCopy Anchor Link

addScriptTag and addStyleTag parametersCopy Anchor Link

snapshot parametersCopy Anchor Link

Also the first seven parameters of boundedSnapshot.

SnapshotDiffResult(unifiedDiff, additions, removals, unchanged, changed).

read parametersCopy Anchor Link

HttpReader(config).read(url, ...) takes the same parameters after a required url and works without a page and without browser cookies.

ReadResult(url, finalUrl, status, contentType, source, truncated, content, headers).

webVitals parametersCopy Anchor Link

screencast parametersCopy Anchor Link

tracing.start parametersCopy Anchor Link

video.start parametersCopy Anchor Link

Emulation valuesCopy Anchor Link