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

events

abstract val events: Flow<Message.Event>

generatedDomains

abstract val generatedDomains: MutableMap<KClass<out Domain>, Domain>

responses

abstract val responses: Flow<Message.Response>

targetId

open val targetId: String?

targetInfo

abstract var targetInfo: Target.TargetInfo?

type

open val type: 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: CDP.() -> 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 override fun callCommand(method: String, parameter: JsonElement?, mode: CommandMode): 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: Regex, block: suspend RequestExpectation.() -> T): T

Expects a request to match the given urlPattern.

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(): Browser.GetWindowForTargetReturn

Gets the current window information for the tab.

intercept

abstract suspend fun <T> intercept(urlPattern: String, requestStage: Fetch.RequestStage, resourceType: Network.ResourceType, 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: Input.MouseButton = 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.

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: CDP.() -> 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.