@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-testing/SKILL.md

@@ -1,376 +1,57 @@
 ---
 name: cometchat-ios-testing
-description: Testing patterns for CometChat iOS UI Kit v5 in Swift / SwiftUI / UIKit projects. Covers XCTest setup, mocking CometChatSDK + CometChatUIKitSwift via protocols, snapshot testing with iOSSnapshotTestCase, async/await test helpers, UI testing for full chat flows on simulators, and CI on Xcode Cloud / GitHub Actions.
+description: "Test an iOS app that embeds CometChat — what to mock vs exercise for real, keeping the CometChatSDK off the network in unit tests, waiting out the async init→login gate, and a lean XCUITest smoke. Triggers: 'test cometchat ios', 'unit test chat swift', 'mock cometchatsdk', 'xcuitest for chat', 'how do I test cometchat swift'."
 license: "MIT"
-compatibility: "Xcode 15+, Swift 5.9+, iOS 13+ deployment target; XCTest (built-in); SnapshotTesting >= 1.15 (Pointfree); CometChatUIKitSwift ~> 5.1"
+compatibility: "CometChatUIKitSwift 5.1.22 + CometChatSDK 4.1.7; Xcode 16+; iOS 15.1+; XCTest / XCUITest"
 metadata:
   author: "CometChat"
-  version: "4.0.0"
-  tags: "cometchat ios testing xctest swift uikit swiftui mocking snapshot async-await ui-tests xcode-cloud github-actions"
+  version: "1.0.0"
+  tags: "cometchat ios swift testing xctest xcuitest mock"
 ---
 
-## Purpose
+> **Ground truth:** `CometChatUIKitSwift` 5.1.22 + `CometChatSDK` 4.1.7 (symbols verified vs `catalogs/ios-v5.json`); signatures FETCHED via `cometchat-ios-core/references/docs-map.md`. **The iOS UI Kit docs have no dedicated testing page** — this is the pack's own guidance (tracked DOCS GAP). The kit ships prebuilt view controllers/SwiftUI views; do not assert against their internal view hierarchy.
 
-Testing patterns for iOS CometChat integrations. XCTest (built-in) for unit + integration; SnapshotTesting (Pointfree) for visual regression; XCUITest for full-flow UI tests on the simulator.
+## Companion skills (read first)
+- `cometchat-ios-core` — the init→login→render lifecycle and the credential flow these tests exercise.
 
-**Read these other skills first:**
-- `cometchat-ios-core` — init, login, Secrets pattern
-- `cometchat-ios-components` — what each VC does (tests assert against this)
-- `cometchat-ios-calls/references/callkit-and-pushkit.md` — CallKit testing strategy (different from chat)
+## Use this skill when
+Adding tests around a CometChat iOS integration, or a "how do I test this" question. NOT part of a normal build — only when tests are explicitly requested (`RULES.md` → Verification scope).
 
-**Ground truth:** **Official docs:** https://www.cometchat.com/docs/ui-kit/ios/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
-- XCTest — https://developer.apple.com/documentation/xctest
-- SnapshotTesting — https://github.com/pointfreeco/swift-snapshot-testing
+## Decide what you are testing
+Test **your** code, not the kit. Three layers:
+- **Your logic** (token fetch, UID mapping, view-model state, routing) → `XCTest` in isolation, keep the SDK off the network.
+- **Your wiring** (the chat screen appears after init+login; the right IDs are passed) → a host-app test that drives the launch hook.
+- **The real round-trip** (send → receive) → a thin `XCUITest` against a test app, not a unit test.
 
