test(realtime): add comprehensive tests for Phase 1 components

This commit adds extensive unit tests for all four new actor-based components
introduced in Phase 1, ensuring correct behavior and thread safety.

**Test Coverage:**

1. **ConnectionStateMachineTests** (10 tests, ~200 LOC)
   - Initial state verification
   - Successful connection
   - Connection reuse on multiple calls
   - Concurrent connect calls create single connection
   - Disconnect behavior
   - Error handling and reconnection
   - Close handling
   - Disconnection triggers reconnect
   - Reconnection cancellation

2. **HeartbeatMonitorTests** (8 tests, ~160 LOC)
   - Heartbeats sent at correct intervals
   - Stop cancels heartbeats
   - Heartbeat response clears pending ref
   - Timeout detection when not acknowledged
   - Mismatched ref doesn't clear pending
   - Restart creates new monitor
   - Stop when not started is safe

3. **AuthTokenManagerTests** (12 tests, ~180 LOC)
   - Initialization with/without token
   - Token provider called when needed
   - Provider not called when token exists
   - Update token returns change status
   - Update to nil
   - Refresh token calls provider
   - Refresh without provider
   - Refresh updates internal token
   - Provider error handling
   - Concurrent access safety
   - Token property access

4. **MessageRouterTests** (11 tests, ~240 LOC)
   - Route to registered channels
   - Unregistered channels don't crash
   - System handlers receive all messages
   - Both system and channel handlers work
   - Unregister stops routing
   - Re-register replaces handler
   - Reset removes all handlers
   - Channel count accuracy
   - Multiple system handlers
   - Concurrent routing

**Test Quality:**

- ✅ Actor isolation tested
- ✅ Concurrent access tested
- ✅ Edge cases covered
- ✅ Error conditions validated
- ✅ Timing-sensitive tests made robust
- ✅ Cleanup verified

**Total:** 41 new tests, ~780 LOC of test code

All tests passing with comprehensive coverage of component behavior.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: grdsdev

Tests/RealtimeTests/AuthTokenManagerTests.swift

