Tab

Represents a browser tab, which is a connection to a specific target in the browser.

This class provides methods to interact with the tab, such as navigating to URLs, managing history, evaluating JavaScript expressions, and manipulating the DOM.

You can create a new instance of this class using the dev.kdriver.core.browser.Browser.get method:

fun main() = runBlocking {
    val browser = createBrowser(this)
    val tab = browser.get("https://example.com")
    // Use the tab instance to do things...
    browser.stop()
}

Inheritors

DefaultTab

Properties

attached

open val attached: Boolean?

browserContextId

open val browserContextId: String?

canAccessOpener

open val canAccessOpener: Boolean?

lastMouseX

abstract var lastMouseX: Double?

Last mouse X position for this tab (for natural trajectories in anti-detection). Each tab maintains its own mouse position to prevent concurrent operations from interfering.

lastMouseY

abstract var lastMouseY: Double?

Last mouse Y position for this tab (for natural trajectories in anti-detection). Each tab maintains its own mouse position to prevent concurrent operations from interfering.

openerFrameId

open val openerFrameId: String?

openerId

open val openerId: String?

subtype

open val subtype: String?

targetId

open val targetId: String?

targetInfo

abstract var targetInfo: <Error class: unknown class>?

title

open val title: String?

type

open val type: String?

url

open val url: String?

Functions

activate

abstract suspend fun activate()

Activates the tab, bringing it to the foreground.

addHandler

inline fun <T> Connection.addHandler(coroutineScope: CoroutineScope, crossinline event: <Error class: unknown class>.() -> Flow<T>, crossinline handler: suspend (T) -> Unit): Job

Adds a handler for a specific CDP event.

back

abstract suspend fun back()

Navigate back in the tab's history.

bringToFront

abstract suspend fun bringToFront()

Brings the tab to the front, activating it.

callCommand

abstract suspend fun callCommand(method: String, parameter: JsonElement?, mode: <Error class: unknown class>): JsonElement?

Internal method to call a CDP command.

abstract suspend fun close()

Closes the websocket connection. Should not be called manually by users.

disableDomAgent

abstract suspend fun disableDomAgent()

Disables the DOM agent to stop receiving DOM-related events.

evaluate

inline suspend fun <T> Tab.evaluate(expression: String, awaitPromise: Boolean = false): T?

Evaluates a JavaScript expression in the context of the tab.

expect

abstract suspend fun <T> expect(urlPattern: <Error class: unknown class>, block: suspend RequestExpectation.() -> T): T

Expects a request to match the given urlPattern.

expectBatch

abstract suspend fun <T> expectBatch(urlPatterns: List<<Error class: unknown class>>, block: suspend BatchRequestExpectation.() -> T): T

Expects multiple requests matching the given list of urlPatterns. All expectations are active concurrently during block.

find

abstract suspend fun find(text: String, bestMatch: Boolean = true, returnEnclosingElement: Boolean = true, timeout: Long): Element

Finds a single element by its text content, optionally waiting for it to appear.

findAll

abstract suspend fun findAll(text: String, timeout: Long): List<Element>

Finds multiple elements by their text content, optionally waiting for them to appear.

findElementByText

abstract suspend fun findElementByText(text: String, bestMatch: Boolean = false, returnEnclosingElement: Boolean = true): Element?

Finds and returns the first element containing the specified text, or the best match if bestMatch is true.

findElementsByText

abstract suspend fun findElementsByText(text: String, tagHint: String? = null): List<Element>

Returns elements which match the given text. Please note: this may (or will) also return any other element (like inline scripts), which happen to contain that text.

forward

abstract suspend fun forward()

Navigate forward in the tab's history.

fullscreen

abstract suspend fun fullscreen()

Sets the tab's window to fullscreen mode.

get

abstract suspend fun get(url: String = "about:blank", newTab: Boolean = false, newWindow: Boolean = false): Tab

Navigate to a specified URL in the tab.

getAllLinkedSources

abstract suspend fun getAllLinkedSources(): List<Element>

Gets all elements of tag: link, a, img, script, meta.

getAllUrls

abstract suspend fun getAllUrls(absolute: Boolean = true): List<String>

Convenience function, which returns all links (a, link, img, script, meta).

getContent

abstract suspend fun getContent(): String

Gets the content of the tab as a string.

getWindow

abstract suspend fun getWindow(): <Error class: unknown class>

Gets the current window information for the tab.

intercept