----
-
-## 1. Test target structure
-
-A typical iOS project has three targets:
-
-| Target | When |
-|---|---|
-| `YourApp` | Production code |
-| `YourAppTests` | Unit + integration tests (XCTest) |
-| `YourAppUITests` | UI tests (XCUITest, runs on simulator) |
-
-The skill writes to `YourAppTests` for most assertions; `YourAppUITests` for full flows.
-
----
-
-## 2. Mocking the SDK via protocols
-
-The CometChat SDKs are class-based with static methods (`CometChat.init`, `CometChat.login`). Hard to mock directly. **Wrap them in protocols you own:**
-
-```swift
-// Protocols/CometChatService.swift
-import CometChatSDK
-
-// CometChatException does NOT conform to Swift's Error, so a throwing
-// continuation can't resume with it directly — bridge it through this.
-struct CometChatTestError: Error { let message: String }
-
-protocol CometChatServiceProtocol {
-  func initialize(appId: String, region: String) async throws
-  func login(uid: String, authKey: String) async throws -> User
-  func logout() async throws
-  func getLoggedInUser() -> User?
-  func sendMessage(_ message: TextMessage) async throws -> TextMessage
-}
-
-// Production implementation
-final class CometChatService: CometChatServiceProtocol {
-  func initialize(appId: String, region: String) async throws {
-    try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
-      let settings = AppSettings.AppSettingsBuilder()
-        .subscribePresenceForAllUsers()
-        .setRegion(region: region)
-        .build()
-      CometChat.init(appId: appId, appSettings: settings, onSuccess: { _ in
-        cont.resume()
-      }, onError: { error in
-        cont.resume(throwing: CometChatTestError(message: error.errorDescription))
-      })
-    }
-  }
-
-  func login(uid: String, authKey: String) async throws -> User {
-    try await withCheckedThrowingContinuation { (cont: CheckedContinuation<User, Error>) in
-      CometChat.login(UID: uid, authKey: authKey, onSuccess: { cont.resume(returning: $0) },
-                      onError: { cont.resume(throwing: CometChatTestError(message: $0.errorDescription)) })
-    }
-  }
-
-  // ... etc
-}
-```
-
-Inject the protocol via DI:
-
-```swift
-final class ChatViewController: UIViewController {
-  private let service: CometChatServiceProtocol
-
-  init(service: CometChatServiceProtocol = CometChatService()) {
-    self.service = service
-    super.init(nibName: nil, bundle: nil)
-  }
-  required init?(coder: NSCoder) { fatalError() }
-}
-```
-
-Test with a mock:
-
-```swift
-// Tests/CometChatServiceMock.swift
-final class CometChatServiceMock: CometChatServiceProtocol {
-  var initializeCallCount = 0
-  var initializeError: Error?
-  var loginUser: User?
-  var loginError: Error?
-
-  func initialize(appId: String, region: String) async throws {
-    initializeCallCount += 1
-    if let error = initializeError { throw error }
-  }
-
-  func login(uid: String, authKey: String) async throws -> User {
-    if let error = loginError { throw error }
-    return loginUser ?? User(uid: uid, name: "Test User")
-  }
-
-  func logout() async throws {}
-  func getLoggedInUser() -> User? { loginUser }
-  func sendMessage(_ message: TextMessage) async throws -> TextMessage { message }
-}
-```
-
----
-
-## 3. XCTest patterns
-
-### Async/await tests
-
-```swift
-import XCTest
-@testable import YourApp
-
-final class ChatViewControllerTests: XCTestCase {
-  func testInitializeRunsBeforeLogin() async throws {
-    let mock = CometChatServiceMock()
-    let vc = ChatViewController(service: mock)
-
-    await vc.bootstrapCometChat()
-
-    XCTAssertEqual(mock.initializeCallCount, 1)
-    XCTAssertNotNil(vc.currentUser)
-  }
-
-  func testLoginFailureSurfacesError() async throws {
-    let mock = CometChatServiceMock()
-    mock.loginError = NSError(domain: "Test", code: 401, userInfo: [NSLocalizedDescriptionKey: "Unauthorized"])
-
-    let vc = ChatViewController(service: mock)
-    await vc.bootstrapCometChat()
-
-    XCTAssertEqual(vc.errorMessage, "Unauthorized")
-    XCTAssertEqual(vc.errorLabel?.textColor, .red)            // skill rule: error UI must be visible
-  }
-}
-```
-
-### Expectation-based tests (legacy / non-async code)
-
-```swift
-func testMessageSendFiresCallback() {
-  let expectation = expectation(description: "message sent")
-
-  let mock = CometChatServiceMock()
-  let vc = ChatViewController(service: mock)
-  vc.send(message: "Hello") { _ in
-    expectation.fulfill()
-  }
-
-  wait(for: [expectation], timeout: 1.0)
-}
-```
-
-For SDK callback-based code, prefer wrapping in protocol + async/await per Section 2; this pattern is for legacy code only.
-
----
-
-## 4. SwiftUI view tests
+Do not unit-test that the kit's message list renders — that is the kit's own surface.
 
