Flutter Golden UI Test ガイド (alchemist & CI決定論的テスト)

Flutterアプリにおいて、意図しないUI崩れ（RenderFlex overflow、パディング・マージンズレ、コンポーネント配置崩れ、ダークモード崩れ等）を検知・防止するためのGolden UI Test（スクリーンショット回帰テスト）基盤の導入・実装・運用ガイドラインです。

1. なぜ OS 間のレンダリング差異が起きるのか？

Flutter標準の matchesGoldenFile や通常のGolden testはピクセル単位でビットマップを比較します。 しかし、ローカル開発環境（macOS）とCIランナー（GitHub Actions の ubuntu-latest / Linux）の間では以下の理由から同じコード・同じフォントであってもピクセルが一致しません：

1. フォントラスタライザの差: macOSは CoreText、Linuxは FreeType を使用するため、アンチエイリアス処理、サブピクセルレンダリング、わずかな文字幅・字詰めが異なります。
2. 影 (BoxShadow) やグラデーションのブレンド計算: OSごとのグラフィックスライブラリやアンチエイリアス処理により、境界線で微細な色差が生じます。

解決策: alchemist の CI Goldens モード（Ahemフォント置換）

Betterment製の alchemist パッケージの CI Goldens モード を標準採用します。 CI Goldensモードでは、テキストが決定論的な Ahem フォント（四角い黒塗りブロック）に自動置換されます。 これにより、OS間のフォント差異を100%排除し、レイアウト、配置、余白、サイズ、配色、コントラスト判定の崩れを決定論的に検証できます。