feat: InternalCdpApi annotation, cdp tutorial, v0.2.3

Author: nathanfallet

README.md

@@ -47,7 +47,7 @@ To use kdriver, add the following to your `build.gradle.kts`:
 
 ```kotlin
 dependencies {
-    implementation("dev.kdriver:core:0.2.2")
+    implementation("dev.kdriver:core:0.2.3")
 }
 ```
 

build.gradle.kts

@@ -6,7 +6,7 @@ plugins {
 
 allprojects {
     group = "dev.kdriver"
-    version = "0.2.2"
+    version = "0.2.3"
 
     repositories {
         mavenCentral()

cdp/build.gradle.kts

@@ -80,6 +80,7 @@ kotlin {
     sourceSets {
         all {
             languageSettings.apply {
+                optIn("dev.kdriver.cdp.InternalCdpApi")
                 optIn("kotlin.js.ExperimentalJsExport")
             }
         }

cdp/src/commonMain/kotlin/dev/kdriver/cdp/CDP.kt

@@ -9,11 +9,16 @@ import kotlin.reflect.KClass
  */
 interface CDP {
 
+    @InternalCdpApi
     val events: Flow<Message.Event>
+
+    @InternalCdpApi
     val responses: Flow<Message.Response>
 
+    @InternalCdpApi
     val generatedDomains: MutableMap<KClass<out Domain>, Domain>
 
+    @InternalCdpApi
     suspend fun callCommand(method: String, parameter: JsonElement?): JsonElement?
 
 }

cdp/src/commonMain/kotlin/dev/kdriver/cdp/InternalCdpApi.kt

@@ -0,0 +1,8 @@
+package dev.kdriver.cdp
+
+@RequiresOptIn(
+    message = "This API is internal to the CDP library. We recommend using the public APIs instead.",
+    level = RequiresOptIn.Level.ERROR
+)
+@Retention(AnnotationRetention.BINARY)
+annotation class InternalCdpApi

core/build.gradle.kts

@@ -56,6 +56,7 @@ kotlin {
     sourceSets {
         all {
             languageSettings.apply {
+                optIn("dev.kdriver.cdp.InternalCdpApi")
                 optIn("kotlin.js.ExperimentalJsExport")
             }
         }

core/src/commonMain/kotlin/dev/kdriver/core/connection/Connection.kt

@@ -1,10 +1,7 @@
 package dev.kdriver.core.connection
 
 import dev.kaccelero.serializers.Serialization
-import dev.kdriver.cdp.CDP
-import dev.kdriver.cdp.Domain
-import dev.kdriver.cdp.Message
-import dev.kdriver.cdp.Request
+import dev.kdriver.cdp.*
 import dev.kdriver.cdp.domain.Target
 import dev.kdriver.cdp.domain.target
 import dev.kdriver.core.browser.Browser
@@ -47,36 +44,18 @@ open class Connection(
 
     private var socketSubscription: Job? = null
 
-    private fun startListening() {
-        socketSubscription?.cancel()
-        socketSubscription = messageListeningScope.launch {
-            try {
-                for (frame in wsSession?.incoming ?: return@launch) {
-                    try {
-                        frame as? Frame.Text ?: continue
-                        val text = frame.readText()
-                        logger.debug("WS < CDP: ${text.take(debugStringLimit)}")
-                        val received = Serialization.json.decodeFromString<Message>(text)
-                        allMessages.emit(received)
-                    } catch (e: Exception) {
-                        logger.debug("WebSocket exception while receiving message: {}", e)
-                    }
-                }
-            } catch (e: Exception) {
-                e.printStackTrace()
-                // Handle disconnect, maybe trigger reconnect logic here
-            }
-        }
-    }
-
     private val currentIdMutex = Mutex()
     private var currentId = 0L
 
     private var allMessages = MutableSharedFlow<Message>(extraBufferCapacity = eventsBufferSize)
 
+    @InternalCdpApi
     override val events: Flow<Message.Event> = allMessages.filterIsInstance()
+
+    @InternalCdpApi
     override val responses: Flow<Message.Response> = allMessages.filterIsInstance()
 
+    @InternalCdpApi
     override val generatedDomains: MutableMap<KClass<out Domain>, Domain> = mutableMapOf()
 
     private suspend fun connect() {
@@ -93,6 +72,34 @@ open class Connection(
         startListening()
     }
 
+    private fun startListening() {
+        socketSubscription?.cancel()
+        socketSubscription = messageListeningScope.launch {
+            try {
+                for (frame in wsSession?.incoming ?: return@launch) {
+                    try {
+                        frame as? Frame.Text ?: continue
+                        val text = frame.readText()
+                        logger.debug("WS < CDP: ${text.take(debugStringLimit)}")
+                        val received = Serialization.json.decodeFromString<Message>(text)
+                        allMessages.emit(received)
+                    } catch (e: Exception) {
+                        logger.debug("WebSocket exception while receiving message: {}", e)
+                    }
+                }
+            } catch (e: Exception) {
+                e.printStackTrace()
+                // Handle disconnect, maybe trigger reconnect logic here
+            }
+        }
+    }
+
+    /**
+     * Internal method to call a CDP command.
+     *
+     * This should not be called directly, but rather through typed methods (like `cdp.network.enable()`).
+     */
+    @InternalCdpApi
     override suspend fun callCommand(method: String, parameter: JsonElement?): JsonElement? {
         connect()
         val requestId = currentIdMutex.withLock { currentId++ }
@@ -104,13 +111,22 @@ open class Connection(
         return result.result
     }
 
+    /**
+     * Closes the websocket connection. Should not be called manually by users.
+     */
+    @InternalCdpApi
     suspend fun close() {
         wsSession?.close()
         wsSession = null
         socketSubscription?.cancel()
         socketSubscription = null
     }
 
+    /**
+     * Updates the target information by fetching it from the CDP.
+     *
+     * This is useful to refresh the target info after some operations that might change it.
+     */
     suspend fun updateTarget() {
         val targetInfo = target.getTargetInfo(targetId)
         this.targetInfo = targetInfo.targetInfo
@@ -149,11 +165,88 @@ open class Connection(
         }
     }
 
+    /**
+     * Suspends the coroutine for a specified time in milliseconds.
+     *
+     * This is a convenience method to ensure that the target information is updated before sleeping.
+     *
+     * @param t Time in milliseconds to sleep.
+     */
     suspend fun sleep(t: Long) {
         updateTarget()
         delay(t)
     }
 
+    /**
+     * Sends a CDP command and waits for the response.
+     *
+     * This is an alias so that you can use cdp the same way as zendriver does:
+     * ```kotlin
+     * // send a network.enable command with kdriver
+     * tab.send { cdp.network.enable() }
+     * ```
+     * That would be equivalent to this with zendriver:
+     * ```python
+     * # send a network.enable command with zendriver
+     * tab.send(cdp.network.enable())
+     * ```
+     *
+     * Although you can directly call the CDP methods on the tab (recommended way of doing it):
+     * ```kotlin
+     * // send a network.enable command with kdriver, directly
+     * tab.network.enable()
+     * ```
+     *
+     * @param command The command to send. This is a suspending function that can call any CDP method.
+     *
+     * @return The result of the command, deserialized to type T.
+     */
+    inline fun <T> send(command: CDP.() -> T): T {
+        return this.command()
+    }
+
+    /**
+     * Adds a handler for a specific CDP event.
+     *
+     * This is an alias so that you can use cdp the same way as zendriver does:
+     * ```kotlin
+     * // add a handler for the consoleAPICalled event with kdriver
+     * tab.addHandler(this, { cdp.runtime.consoleAPICalled }) { event ->
+     *     println(event)
+     * }
+     * ```
+     * That would be equivalent to this with zendriver:
+     * ```python
+     * # add a handler for the consoleAPICalled event with zendriver
+     * tab.add_handler(cdp.runtime.consoleAPICalled, lambda event: print(event))
+     * ```
+     *
+     * Although you can directly collect the events from the tab (recommended way of doing it):
+     * ```kotlin
+     * // add a handler for the consoleAPICalled event with kdriver, directly
+     * launch {
+     *     tab.runtime.consoleAPICalled.collect { event ->
+     *         println(event)
+     *     }
+     * }
+     * ```
+     *
+     * @param coroutineScope The coroutine scope in which the handler will run.
+     * @param event A lambda that returns a Flow of the event type to listen to.
+     * @param handler A suspend function that will be called with each event of the specified type.
+     *
+     * @return A Job that can be used to cancel the handler.
+     */
+    inline fun <T> addHandler(
+        coroutineScope: CoroutineScope,
+        crossinline event: CDP.() -> Flow<T>,
+        crossinline handler: suspend (T) -> Unit,
+    ): Job {
+        return coroutineScope.launch {
+            event().collect { handler(it) }
+        }
+    }
+
     override fun toString(): String {
         return "Connection: ${targetInfo?.toString() ?: "no target"}"
     }

core/src/commonMain/kotlin/dev/kdriver/core/tab/Tab.kt

@@ -1,7 +1,6 @@
 package dev.kdriver.core.tab
 
 import dev.kaccelero.serializers.Serialization
-import dev.kdriver.cdp.CDP
 import dev.kdriver.cdp.CDPException
 import dev.kdriver.cdp.domain.*
 import dev.kdriver.core.browser.Browser
@@ -851,34 +850,6 @@ class Tab(
         // displays for a short time a red dot on the element
     }
 
-    /**
-     * Sends a CDP command and waits for the response.
-     *
-     * This is an alias so that you can use cdp the same way as zendriver does:
-     * ```kotlin
-     * // send a network.enable command with kdriver
-     * tab.send { network.enable() }
-     * ```
-     * That would be equivalent to this with zendriver:
-     * ```python
-     * # send a network.enable command with zendriver
-     * tab.send(network.enable())
-     * ```
-     *
-     * Although you can directly call the CDP methods on the tab (recommended way of doing it):
-     * ```kotlin
-     * // send a network.enable command with kdriver, directly
-     * tab.network.enable()
-     * ```
-     *
-     * @param command The command to send. This is a suspending function that can call any CDP method.
-     *
-     * @return The result of the command, deserialized to type T.
-     */
-    inline fun <T> send(command: CDP.() -> T): T {
-        return this.command()
-    }
-
     /**
      * Expects a request to match the given [urlPattern].
      *

core/src/jvmTest/kotlin/dev/kdriver/core/tab/TabTest.kt

@@ -1,9 +1,7 @@
 package dev.kdriver.core.tab
 
-import dev.kdriver.cdp.cdp
 import dev.kdriver.cdp.domain.Fetch
 import dev.kdriver.cdp.domain.Network
-import dev.kdriver.cdp.domain.network
 import dev.kdriver.core.browser.Browser
 import dev.kdriver.core.exceptions.EvaluateException
 import dev.kdriver.core.exceptions.TimeoutWaitingForElementException
@@ -15,16 +13,6 @@ import kotlin.test.*
 
 class TabTest {
 
-    @Test
-    fun testSend() = runBlocking {
-        val browser = Browser.create(this, headless = true, sandbox = false)
-        val tab = browser.mainTab ?: throw IllegalStateException("Main tab is not available")
-        tab.send { cdp.network.setUserAgentOverride("Test user agent") }
-        val navigatorUserAgent = tab.evaluate<String>("navigator.userAgent")
-        assertEquals("Test user agent", navigatorUserAgent)
-        browser.stop()
-    }
-
     @Test
     fun testSetUserAgentSetsNavigatorValues() = runBlocking {
         val browser = Browser.create(this, headless = true, sandbox = false)

core/src/jvmTest/kotlin/dev/kdriver/tutorials/CdpTest.kt

@@ -0,0 +1,55 @@
+package dev.kdriver.tutorials
+
+import dev.kdriver.cdp.cdp
+import dev.kdriver.cdp.domain.Runtime
+import dev.kdriver.cdp.domain.runtime
+import dev.kdriver.core.browser.Browser
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class CdpTest {
+
+    @Test
+    fun testCdpFunctionality() = runBlocking {
+        val browser = Browser.create(this, headless = true, sandbox = false)
+        val page = browser.get("https://slensky.com/zendriver-examples/console.html")
+
+        // Those 4 lines are equivalent and do the same thing
+        page.runtime.enable()
+        page.cdp.runtime.enable()
+        page.send { runtime.enable() }
+        page.send { cdp.runtime.enable() }
+
+        // Create a listener for console API calls
+        val logs = mutableListOf<String>()
+        val consoleHandler: (Runtime.ConsoleAPICalledParameter) -> Unit = { event ->
+            logs.add("${event.type} - ${event.args.joinToString(", ") { it.value.toString() }}")
+        }
+
+        // Those 4 lines are equivalent and do the same thing
+        val job1 = launch { page.runtime.consoleAPICalled.collect { consoleHandler(it) } }
+        val job2 = launch { page.cdp.runtime.consoleAPICalled.collect { consoleHandler(it) } }
+        val job3 = page.addHandler(this, { runtime.consoleAPICalled }, consoleHandler)
+        val job4 = page.addHandler(this, { cdp.runtime.consoleAPICalled }, consoleHandler)
+
+        page.select("#myButton").click()
+
+        page.wait(1000) // Wait for the console messages to be printed
+
+        // Remember to cancel the job to stop listening to console events
+        job1.cancel()
+        job2.cancel()
+        job3.cancel()
+        job4.cancel()
+
+        assertEquals(
+            List(4) { "log - \"Button clicked!\"" },
+            logs
+        )
+
+        browser.stop()
+    }
+
+}