@@ -0,0 +1,192 @@
+//
+//  AuthTokenManagerTests.swift
+//  Realtime Tests
+//
+//  Created on 17/01/25.
+//
+
+import Foundation
+import XCTest
+
+@testable import Realtime
+
+final class AuthTokenManagerTests: XCTestCase {
+  var manager: AuthTokenManager!
+
+  override func tearDown() async throws {
+    manager = nil
+    try await super.tearDown()
+  }
+
+  // MARK: - Tests
+
+  func testInitWithToken() async {
+    manager = AuthTokenManager(initialToken: "initial-token", tokenProvider: nil)
+
+    let token = await manager.getCurrentToken()
+
+    XCTAssertEqual(token, "initial-token")
+  }
+
+  func testInitWithoutToken() async {
+    manager = AuthTokenManager(initialToken: nil, tokenProvider: nil)
+
+    let token = await manager.getCurrentToken()
+
+    XCTAssertNil(token)
+  }
+
+  func testGetCurrentTokenCallsProviderWhenNoToken() async {
+    var providerCallCount = 0
+
+    manager = AuthTokenManager(
+      initialToken: nil,
+      tokenProvider: {
+        providerCallCount += 1
+        return "provider-token"
+      }
+    )
+
+    let token = await manager.getCurrentToken()
+
+    XCTAssertEqual(token, "provider-token")
+    XCTAssertEqual(providerCallCount, 1)
+
+    // Second call should use cached token, not call provider again
+    let token2 = await manager.getCurrentToken()
+
+    XCTAssertEqual(token2, "provider-token")
+    XCTAssertEqual(providerCallCount, 1, "Should not call provider again")
+  }
+
+  func testGetCurrentTokenReturnsInitialTokenWithoutCallingProvider() async {
+    var providerCallCount = 0
+
+    manager = AuthTokenManager(
+      initialToken: "initial-token",
+      tokenProvider: {
+        providerCallCount += 1
+        return "provider-token"
+      }
+    )
+
+    let token = await manager.getCurrentToken()
+
+    XCTAssertEqual(token, "initial-token")
+    XCTAssertEqual(providerCallCount, 0, "Should not call provider when token exists")
+  }
+
+  func testUpdateTokenReturnsTrueWhenChanged() async {
+    manager = AuthTokenManager(initialToken: "old-token", tokenProvider: nil)
+
+    let changed = await manager.updateToken("new-token")
+
+    XCTAssertTrue(changed)
+
+    let token = await manager.getCurrentToken()
+    XCTAssertEqual(token, "new-token")
+  }
+
+  func testUpdateTokenReturnsFalseWhenSame() async {
+    manager = AuthTokenManager(initialToken: "same-token", tokenProvider: nil)
+
+    let changed = await manager.updateToken("same-token")
+
+    XCTAssertFalse(changed)
+  }
+
+  func testUpdateTokenToNil() async {
+    manager = AuthTokenManager(initialToken: "some-token", tokenProvider: nil)
+
+    let changed = await manager.updateToken(nil)
+
+    XCTAssertTrue(changed)
+
+    let token = await manager.token
+    XCTAssertNil(token)
+  }
+
+  func testRefreshTokenCallsProvider() async {
+    var providerCallCount = 0
+
+    manager = AuthTokenManager(
+      initialToken: "initial-token",
+      tokenProvider: {
+        providerCallCount += 1
+        return "refreshed-token-\(providerCallCount)"
+      }
+    )
+
+    let token1 = await manager.refreshToken()
+
+    XCTAssertEqual(token1, "refreshed-token-1")
+    XCTAssertEqual(providerCallCount, 1)
+
+    // Refresh again
+    let token2 = await manager.refreshToken()
+
+    XCTAssertEqual(token2, "refreshed-token-2")
+    XCTAssertEqual(providerCallCount, 2)
+  }
+
+  func testRefreshTokenWithoutProviderReturnsCurrentToken() async {
+    manager = AuthTokenManager(initialToken: "current-token", tokenProvider: nil)
+
+    let token = await manager.refreshToken()
+
+    XCTAssertEqual(token, "current-token")
+  }
+
+  func testRefreshTokenUpdatesInternalToken() async {
+    manager = AuthTokenManager(
+      initialToken: "old-token",
+      tokenProvider: { "new-token" }
+    )
+
+    _ = await manager.refreshToken()
+
+    let token = await manager.token
+    XCTAssertEqual(token, "new-token")
+  }
+
+  func testProviderThrowingError() async {
+    manager = AuthTokenManager(
+      initialToken: nil,
+      tokenProvider: {
+        throw NSError(domain: "test", code: 1)
+      }
+    )
+
+    let token = await manager.getCurrentToken()
+
+    XCTAssertNil(token, "Should return nil when provider throws")
+  }
+
+  func testConcurrentAccess() async {
+    manager = AuthTokenManager(initialToken: "initial", tokenProvider: nil)
+
+    // Concurrent updates
+    await withTaskGroup(of: Void.self) { group in
+      for i in 0..<100 {
+        group.addTask {
+          _ = await self.manager.updateToken("token-\(i)")
+        }
+      }
+
+      await group.waitForAll()
+    }
+
+    // Should have some token (race condition, but should not crash)
+    let token = await manager.token
+    XCTAssertNotNil(token)
+    XCTAssertTrue(token!.starts(with: "token-"))
+  }
+
+  func testTokenPropertyReturnsCurrentValue() async {
+    manager = AuthTokenManager(initialToken: "test-token", tokenProvider: nil)
+
+    let token = await manager.token
+
+    XCTAssertEqual(token, "test-token")
+  }
+}

Tests/RealtimeTests/ConnectionStateMachineTests.swift

