docs(ui): make docs snapshots authentic to the production SDK

[xsahil03x]

Summary

Reworks the docs_screenshots golden suite so every snapshot looks like the real app instead of a Material approximation. The pivots:

• Pin the platform. Override CurrentPlatform, defaultTargetPlatform, and ThemeData.platform to iOS in a docsGoldenTest wrapper. Set inside alchemist's pumpWidget hook, reset via whilePerforming's cleanup callback — the only timing that satisfies _verifyInvariants. Snapshots render identically on macOS dev and Linux CI.
• Real San Francisco on macOS. _loadAppleSystemFont registers /System/Library/Fonts/SFNS.ttf under the CupertinoSystemDisplay / CupertinoSystemText family aliases Material's iOS typography expects. Apple Color Emoji loaded the same way. No more Roboto stand-in.
• Real user avatars. 18 portrait fixtures sourced directly from Figma node 2867:55922 ("User Photo") live under test/fixtures/avatars/. A networkImage StreamComponentBuilder (installed via GoldenComponentFactory) resolves any URL by its slug (https://docs.fixture/avatar/amelia-moore.png → that fixture). Adding a new avatar is two lines: drop a PNG + add the slug to _avatarSlugs.
• Named sample users. test/src/sample_users.dart exports 18 named User constants matching the Figma roster (ameliaMoore, noahSmith, …) plus a single ownUser (OwnUser) for the signed-in identity used across every snapshot. User(id: 'user-2', name: 'Bob', …) literals are gone.
• Chrome matches sample_app. StreamChannelListHeader everywhere a generic AppBar used to live (with trailing: StreamButton.icon(icons.plus)), bottom nav copies sample's Chats / Threads two-tab theming verbatim, StreamSheetHeader for the poll creator, message-actions modal uses StreamMessageActionsBuilder.buildActions + StreamContextMenuAction.partitioned so Delete lands at the end under a separator. Empty states use the SDK's default StreamScrollViewEmptyWidget.
• Real Slidable + real drag. The slidable snapshots now wrap each row in Slidable (sample app's exact ActionPane with BehindMotion, more + mute) and trigger the reveal via whilePerforming: (tester) async { await tester.drag(...); await tester.pumpAndSettle(); }. ~70 lines of Stack + Transform.translate fakery deleted.
• Mock fidelity. setupMockChannel defaults to a deterministic 2–6 member group seeded off channel.id (so the Engineering channel happens to surface the +N overflow chip), stubs channel.memberCount so group headers read "3 Members" instead of misleading "Last online a few seconds ago".
• macOS workflow for docs goldens. update_goldens.yml gained a target: sdk|docs dispatch input — SDK target stays on ubuntu-latest, docs target runs on macos-latest for authoritative platform-variant regen. Auto-commit patterns are scoped so the two jobs never fight.
• Gitignore actually enforces macOS-only. Previous !**/goldens/macos/* was a no-op without a preceding ignore. Now **/test/**/goldens/** ignores by default with !.../macos/ (re-include the directory) + !.../macos/** (re-include files) — both lines required because git can't re-include a file beneath an ignored directory.

What this fixes / adds

Before	After
Snapshots flake between hosts (mic button visibility, font metrics)	Pinned platform — same render anywhere
AppBar/TextField text rendered as Ahem tofu	Real SF on macOS, Roboto/CI obscured on Linux runners
Gradient-letter avatar placeholders	18 real portraits matching the design system
Generic AppBar('Stream Chat') everywhere	StreamChannelListHeader with avatar leading + plus trailing
Custom 6-action message menu with Material icons	SDK's canonical 9-action menu, destructive partitioned to end
Fake Transform.translate slidable	Real Slidable + real swipe gesture
channel.image: null → "Last online a few seconds ago" on group channels	Stubbed memberCount → "3 Members"

Test plan

• fvm flutter analyze — no issues across the suite
• fvm flutter test (no --update-goldens) — 41/41 pass
• fvm flutter test --update-goldens — clean regeneration, all goldens stable across local runs
• update_goldens workflow with target=docs on macOS — verified end-to-end, bot auto-commits PNGs scoped to docs/**/goldens/macos/*.png

🤖 Generated with Claude Code

📦 Migration guide — bringing #2649's snapshots onto this branch

#2649 ("docs(ui): more docs screenshots") adds four new snapshot scenarios (flutter_showcase, localization_support, theming, stream_message_composer extensions) plus a GoldenComponentFactory and a docsScreenshotsDarkTheme(). This branch reshapes most of that surface area. Here's how to land #2649's content on top of these patterns.

TL;DR

#2649 ships	This branch wants you to use
Inline User(id: 'user-1', name: 'Mace Windu', …)	Sample users from test/src/sample_users.dart — ameliaMoore, noahSmith, etc.
final _currentUser = OwnUser(id: 'user-1', name: 'Alice')	ownUser (already an OwnUser, single source of truth)
goldenTest('…', …)	docsGoldenTest('…', …) — pins platform, wraps in GoldenComponentFactory, precaches images
GoldenComponentFactory wrapped inside every scaffold	Auto-applied by docsGoldenTest — drop the manual wrap
import 'package:alchemist/alchemist.dart';	Not needed anymore (the helper re-exports what tests use)
final _redTheme = ThemeData(…) hand-built	Extend docsScreenshotsTheme() (preserves platform: TargetPlatform.iOS, fontFamily: CupertinoSystemText, etc.)
stream_chat_localizations added to pubspec.yaml	Same — but goes under dev_dependencies, not dependencies

File-by-file

test/src/golden_component_factory.dart

Already on this branch — delete #2649's copy entirely and accept ours. It also overrides networkImage to render avatar fixtures, which #2649's version doesn't.

test/src/golden_theme.dart

#2649 adds docsScreenshotsDarkTheme(). Keep that addition, but rebuild it from our light theme so it inherits the platform pin and SF font setup. Sketch:

ThemeData docsScreenshotsDarkTheme() {
  final streamTextTheme = core.StreamTextTheme().apply(
    color: core.StreamColorScheme.dark().systemText,
    fontFamily: 'CupertinoSystemText',
  );
  return ThemeData(
    useMaterial3: true,
    brightness: Brightness.dark,
    platform: docsScreenshotsTargetPlatform,
    scaffoldBackgroundColor: const Color(0xFF000000),
    appBarTheme: const AppBarTheme(backgroundColor: Color(0xFF000000)),
    extensions: [
      StreamTheme(brightness: Brightness.dark, textTheme: streamTextTheme),
    ],
  );
}

test/theming/theming_test.dart

• Replace final _currentUser = OwnUser(id: 'user-1', name: 'Mace Windu') → ownUser.
• Replace final _otherUser = User(id: 'user-2', name: 'Lando Calrissian') → pick a sample user (e.g. noahSmith). If the original "Mace / Lando" identities matter for the brand demo, add them to sample_users.dart and ship matching PNGs to test/fixtures/avatars/.
• _redTheme() should compose from docsScreenshotsTheme() — copy its body and override extensions with the red StreamColorScheme. Keep the platform: and fontFamily: lines so iOS typography + SF font still resolve.
• Use docsGoldenTest(...) instead of goldenTest(...).
• Remove the inline GoldenComponentFactory(child: ...) wrap — docsGoldenTest already handles it.

test/localization/localization_support_test.dart

• Replace inline User(id: 'user-1', name: 'Alice') → ownUser.
• Each per-locale phone wraps StreamChannel in MaterialApp. Use theme: docsScreenshotsTheme() so SF + Roboto fallback work in every locale.
• Add stream_chat_localizations: ^10.0.0-beta.13 to dev_dependencies (not dependencies — the docs package is publish_to: none).
• Switch to docsGoldenTest. Remove manual GoldenComponentFactory.

test/flutter_showcase/flutter_showcase_test.dart

• The four phone crops use light + dark themes — pass docsScreenshotsTheme() and the new docsScreenshotsDarkTheme() (see above).
• Inline User(id: 'user-2', name: 'Bassett') etc. → pick from sampleUsers. If you need the actual bassett identity for the marketing image, add it to sample_users.dart + drop a PNG into test/fixtures/avatars/.
• Use docsGoldenTest. Remove any explicit GoldenComponentFactory wraps.
• setupMockChannel now defaults to a deterministic 2–6 member group and stubs channel.memberCount. If the showcase phones need a specific member count, pass members: [...] explicitly.

test/message_input/stream_message_composer_test.dart & test/message_list/message_widget_test.dart

• The "message input custom buttons" and "message reaction theming" additions from docs(ui): showcase, localization, theming, and composer snapshots #2649 mostly survive — but swap User(id: 'other-user', …) → ameliaMoore / noahSmith / similar.
• Replace any goldenTest(...) with docsGoldenTest(...).
• Drop import 'package:alchemist/alchemist.dart'; if it's only used for goldenTest.

Channel + member defaults

#2649's tests construct channels via setupMockChannel or fakeChannel without specifying members or capabilities. This branch now:

• Defaults to a deterministic 2–6 sample-user group (seeded off channel.id) so each channel gets a unique stacked-avatar group.
• Stubs channel.image: null so StreamChannelInfo derives the avatar from members.
• Stubs channel.memberCount so group headers render "N Members" instead of "Last online a few seconds ago".

If a #2649 test relies on a single specific member or a channel.image, pass them explicitly. Otherwise the defaults give you authentic group avatars for free.

Workflow

#2649 doesn't touch CI. Once these tests land, run them via the new workflow:

gh workflow run update_goldens.yml --ref <branch> -f target=docs

The macOS job will render fresh goldens/macos/*.png and auto-commit them. Don't commit local goldens — let the workflow produce the authoritative bytes (local macOS rendering drifts by a few bytes from CI macOS).

Quick checklist

• Delete docs(ui): showcase, localization, theming, and composer snapshots #2649's golden_component_factory.dart — use ours.
• Move all User(id: …, name: …) literals into sample_users.dart (or reference existing constants).
• Replace goldenTest → docsGoldenTest. Drop the alchemist import if unused.
• Drop manual GoldenComponentFactory(child: …) wraps from each scaffold.
• Rebuild any custom ThemeData() to compose from docsScreenshotsTheme() so the platform pin and SF setup carry through.
• Add stream_chat_localizations under dev_dependencies.
• Drop any custom emptyBuilder / hand-rolled "no items" widgets — let the SDK render its default.
• Don't commit golden PNGs locally; dispatch update_goldens.yml with target=docs.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b7e9dae3-5c2a-4800-ac3b-eb3563862db3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/snapshots-platform-pin

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[renefloor]

This is now from Noah

[xsahil03x]

Yes, we now use users from the list we created