uts: add inline documentation for fake clocks, HTTP, and WebSocket mocks

- Added KDoc comments to `FakeClock`, `MockHttpClient`, and `MockWebSocket` explaining their purpose and usage.

Author: ttypic

uts/src/test/kotlin/io/ably/lib/test/mock/FakeClock.kt

@@ -6,6 +6,12 @@ import io.ably.lib.util.TimerInstance
 import java.util.TimerTask
 import kotlin.time.Duration
 
+/**
+ * Virtual clock for deterministic time control in unit tests.
+ *
+ * Install via `enableFakeTimers(fakeClock)` inside a `TestRealtimeClient` or `TestRestClient` block.
+ * Time only advances when [advance] is called; timer callbacks fire synchronously within that call.
+ */
 class FakeClock(initialTimeMs: Long = 0L) : Clock {
     @Volatile private var time = initialTimeMs
     private val timers = mutableMapOf<String, FakeNamedTimer>()
@@ -18,13 +24,16 @@ class FakeClock(initialTimeMs: Long = 0L) : Clock {
         return t
     }
 
+    /** Advance virtual time by [ms] milliseconds, firing any timers that become due. */
     fun advance(ms: Long) {
         time += ms
         timers.values.forEach { it.fireDue(time) }
     }
 
+    /** Advance virtual time by [time], firing any timers that become due. */
     fun advance(time: Duration) = advance(time.inWholeMilliseconds)
 
+    /** Number of tasks currently scheduled on the named timer — useful for asserting retry state. */
     fun pendingTaskCount(timerName: String) = timers[timerName]?.pendingCount ?: 0
 
     inner class FakeNamedTimer(val name: String) : NamedTimer {

uts/src/test/kotlin/io/ably/lib/test/mock/MockHttpClient.kt

@@ -9,11 +9,22 @@ import kotlinx.coroutines.withTimeout
 import kotlin.time.Duration
 import kotlin.time.Duration.Companion.seconds
 
+/**
+ * Callbacks for [MockHttpClient]. Both fields are optional.
+ *
+ * When a callback is set it is invoked synchronously; when null the event queues for the
+ * corresponding `await*` method.
+ */
 class HttpMockConfig {
+    /** Called for every TCP connection attempt. Leave null to use [MockHttpClient.awaitConnectionAttempt]. */
     var onConnectionAttempt: ((PendingConnection) -> Unit)? = null
+    /** Called for every HTTP request. Leave null to use [MockHttpClient.awaitRequest]. */
     var onRequest: ((PendingRequest) -> Unit)? = null
 }
 
+/**
+ * Fake HTTP engine for SDK unit tests. Install via [installOn] or `TestRestClient`/`TestRealtimeClient`.
+ */
 class MockHttpClient(private val config: HttpMockConfig = HttpMockConfig()) {
     private var _pendingConnections = Channel<PendingConnection>(Channel.UNLIMITED)
     private var _pendingRequests = Channel<PendingRequest>(Channel.UNLIMITED)
@@ -29,20 +40,24 @@ class MockHttpClient(private val config: HttpMockConfig = HttpMockConfig()) {
         },
     )
 
+    /** Wire this mock into [options] so the SDK uses it instead of a real HTTP client. */
     fun installOn(options: DebugOptions) {
         options.httpEngine = engine
     }
 
+    /** Suspend until the SDK opens a TCP connection. Only usable when [HttpMockConfig.onConnectionAttempt] is null. */
     suspend fun awaitConnectionAttempt(timeout: Duration = 5.seconds): PendingConnection =
         withContext(Dispatchers.Default.limitedParallelism(1)) {
             withTimeout(timeout) { _pendingConnections.receive() }
         }
 
+    /** Suspend until the SDK makes an HTTP request. Only usable when [HttpMockConfig.onRequest] is null. */
     suspend fun awaitRequest(timeout: Duration = 5.seconds): PendingRequest =
         withContext(Dispatchers.Default.limitedParallelism(1)) {
             withTimeout(timeout) { _pendingRequests.receive() }
         }
 
+    /** Clear all queued pending connections and requests. Call between tests when reusing a mock instance. */
     fun reset() {
         _pendingConnections.close()
         _pendingRequests.close()

uts/src/test/kotlin/io/ably/lib/test/mock/MockWebSocket.kt

@@ -15,15 +15,36 @@ import java.util.Collections
 import kotlin.time.Duration
 import kotlin.time.Duration.Companion.seconds
 
+/**
+ * Callbacks for [MockWebSocket]. All fields are optional.
+ *
+ * When a callback is set it receives the event immediately (synchronous, on the SDK's thread).
+ * When a callback is null the event is queued for the corresponding `await*` method instead.
+ * The two styles cannot be mixed for the same event type.
+ */
 class WebSocketMockConfig {
+    /** Called for every connection attempt. Set to respond inline; leave null to use [MockWebSocket.awaitConnectionAttempt]. */
     var onConnectionAttempt: ((PendingConnection) -> Unit)? = null
+    /** Called for every decoded protocol message from the SDK. Leave null to use [MockWebSocket.awaitNextMessageFromClient]. */
     var onMessageFromClient: ((ProtocolMessage) -> Unit)? = null
+    /** Raw text frame callback — rarely needed; prefer [onMessageFromClient]. */
     var onTextDataFrame: ((String) -> Unit)? = null
+    /** Raw binary frame callback — rarely needed; prefer [onMessageFromClient]. */
     var onBinaryDataFrame: ((ByteArray) -> Unit)? = null
 }
 
+/**
+ * Fake WebSocket transport for SDK unit tests. Install via [installOn] or `TestRealtimeClient`.
+ *
+ * Two usage styles for connection/message handling (cannot mix per event type):
+ * - **Callback** (`onConnectionAttempt`, `onMessageFromClient` in [WebSocketMockConfig]): handle
+ *   inline, synchronously on the SDK thread. Preferred for single-behaviour setups.
+ * - **Await** ([awaitConnectionAttempt], [awaitNextMessageFromClient]): suspend until the SDK
+ *   triggers the event. Required when initial and reconnection attempts need different behaviour.
+ */
 class MockWebSocket(config: WebSocketMockConfig = WebSocketMockConfig()) {
     private val _events = Collections.synchronizedList(mutableListOf<MockEvent>())
+    /** Snapshot of all events recorded since construction (or last [reset]). */
     val events: List<MockEvent> get() = _events.toList()
 
     private var _pendingConnections = Channel<PendingConnection>(Channel.UNLIMITED)
@@ -82,31 +103,37 @@ class MockWebSocket(config: WebSocketMockConfig = WebSocketMockConfig()) {
         },
     )
 
+    /** Wire this mock into [options] so the SDK uses it instead of a real WebSocket. */
     fun installOn(options: DebugOptions) {
         options.webSocketEngineFactory = engineFactory
     }
 
+    /** Suspend until the SDK opens a new WebSocket connection. Only usable when [WebSocketMockConfig.onConnectionAttempt] is null. */
     suspend fun awaitConnectionAttempt(timeout: Duration = 5.seconds): PendingConnection =
         withContext(Dispatchers.Default.limitedParallelism(1)) {
             withTimeout(timeout) { _pendingConnections.receive() }
         }
 
+    /** Suspend until the SDK sends a protocol message to the server. Only usable when [WebSocketMockConfig.onMessageFromClient] is null. */
     suspend fun awaitNextMessageFromClient(timeout: Duration = 5.seconds): ProtocolMessage =
         withContext(Dispatchers.Default.limitedParallelism(1)) {
             withTimeout(timeout) { _messagesFromClient.receive() }
         }
 
+    /** Suspend until the SDK sends a WebSocket close frame. */
     suspend fun awaitClientClose(timeout: Duration = 5.seconds): MockEvent.ClientClose =
         withContext(Dispatchers.Default.limitedParallelism(1)) {
             withTimeout(timeout) { _clientCloseEvents.receive() }
         }
 
+    /** Deliver [message] from the fake server to the SDK over the active connection. */
     fun sendToClient(message: ProtocolMessage) {
         val listener = checkNotNull(activeListener) { "No active WebSocket connection" }
         _events.add(MockEvent.SentToClient(message))
         listener.onMessage(Serialisation.gson.toJson(message))
     }
 
+    /** Deliver [message] to the SDK then immediately close the connection with code 1000. */
     fun sendToClientAndClose(message: ProtocolMessage) {
         val listener = checkNotNull(activeListener) { "No active WebSocket connection" }
         _events.add(MockEvent.SentToClient(message))
@@ -115,13 +142,15 @@ class MockWebSocket(config: WebSocketMockConfig = WebSocketMockConfig()) {
         listener.onClose(1000, "Normal closure")
     }
 
+    /** Simulate an abnormal network drop (close code 1006). Triggers DISCONNECTED on the SDK. */
     fun simulateDisconnect() {
         val listener = checkNotNull(activeListener) { "No active WebSocket connection" }
         _events.add(MockEvent.Disconnected)
         activeListener = null
         listener.onClose(1006, "Abnormal closure")
     }
 
+    /** Clear all queued events and pending channels. Call between tests when reusing a mock instance. */
     fun reset() {
         _pendingConnections.close()
         _messagesFromClient.close()