+## Keep the SDK off the network in unit tests
+Put your CometChat calls behind a protocol your view-models depend on, and inject a fake in tests:
 ```swift
-import SwiftUI
-import XCTest
-@testable import YourApp
-
-@MainActor
-final class ProfileViewTests: XCTestCase {
-  func testCallButtonInvokesService() throws {
-    let mock = CallServiceMock()
-    let view = ProfileView(user: testUser(), callService: mock)
-
-    let host = UIHostingController(rootView: view)
-    host.loadViewIfNeeded()
-
-    // Hard to interact with SwiftUI views from XCTest directly — use ViewInspector or UI tests
-    // For most behavioral tests, prefer XCUITest (Section 6)
-  }
-}
-```
-
-Pure SwiftUI testing is hard; pragmatic choice is to keep most tests at the service / view-model layer and put view assertions in UI tests.
-
-### ViewInspector (third-party)
-
-For SwiftUI views you do want to inspect from XCTest, install `ViewInspector`:
-
-```swift
-import ViewInspector
-
-func testProfileShowsUserName() throws {
-  let user = testUser()
-  let view = ProfileView(user: user)
-  let text = try view.inspect().find(text: user.name)
-  XCTAssertNotNil(text)
-}
-```
-
-Adds a runtime dep. Not strictly necessary if you have UI tests.
-
----
-
-## 5. Snapshot testing
-
-```bash
-# Package.swift dependency
-.package(url: "https://github.com/pointfreeco/swift-snapshot-testing.git", from: "1.15.0")
+protocol ChatAuthing { func login(authToken: String) async throws -> String }   // returns uid
+final class FakeChatAuth: ChatAuthing { func login(authToken: String) async throws -> String { "u1" } }
 ```
+Test your token-fetch, error handling, and UID mapping against `FakeChatAuth` — no real `CometChatUIKit.login`, no network, no Auth Key in the test target. Injecting the real implementation only in the app keeps unit tests fast and hermetic.
 
+## The init→login gate in host-app tests
+The chat screen mounts only after `initFromSettings` + `login` resolve (both async). A test that asserts immediately after presenting the screen races the gate — wait for a stable, YOUR-owned element (a title, an accessibility identifier you set), with an expectation/timeout, not a fixed sleep:
 ```swift
-import SnapshotTesting
-import XCTest
-@testable import YourApp
-
-final class ChatViewSnapshotTests: XCTestCase {
-  func testEmptyChatView() {
-    let view = ChatView(messages: [])
-    let host = UIHostingController(rootView: view)
-    assertSnapshot(matching: host, as: .image(on: .iPhone13))
-  }
-
-  func testChatViewWithMessages() {
-    let messages = [
-      TextMessage(receiverUid: "alice", text: "Hi", receiverType: .user),
-      TextMessage(receiverUid: "bob", text: "Hey", receiverType: .user),
-    ]
-    let view = ChatView(messages: messages)
-    let host = UIHostingController(rootView: view)
-    assertSnapshot(matching: host, as: .image(on: .iPhone13))
-  }
-}
+let list = app.otherElements["conversationsScreen"]   // an identifier YOU set on your container
+XCTAssertTrue(list.waitForExistence(timeout: 20))
 ```
+Set `accessibilityIdentifier`s on your own containers so UI tests have stable anchors that survive kit updates.
 
