Asynchronous coroutine-based client for Chrome DevTools Protocol; supports browser automation, debugging, and interaction with Chrome targets through type-safe domain commands and event handling.
An asynchronous coroutine-based multiplatform Kotlin client for the Chrome DevTools Protocol.
Part of this client is generated based on information from the "latest" (a.k.a
"tip-of-tree") JSON descriptors found in the
ChromeDevTools/devtools-protocol repository.
All the domains' commands and events defined in these protocol descriptors are therefore available in
chrome-devtools-kotlin, as well as their doc and deprecated/experimental status.
The protocol definitions are automatically updated daily, but releases of chrome-devtools-kotlin are still manual.
If you're missing some APIs or updates, don't hesitate to open an issue to request a new release with updated protocol.
You can find the protocol version used by chrome-devtools-kotlin after the - in the version number.
For instance, version 1.3.0-861504 of chrome-devtools-kotlin was built using version 861504 of the Chrome
DevTools Protocol (this is technically the Chromium revision, but it gives the tip-of-tree version number of the
protocol).
The Chrome Devtools Protocol defines domains that expose some commands and events. They are subsets of the protocol's API. You can find the list and documentation of all domains in the protocol's web page.
This library defines a type for each domain (e.g. PageDomain, StorageDomain...), which exposes:
suspend method for each command, accepting a request type and returning a response type,
respectively containing the input and output parameters defined in the protocol for that command.The domains usually also expose an enable() command which is required to enable events.
Without calling it, you will receive no events in the Flow subscriptions.
Clients can interact with different parts of Chrome such as pages (tabs), service workers, and extensions. These parts are called targets. The browser itself is also a target.
Each type of target supports a different subset of the domains defined in the protocol.
The protocol requires you to attach to a target in order to interact with it.
Attaching to a target opens a target session of the relevant type, such as BrowserSession or
PageSession.
When connecting to Chrome, a browser target is automatically attached, thus you obtain a BrowserSession.
You can then use this session to attach to other targets (child targets), such as pages.
Each of the supported domains are defined as properties of the session type, which provides a type-safe way to know
if the attached target supports a given domain.
For instance, PageSession.dom gives access to the DOM domain in this page session, which allows to issue commands
and listen to DOM events.
Note: The supported set of domains for each target type is not clearly defined by the protocol, so I have to regularly extract this information from Chromium's source code and update my own extra definition file: target_types.json. This process is described in details in a dedicated README.
Because of this, there might be some missing domains on some session types at some point in time that require manual adjustment. If this is the case, use the method on the session object to get full access to all domains (also, please open an issue so I can fix the missing domain).
This library is available on Maven Central.
It requires a Ktor engine to work, so make sure to add one that
supports the web sockets feature (check the
compatibility table).
For example, you can pick the CIO engine by adding this engine to your dependencies next to chrome-devtools-kotlin:
dependencies {
implementation("org.hildan.chrome:chrome-devtools-kotlin:$version")
implementation("io.ktor:ktor-client-cio:$ktorVersion")
}
This library doesn't provide a way to start a browser programmatically. It assumes a browser was started externally and exposes a debugger server. Below are some options to get a browser running.
Start a Headless Chrome browser using
the zenika/alpine-chrome Docker image with the following command:
docker run --rm -p 9222:9222 zenika/alpine-chrome --no-sandbox --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 about:blank
This exposes the debugger server at http://localhost:9222 (see the next section for how to connect).
Start a Headless Chromium using the Browserless Docker image:
docker run --rm -p 3000:3000 ghcr.io/browserless/chromium
This allows direct web socket connections at ws://localhost:3000 (see the next section for how to connect).
Browserless BaaS provides readily available chrome browsers so you don't have to start anything locally. They have some free plan which might be useful when Docker is not an option.
Once you have registered and got your token, you will be able to connect to the web socket directly using the URL
wss://production-sfo.browserless.io/?token=<TOKEN> (see the next section for how to connect).
Once you got your HTTP or web socket URL to the Chrome debugger, use ChromeDP.connect(url) to connect to the debugger
and start your browser session:
val browserSession: BrowserSession = ChromeDP.connect("http://localhost:9222")
When you're done with the session, don't forget to close() it in order to close the underlying web socket.
You can also use the familiar use { ... } extension, which automatically closes the session in every code path
leaving the lambda (even in case of exception).
The BrowserSession is attached to a browser target, but we're usually interested in more useful targets, such as pages.
Once you have your browser session, you can use it to create child page targets and attach to them.
Here is an example to create a new page target and attach to it:
ChromeDP.connect("http://localhost:9222").use { browserSession ->
browserSession.newPage().use { pageSession ->
// goto() navigates the current page to the URL and awaits the 'load' event by default
pageSession.goto("http://example.com")
// This page session has access to many useful protocol domains (e.g. dom, page...)
val doc = pageSession.dom.getDocument().root
val base64Img = pageSession.page.captureScreenshot {
format = ScreenshotFormat.jpeg
quality = 80
}
} // automatically closes the pageSession
} // automatically closes the browserSession
In addition to the generated domain commands and events, some extensions are provided for higher-level functionality. You can discover them using auto-complete in your IDE.
The most useful of them are documented in this section.
PageSession.goto(url: String): navigates to a URL and also waits for the next load event, or other eventsPageSession.clickOnElement(selector: CssSelector, clickDuration: Duration, mouseButton: MouseButton): finds a node
using a selector query and simulates a click on itCaptureScreenshotResponse.decodeData(): ByteArray: decodes a base64 encoded image (from PageDomain.captureScreenshot) into bytesPageDomain.captureScreenshotToFile(outputFile: Path, options) (JVM-only)<T> RuntimeDomain.evaluateJs(js: String): T?: evaluates JS and returns the result (uses Kotlinx serialization to
deserialize JS results)Example usage of Runtime.evaluateJs(js: String):
@Serializable
data class Person(val firstName: String, val lastName: String)
val evaluatedInt = pageSession.runtime.evaluateJs<Int>("42")
assertEquals(42, evaluatedInt)
val evaluatedPerson = pageSession.runtime.evaluateJs<Person>("""eval({firstName: "Bob", lastName: "Lee Swagger"})""")
assertEquals(Person("Bob", "Lee Swagger"), evaluatedPerson)
Note that the deserialization here uses Kotlinx Serialization,
which requires annotating the deserialized classes with @Serializable and using the corresponding compiler plugin.
Host header is specified and is not an IP address or localhost
Sometimes this error also appears in the form of an HTTP 500.
Chrome doesn't accept a Host header that is not an IP nor localhost, but in some environments it might be hard
to provide this (e.g. docker services in a docker swarm, communicating using service names).
To work around this problem, simply set overrideHostHeader to true when creating ChromeDPClient.
This overrides the Host header to "localhost" in the HTTP requests to the Chrome debugger to make it happy, and
also replaces the host in subsequent web socket URLs (returned by Chrome) by the initial host provided in
remoteDebugUrl.
This is necessary because Chrome uses the Host header to build these URLs, and it would be incorrect to keep this.
This project is distributed under the MIT license.
If you're looking for Chrome Devtools Protocol clients in Kotlin, I have only found one other so far, chrome-reactive-kotlin. This is the reactive equivalent of this project. The main differences are the following:
unsafe() in chrome-devtools-kotlin)I needed a coroutine-based API instead and more type-safety, which is how this chrome-devtools-kotlin
project was born.
You can find alternative Chrome DevTools libraries in other languages in this awesome list.
Special thanks to @wendigo and his project chrome-reactive-kotlin which inspired the creation of this project.
suspendFlow of this particular event typeevents() method, returning a Flow of all events of the domainPageSession.unsafe()DOMDomain.getNodeBySelector(selector: CssSelector): NodeId?: finds a node using a selector query, or throws if not foundDOMDomain.findNodeBySelector(selector: CssSelector): NodeId?: finds a node using a selector query, or returns nullDOMDomain.awaitNodeBySelector(selector: CssSelector, pollingPeriod: Duration): NodeId?: suspends until a node
corresponding to the selector query appears in the DOM.DOMDomain.awaitNodeAbsentBySelector(selector: CssSelector, pollingPeriod: Duration): NodeId?: suspends until a node
corresponding to the selector query disappears from the DOM.DOMDomain.getTypedAttributes(nodeSelector: CssSelector): DOMAttributes?: gets the attributes of the node
corresponding to the given nodeSelector, or null if the selector didn't match any node.DOMDomain.getAttributeValue(nodeSelector: CssSelector, attributeName: String): String?: gets the value of the
attribute attributeName of the node corresponding to the given nodeSelector, or null if the node wasn't found.DOMDomain.setAttributeValue(nodeSelector: CssSelector, name: String, value: String): sets the value of the
attribute attributeName of the node corresponding to the given nodeSelector.Surfaced from shared tags and platforms — no rankings paid for.