@@ -0,0 +1,194 @@
+//
+//  ConnectionStateMachineTests.swift
+//  Realtime Tests
+//
+//  Created on 17/01/25.
+//
+
+import Foundation
+import XCTest
+
+@testable import Realtime
+
+final class ConnectionStateMachineTests: XCTestCase {
+  var stateMachine: ConnectionStateMachine!
+  var mockWebSocket: FakeWebSocket!
+  var connectCallCount = 0
+  var lastConnectURL: URL?
+  var lastConnectHeaders: [String: String]?
+
+  override func setUp() async throws {
+    try await super.setUp()
+    connectCallCount = 0
+    lastConnectURL = nil
+    lastConnectHeaders = nil
+    (mockWebSocket, _) = FakeWebSocket.fakes()
+  }
+
+  override func tearDown() async throws {
+    stateMachine = nil
+    mockWebSocket = nil
+    try await super.tearDown()
+  }
+
+  // MARK: - Helper
+
+  func makeStateMachine(
+    url: URL = URL(string: "ws://localhost")!,
+    headers: [String: String] = [:],
+    reconnectDelay: TimeInterval = 0.1
+  ) -> ConnectionStateMachine {
+    ConnectionStateMachine(
+      transport: { [weak self] url, headers in
+        self?.connectCallCount += 1
+        self?.lastConnectURL = url
+        self?.lastConnectHeaders = headers
+        return self!.mockWebSocket
+      },
+      url: url,
+      headers: headers,
+      reconnectDelay: reconnectDelay,
+      logger: nil
+    )
+  }
+
+  // MARK: - Tests
+
+  func testInitialStateIsDisconnected() async {
+    stateMachine = makeStateMachine()
+
+    let connection = await stateMachine.connection
+    let isConnected = await stateMachine.isConnected
+
+    XCTAssertNil(connection)
+    XCTAssertFalse(isConnected)
+  }
+
+  func testConnectSuccessfully() async throws {
+    stateMachine = makeStateMachine(
+      url: URL(string: "ws://example.com")!,
+      headers: ["Authorization": "Bearer token"]
+    )
+
+    let connection = try await stateMachine.connect()
+
+    XCTAssertNotNil(connection)
+    XCTAssertEqual(connectCallCount, 1)
+    XCTAssertEqual(lastConnectURL?.absoluteString, "ws://example.com")
+    XCTAssertEqual(lastConnectHeaders?["Authorization"], "Bearer token")
+
+    let isConnected = await stateMachine.isConnected
+    XCTAssertTrue(isConnected)
+  }
+
+  func testMultipleConnectCallsReuseConnection() async throws {
+    stateMachine = makeStateMachine()
+
+    let connection1 = try await stateMachine.connect()
+    let connection2 = try await stateMachine.connect()
+    let connection3 = try await stateMachine.connect()
+
+    XCTAssertEqual(connectCallCount, 1, "Should only connect once")
+    XCTAssertTrue(connection1 === mockWebSocket)
+    XCTAssertTrue(connection2 === mockWebSocket)
+    XCTAssertTrue(connection3 === mockWebSocket)
+  }
+
+  func testConcurrentConnectCallsCreateSingleConnection() async throws {
+    stateMachine = makeStateMachine()
+
+    // Simulate concurrent connect calls
+    async let connection1 = stateMachine.connect()
+    async let connection2 = stateMachine.connect()
+    async let connection3 = stateMachine.connect()
+
+    let results = try await [connection1, connection2, connection3]
+
+    XCTAssertEqual(connectCallCount, 1, "Should only connect once despite concurrent calls")
+    XCTAssertTrue(results.allSatisfy { $0 === mockWebSocket })
+  }
+
+  func testDisconnectClosesConnection() async throws {
+    stateMachine = makeStateMachine()
+
+    _ = try await stateMachine.connect()
+    XCTAssertFalse(mockWebSocket.isClosed)
+
+    await stateMachine.disconnect(reason: "test disconnect")
+
+    XCTAssertTrue(mockWebSocket.isClosed)
+    XCTAssertEqual(mockWebSocket.closeReason, "test disconnect")
+
+    let isConnected = await stateMachine.isConnected
+    XCTAssertFalse(isConnected)
+  }
+
+  func testDisconnectWhenDisconnectedIsNoop() async {
+    stateMachine = makeStateMachine()
+
+    // Should not crash
+    await stateMachine.disconnect()
+
+    let isConnected = await stateMachine.isConnected
+    XCTAssertFalse(isConnected)
+  }
+
+  func testHandleErrorTriggersReconnect() async throws {
+    stateMachine = makeStateMachine(reconnectDelay: 0.05)
+
+    _ = try await stateMachine.connect()
+    XCTAssertEqual(connectCallCount, 1)
+
+    // Simulate error
+    await stateMachine.handleError(NSError(domain: "test", code: 1))
+
+    // Wait for reconnect delay
+    try await Task.sleep(nanoseconds: 100_000_000) // 0.1 seconds
+
+    // Should have reconnected
+    XCTAssertEqual(connectCallCount, 2, "Should have reconnected after error")
+  }
+
+  func testHandleCloseDisconnects() async throws {
+    stateMachine = makeStateMachine()
+
+    _ = try await stateMachine.connect()
+
+    await stateMachine.handleClose(code: 1000, reason: "normal closure")
+
+    let isConnected = await stateMachine.isConnected
+    XCTAssertFalse(isConnected)
+  }
+
+  func testHandleDisconnectedTriggersReconnect() async throws {
+    stateMachine = makeStateMachine(reconnectDelay: 0.05)
+
+    _ = try await stateMachine.connect()
+    XCTAssertEqual(connectCallCount, 1)
+
+    await stateMachine.handleDisconnected()
+
+    // Wait for reconnect
+    try await Task.sleep(nanoseconds: 100_000_000)
+
+    XCTAssertEqual(connectCallCount, 2, "Should have reconnected")
+  }
+
+  func testDisconnectCancelsReconnection() async throws {
+    stateMachine = makeStateMachine(reconnectDelay: 0.2)
+
+    _ = try await stateMachine.connect()
+
+    // Trigger reconnection
+    await stateMachine.handleError(NSError(domain: "test", code: 1))
+
+    // Immediately disconnect before reconnection completes
+    await stateMachine.disconnect()
+
+    // Wait longer than reconnect delay
+    try await Task.sleep(nanoseconds: 300_000_000)
+
+    // Should only have connected once (reconnection was cancelled)
+    XCTAssertEqual(connectCallCount, 1)
+  }
+}