-First run creates the reference image; subsequent runs diff against it. Commit the `__Snapshots__` directory.
-
-**Gotcha:** snapshot tests are sensitive to font rendering — if CI uses a different macOS version than dev, snapshots won't match. Pin runners to a known version.
-
----
-
-## 6. UI tests (XCUITest)
-
-```swift
-import XCTest
-
-final class ChatUITests: XCTestCase {
-  override func setUp() {
-    continueAfterFailure = false
-    let app = XCUIApplication()
-    app.launchEnvironment["UI_TEST_MODE"] = "1"
-    app.launchEnvironment["TEST_UID"] = "cometchat-uid-1"
-    app.launch()
-  }
-
-  func testLoginAndSeeConversations() {
-    let app = XCUIApplication()
-    XCTAssertTrue(app.staticTexts["Welcome"].waitForExistence(timeout: 10))
-    app.buttons["Messages"].tap()
-    XCTAssertTrue(app.staticTexts["Conversations"].waitForExistence(timeout: 10))
-  }
-
-  func testSendMessage() {
-    let app = XCUIApplication()
-    app.buttons["Messages"].tap()
-    app.buttons["cometchat-uid-2"].tap()
-
-    let composer = app.textFields["Type a message"]
-    composer.tap()
-    composer.typeText("Hello from UI test")
-    app.buttons["Send"].tap()
-
-    XCTAssertTrue(app.staticTexts["Hello from UI test"].waitForExistence(timeout: 5))
-  }
-}
-```
-
-**`UI_TEST_MODE` flag:** in production code, check this env var and skip animations / use shorter timeouts:
-
-```swift
-if ProcessInfo.processInfo.environment["UI_TEST_MODE"] == "1" {
-  UIView.setAnimationsEnabled(false)
-}
-```
-
-**Test users:** UI tests need real login. Use the dev `cometchat-uid-1` through `cometchat-uid-5`; never use production credentials.
-
----
-
-## 7. CI configuration
-
-### GitHub Actions
-
-```yaml
-name: tests
-on: [push, pull_request]
-
-jobs:
-  unit:
-    runs-on: macos-13                              # pin macOS version for snapshot stability
-    steps:
-      - uses: actions/checkout@v4
-      - run: |
-          xcodebuild test \
-            -scheme YourApp \
-            -destination "platform=iOS Simulator,name=iPhone 15,OS=17.0" \
-            -only-testing:YourAppTests \
-            COMETCHAT_TEST_APP_ID="${{ secrets.TEST_COMETCHAT_APP_ID }}" \
-            COMETCHAT_TEST_REGION="${{ secrets.TEST_COMETCHAT_REGION }}" \
-            COMETCHAT_TEST_AUTH_KEY="${{ secrets.TEST_COMETCHAT_AUTH_KEY }}"
-
-  ui:
-    runs-on: macos-13
-    needs: unit
-    steps:
-      - uses: actions/checkout@v4
-      - run: |
-          xcodebuild test \
-            -scheme YourApp \
-            -destination "platform=iOS Simulator,name=iPhone 15,OS=17.0" \
-            -only-testing:YourAppUITests \
-            COMETCHAT_TEST_APP_ID="${{ secrets.TEST_COMETCHAT_APP_ID }}"
-```
-
-### Xcode Cloud
-
-Configure in App Store Connect → Xcode Cloud. Use the same env var convention; Xcode Cloud injects them into `xcodebuild` automatically.
-
----
-
-## 8. Anti-patterns
-
-1. **Mocking CometChat directly** (without the protocol wrapper). The static methods aren't swappable; you'd need OCMock and method swizzling. The protocol wrapper is cleaner.
-2. **Using real WebSocket connections** in unit tests. They're flaky on CI. Mock the service layer.
-3. **Snapshot tests on a Mac with system font preference different from CI.** Pin macOS + Xcode versions.
-4. **Hardcoding `cometchat-uid-1` strings** across many tests. Centralize via a `TestUsers` enum so renames are one-edit.
-5. **Skipping `continueAfterFailure = false`** in UI tests. Default UI tests continue running after a failure, hiding root causes in cascade failures.
-6. **Storing test credentials in `Secrets.swift`.** Use env vars passed via `xcodebuild` and read via `ProcessInfo.processInfo.environment["..."]` in test bundles only.
-
-## 9. Verification checklist
+## XCUITest smoke
+One high-value path against a **real test app** (seeded users; a test-only Auth Key supplied via the scheme's env, never the release config): launch, sign in, assert the conversation screen appears and a message can be sent. Assert on your accessibility identifiers and visible text — never the kit's internal view tree. Keep it to the happy path + one auth-failure path.
 
-- [ ] `CometChatServiceProtocol` (or similar) wrapping the SDK; production VCs use it via DI
-- [ ] Mock implementation in `Tests/Mocks/`
-- [ ] At least one test for "init resolves before VC is functional"
-- [ ] At least one test for "error UI shows on init/login failure"
-- [ ] Snapshot tests for at least the empty + populated states of chat surfaces
-- [ ] At least one UI test for login + see conversations
-- [ ] Test target uses dedicated CometChat test App ID via env vars (not Secrets.swift)
-- [ ] CI pinned to macOS + Xcode versions
-- [ ] No `continueAfterFailure = true` in UI tests
+## Not worth automating
+Kit view internals, exhaustive option matrices, live calls/VoIP push (device- and entitlement-dependent), and screenshot snapshots of kit UI (they churn across kit versions). Spend the budget on your token flow, UID mapping, and the init-gate wiring.
 
-## 10. Pointers
+## Common pitfalls
+1. **Fixed `sleep()` instead of `waitForExistence`** — flaky against the async init gate.
+2. **Asserting on kit view internals** — brittle; anchor on your own `accessibilityIdentifier`s.
+3. **A real login (and Auth Key) in the unit-test target** — hide it behind a protocol + fake; keep secrets out of tests.
+4. **Testing on the release configuration** — use a test scheme whose env carries the dev Auth Key, so production stays token-only.
 
-- `cometchat-ios-calls/references/callkit-and-pushkit.md` — calls + CallKit testing
-- `cometchat-ios-core` — init, login, Secrets patterns the tests assert against
-- `cometchat-ios-troubleshooting` — when tests pass but production breaks
+## Verify it works
+Unit tests pass with a fake auth (no network, no Auth Key in the target) · a host-app/UI test waits out the init gate and finds your identified container · the XCUITest smoke signs in and shows conversations against a test app · no test asserts a kit-internal view.