test(llc): migrate the stream_chat test suite to the stream_chat_test algebra

STYLE_GUIDE.md

@@ -997,6 +997,10 @@ functions called inside each test block. For cleanup, prefer `addTearDown` over
 global `tearDown` callback — `addTearDown` registers cleanup at the exact point a
 resource is created, ensuring it only runs if initialization succeeded.
 
+The `setUp:` parameter of `chatClientTest` / `channelTest` is a different thing and is
+fine to use: it runs once per test against that test's own tester, and shares nothing
+with the tests around it.
+
 ### Prefer more test files, avoid long test files
 
 Organize tests into smaller files grouped by feature, widget, or behavior. It's easier
@@ -1029,6 +1033,52 @@ persistence client, WebSocket). Do not mock every collaborator.
   mock.method(any(named: 'foo')))` pattern; do not hand-roll a fake that duplicates the
   full interface.
 
+For `stream_chat` those seams are already replaced for you — see
+[Use the `stream_chat_test` harness for `stream_chat` tests](#use-the-stream_chat_test-harness-for-stream_chat-tests).
+
+### Use the `stream_chat_test` harness for `stream_chat` tests
+
+`chatClientTest` / `channelTest`, from the `stream_chat_test` package, build a **real**
+`StreamChatClient` with only the REST API, the WebSocket transport and — when asked
+for — the persistence client swapped out, so event decoding, state, retries and
+reconnection all run production code. Do not hand-roll a mocked `StreamChatClient`
+for these tests. See the package's README for the full API.
+
+```dart
+// BAD — mocking the subject itself; nothing underneath it is exercised.
+final client = MockStreamChatClient();
+when(() => client.markAllRead()).thenAnswer((_) async => EmptyResponse());
+
+// GOOD — the client, its state and the event pipeline are real; only the
+// REST call is stubbed.
+chatClientTest(
+  '`.markAllRead` marks every channel as read',
+  body: (tester) async {
+    tester.mockApi(
+      (api) => api.channel.markAllRead(),
+      result: createDefaultEmptyResponse(),
+    );
+
+    await tester.client.markAllRead();
+
+    tester.verifyApi((api) => api.channel.markAllRead());
+  },
+);
+```
+
+Three conventions keep that harness trustworthy. Breaking them tends to produce a
+confusing mismatch rather than a clear failure:
+
+- **Stub with exact argument values wherever the value is known.** A mocktail stub
+  only answers on a match, so an exact stub doubles as verification of the request
+  the SDK actually sent. Reach for `any()` only when the SDK stamps the argument
+  itself (e.g. a `Message`, which gets a local timestamp and sender attached).
+- **Keep fixtures deterministic.** Build them with the `createDefaultXxx` factories
+  and pass timestamps explicitly — a `DateTime.now()` in test data makes
+  equality-based matching differ from run to run.
+- **Use UTC for any `DateTime` inside an emitted event.** Emitted events go through
+  real JSON decoding, and local times do not survive that round-trip intact.
+
 ### Golden tests
 
 Widget tests that verify pixel-level rendering use the `alchemist` package. Golden

TESTING.md

@@ -138,6 +138,10 @@ The helpers (`_emptyChannelListController`, `_pumpChannelListView`) live at the
 of the test file. Their names tell the reader what they do; the reader doesn't need to
 look inside unless something breaks.
 
+When testing `stream_chat`, the `connect:` and `setUp:` phases of `chatClientTest` /
+`channelTest` are where this setup belongs, so the body holds only the behavior under
+test.
+
 ## Optimize tests for comprehension
 
 Even a well-factored test benefits from small edits that separate "the thing under
@@ -241,5 +245,7 @@ your machine — see [Golden tests in STYLE_GUIDE.md](STYLE_GUIDE.md#golden-test
 
 - [STYLE_GUIDE.md — Testing](STYLE_GUIDE.md#testing) — repo-level testing conventions
   (mocktail, alchemist golden tests, self-contained tests, `addTearDown`).
+- [`packages/stream_chat_test/README.md`](packages/stream_chat_test/README.md) — the
+  `chatClientTest` / `channelTest` harness used by the `stream_chat` test suite.
 - Flutter's [Writing-Effective-Tests](https://github.com/flutter/flutter/blob/master/docs/contributing/testing/Writing-Effective-Tests.md)
   — the source this guide was adapted from.

melos.yaml

@@ -85,6 +85,7 @@ command:
       media_kit_video: ^2.0.1
       meta: ^1.9.1
       mime: ^2.0.0
+      mocktail: ^1.0.5
       package_info_plus: ">=9.0.1 <11.0.0"
       path: ^1.9.1
       path_provider: ^2.1.5
@@ -116,6 +117,7 @@ command:
           ref: 2aea1413997af886ee951921d71e6b8cb8c5cfbb
           path: packages/stream_thumbnail
       synchronized: ^3.4.0
+      test: ^1.31.1
       url_launcher: ^6.3.2
       uuid: ^4.5.3
       video_player: ^2.11.1

packages/stream_chat/pubspec.yaml

@@ -45,4 +45,6 @@ dev_dependencies:
   freezed: ^3.0.0
   json_serializable: ^6.13.2
   mocktail: ^1.0.5
+  stream_chat_test:
+    path: ../stream_chat_test
   test: ^1.31.1

packages/stream_chat/test/src/client/channel/channel_capability_check_test.dart

@@ -1,60 +1,35 @@
 // ignore_for_file: deprecated_member_use_from_same_package
 
-import 'package:mocktail/mocktail.dart';
 import 'package:stream_chat/stream_chat.dart';
-import 'package:test/test.dart';
-
-import '../../fakes.dart';
-import '../../mocks.dart';
+import 'package:stream_chat_test/stream_chat_test.dart';
 
 void main() {
   group('ChannelCapabilityCheck', () {
-    const channelId = 'test-channel-id';
-    const channelType = 'test-channel-type';
-    late final client = MockStreamChatClient();
-
-    setUpAll(() {
-      // detached loggers
-      when(() => client.detachedLogger(any())).thenAnswer((invocation) {
-        final name = invocation.positionalArguments.first;
-        return _createLogger(name);
-      });
-
-      final retryPolicy = RetryPolicy(
-        shouldRetry: (_, __, ___) => false,
-        delayFactor: Duration.zero,
-      );
-      when(() => client.retryPolicy).thenReturn(retryPolicy);
-
-      // fake clientState
-      final clientState = FakeClientState();
-      when(() => client.state).thenReturn(clientState);
-
-      // client logger
-      when(() => client.logger).thenReturn(_createLogger('mock-client-logger'));
-    });
-
-    /// Parameterized test for channel capability extension properties
+    /// Parameterized test for channel capability extension properties.
     void testCapability(
       String capabilityName,
       ChannelCapability capability,
       bool Function(Channel) getterMethod,
     ) {
-      test('can$capabilityName returns false when capability is absent', () {
-        final channelState = _generateChannelState(channelId, channelType);
-        final channel = Channel.fromState(client, channelState);
-        expect(getterMethod(channel), false);
-      });
-
-      test('can$capabilityName returns true when capability is present', () {
-        final channelState = _generateChannelState(
-          channelId,
-          channelType,
-          ownCapabilities: [capability],
-        );
-        final channel = Channel.fromState(client, channelState);
-        expect(getterMethod(channel), true);
-      });
+      channelTest(
+        'can$capabilityName returns false when capability is absent',
+        setUp: (tester) => tester.watch(),
+        body: (tester) async {
+          expect(getterMethod(tester.channel), false);
+        },
+      );
+
+      channelTest(
+        'can$capabilityName returns true when capability is present',
+        setUp: (tester) => tester.watch(
+          modifyResponse: (state) => state.copyWith(
+            channel: createDefaultChannelModel(ownCapabilities: [capability]),
+          ),
+        ),
+        body: (tester) async {
+          expect(getterMethod(tester.channel), true);
+        },
+      );
     }
 
     // Test all channel capabilities using the parameterized function
@@ -310,101 +285,73 @@ void main() {
       (channel) => channel.canNotifyGroup,
     );
 
-    test('returns correct values with multiple capabilities', () {
-      final channelState = _generateChannelState(
-        channelId,
-        channelType,
-        ownCapabilities: [
-          ChannelCapability.sendMessage,
-          ChannelCapability.sendReply,
-          ChannelCapability.deleteOwnMessage,
-        ],
+    channelTest(
+      'returns correct values with multiple capabilities',
+      setUp: (tester) => tester.watch(
+        modifyResponse: (state) => state.copyWith(
+          channel: createDefaultChannelModel(
+            ownCapabilities: [
+              ChannelCapability.sendMessage,
+              ChannelCapability.sendReply,
+              ChannelCapability.deleteOwnMessage,
+            ],
+          ),
+        ),
+      ),
+      body: (tester) async {
+        expect(tester.channel.canSendMessage, true);
+        expect(tester.channel.canSendReply, true);
+        expect(tester.channel.canDeleteOwnMessage, true);
+        expect(tester.channel.canDeleteAnyMessage, false);
+        expect(tester.channel.canUpdateChannel, false);
+      },
+    );
+    group('usesLocalUnreadCount', () {
+      channelTest(
+        'is false when disabled and read receipts are unavailable',
+        setUp: (tester) => tester.watch(),
+        body: (tester) async {
+          expect(tester.channel.usesLocalUnreadCount, false);
+        },
+      );
+
+      channelTest(
+        'is false when disabled and read receipts are available',
+        setUp: (tester) => tester.watch(
+          modifyResponse: (state) => state.copyWith(
+            channel: createDefaultChannelModel(
+              ownCapabilities: [ChannelCapability.readEvents],
+            ),
+          ),
+        ),
+        body: (tester) async {
+          expect(tester.channel.usesLocalUnreadCount, false);
+        },
       );
 
-      final channel = Channel.fromState(client, channelState);
-      expect(channel.canSendMessage, true);
-      expect(channel.canSendReply, true);
-      expect(channel.canDeleteOwnMessage, true);
-      expect(channel.canDeleteAnyMessage, false);
-      expect(channel.canUpdateChannel, false);
-    });
+      channelTest(
+        'is false when enabled but the channel supports read receipts',
+        isLocalUnreadCountEnabled: true,
+        setUp: (tester) => tester.watch(
+          modifyResponse: (state) => state.copyWith(
+            channel: createDefaultChannelModel(
+              ownCapabilities: [ChannelCapability.readEvents],
+            ),
+          ),
+        ),
+        body: (tester) async {
+          expect(tester.channel.usesLocalUnreadCount, false);
+        },
+      );
 
-    group('usesLocalUnreadCount', () {
-      // `isLocalUnreadCountEnabled` is a settable field on the mock and the
-      // client is shared across the group, so reset it between tests.
-      tearDown(() => client.isLocalUnreadCountEnabled = false);
-
-      Channel channelWithReadEvents({required bool available}) {
-        final channelState = _generateChannelState(
-          channelId,
-          channelType,
-          ownCapabilities: [
-            if (available) ChannelCapability.readEvents,
-          ],
-        );
-
-        final channel = Channel.fromState(client, channelState);
-        addTearDown(channel.dispose);
-
-        return channel;
-      }
-
-      test('is false when disabled and read receipts are unavailable', () {
-        client.isLocalUnreadCountEnabled = false;
-        final channel = channelWithReadEvents(available: false);
-        expect(channel.usesLocalUnreadCount, false);
-      });
-
-      test('is false when disabled and read receipts are available', () {
-        client.isLocalUnreadCountEnabled = false;
-        final channel = channelWithReadEvents(available: true);
-        expect(channel.usesLocalUnreadCount, false);
-      });
-
-      test('is false when enabled but the channel supports read receipts', () {
-        client.isLocalUnreadCountEnabled = true;
-        final channel = channelWithReadEvents(available: true);
-        expect(channel.usesLocalUnreadCount, false);
-      });
-
-      test('is true when enabled and read receipts are unavailable', () {
-        client.isLocalUnreadCountEnabled = true;
-        final channel = channelWithReadEvents(available: false);
-        expect(channel.usesLocalUnreadCount, true);
-      });
+      channelTest(
+        'is true when enabled and read receipts are unavailable',
+        isLocalUnreadCountEnabled: true,
+        setUp: (tester) => tester.watch(),
+        body: (tester) async {
+          expect(tester.channel.usesLocalUnreadCount, true);
+        },
+      );
     });
   });
 }
-
-// region Test Helpers
-
-ChannelState _generateChannelState(
-  String channelId,
-  String channelType, {
-  DateTime? lastMessageAt,
-  List<ChannelCapability>? ownCapabilities,
-  bool mockChannelConfig = false,
-}) {
-  ChannelConfig? config;
-  if (mockChannelConfig) {
-    config = MockChannelConfig();
-    when(() => config!.readEvents).thenReturn(true);
-    when(() => config!.typingEvents).thenReturn(true);
-  }
-  final channel = ChannelModel(
-    id: channelId,
-    type: channelType,
-    config: config,
-    ownCapabilities: ownCapabilities,
-    lastMessageAt: lastMessageAt,
-  );
-  return ChannelState(channel: channel);
-}
-
-Logger _createLogger(String name) {
-  final logger = Logger.detached(name)..level = Level.ALL;
-  logger.onRecord.listen(print);
-  return logger;
-}
-
-// endregion