abstract suspend fun <T> intercept(urlPattern: String, requestStage: <Error class: unknown class>, resourceType: <Error class: unknown class>, block: suspend FetchInterception.() -> T): T

Intercepts network requests matching the given urlPattern and requestStage. This allows you to modify requests, responses, or block them entirely.

maximize

abstract suspend fun maximize()

Maximizes the tab's window.

medimize

abstract suspend fun medimize()

Restores the tab's window to its normal state.

minimize

abstract suspend fun minimize()

Minimizes the tab's window.

mouseClick

abstract suspend fun mouseClick(x: Double, y: Double, button: <Error class: unknown class> = Input.MouseButton.LEFT, buttons: Int = 1, modifiers: Int = 0)

Performs a native mouse click at the specified \[x, y\] coordinates.

mouseMove

abstract suspend fun mouseMove(x: Double, y: Double, steps: Int = 10, flash: Boolean = false)

Moves the mouse cursor to the specified \[x, y\] coordinates, optionally in multiple steps and with a flash effect.

querySelector

abstract suspend fun querySelector(selector: String, node: NodeOrElement? = null): Element?

Finds a single element based on a CSS selector string.

querySelectorAll

abstract suspend fun querySelectorAll(selector: String, node: NodeOrElement? = null): List<Element>

Equivalent of JavaScript's document.querySelectorAll. This is considered one of the main methods to use in this package.

rawEvaluate

abstract suspend fun rawEvaluate(expression: String, awaitPromise: Boolean = false): JsonElement?

Evaluates a JavaScript expression in the context of the tab.

reload

abstract suspend fun reload(ignoreCache: Boolean = true, scriptToEvaluateOnLoad: String? = null)

Reload the current page in the tab.

saveScreenshot

abstract suspend fun saveScreenshot(filename: Path? = null, format: ScreenshotFormat = ScreenshotFormat.JPEG, fullPage: Boolean = false): String

Saves a screenshot of the page. This is not the same as Element.saveScreenshot, which saves a screenshot of a single element only.

screenshotB64

abstract suspend fun screenshotB64(format: ScreenshotFormat = ScreenshotFormat.JPEG, fullPage: Boolean = false): String

Takes a screenshot of the page and returns the result as a base64 encoded string. This is not the same as Element.screenshotB64, which takes a screenshot of a single element only.

scrollDown

abstract suspend fun scrollDown(amount: Int = 25, speed: Int = 800)

Scrolls the tab down by a specified amount.

scrollTo

abstract suspend fun scrollTo(scrollX: Double, scrollY: Double, speed: Int? = null)

Scrolls the page naturally using CDP's synthesizeScrollGesture (P3 - Anti-detection). This creates smooth, human-like scrolling instead of instant jumps.

scrollUp

abstract suspend fun scrollUp(amount: Int = 25, speed: Int = 800)

Scrolls the tab up by a specified amount.

select

abstract suspend fun select(selector: String, timeout: Long): Element

Selects an element in the DOM using a CSS selector.

selectAll

abstract suspend fun selectAll(selector: String, timeout: Long, includeFrames: Boolean = false): List<Element>

Finds multiple elements by CSS selector, optionally waiting for them to appear.

send

inline fun <T> Connection.send(command: <Error class: unknown class>.() -> T): T

Sends a CDP command and waits for the response.

setUserAgent

abstract suspend fun setUserAgent(userAgent: String? = null, acceptLanguage: String? = null, platform: String? = null)

Sets the user agent for the tab.

setWindowState

abstract suspend fun setWindowState(left: Int = 0, top: Int = 0, width: Int = 1280, height: Int = 720, state: String = "normal")

Sets the tab's window state, including position and size.

sleep

abstract suspend fun sleep(t: Long)

Suspends the coroutine for a specified time in milliseconds.

updateTarget

abstract suspend fun updateTarget()

Updates the target information by fetching it from the CDP.

wait

abstract suspend fun wait(t: Long? = null)

Waits until the event listener reports idle (no new events received in a certain timespan). When \`t\` is provided, ensures waiting for \`t\` milliseconds, no matter what.

waitForReadyState

abstract suspend fun waitForReadyState(until: ReadyState = ReadyState.INTERACTIVE, timeout: Long): Boolean

Waits for the document's ready state to reach a specified state.

xpath

abstract suspend fun xpath(xpath: String, timeout: Long): List<Element>

Finds elements by XPath string.