flutter-golden-test

用途

Flutter Golden Test 技能让 Flutter 初学者也能搭建 Golden Test（视觉回归测试）环境，并以交互方式为组件或页面创建、执行 Golden Test。其目标是通过保存 Widget 截图，自动验证后续改动是否意外改变了外观，从而在保证 UI 质量的前提下安心重构。

触发场景包括：

“想引入 Golden Test”“搭建黄金测试”
“想做截图测试”“添加 UI 测试”
“为组件编写 Golden Test”
“执行 Golden Test”“更新黄金文件”

主要能力

技能以“资深 Flutter 测试工程师”的角色进行需求访谈，原则是一次只问一个问题，等待用户回答后再进入下一步，并支持以下工作模式：

初始搭建模式：当项目中没有 Golden Test 环境时执行。按顺序完成 8 个步骤（不可跳过）：
- Step 0：说明 Golden Test 是什么、可以做什么、示例测试与文件结构、执行命令
- Step 1：解析项目（检查 test/flutter_test_config.dart、test/helpers/golden_test_helper.dart、pubspec.yaml 字体设置、主题文件位置）
- Step 2：确认字体设置（Noto Sans JP / Roboto / 自定义 / 不需要）
- Step 3：确认是否使用 Riverpod，并根据情况引导选择复用既有测试辅助文件或新建独立配置
- Step 4：确认主题设置（自定义主题或默认 Material Theme）
- Step 5：确认测试用屏幕尺寸预设（组件用与页面用）
- Step 6：确认是否使用图片资源，并添加相应加载配置
- Step 7：确认测试创建粒度（组件单位 / 页面单位 / 每次确认），并记录到项目 CLAUDE.md
- Step 8：生成文件
测试生成模式：在已有 Golden Test 环境下创建新测试。步骤包括确认测试对象、根据 CLAUDE.md 的粒度设置确认测试类型、解析 Widget 并检查警告（网络图片、日文字体兼容性）、解析 Widget 参数并选择要测试的状态、生成测试代码。
测试执行与更新模式：提供执行命令指引，包括运行验证、更新 Golden 文件、运行全部 Golden Test、更新指定目录的 Golden Test。
故障排查模式：确认错误信息、期望与实际差异、环境信息，参照常见问题给出解决方案，并将问题与解决记录写入 test/golden_test_issues.md，必要时追加到 CLAUDE.md。

使用方式

技能以对话方式驱动，逐问逐答，不会一次抛出多个问题。在初始搭建完成后会生成以下文件：

test/flutter_test_config.dart：全局测试设置（字体加载、图标字体加载）
test/helpers/golden_test_helper.dart：辅助文件，包含 GoldenTestSizes 尺寸预设、GoldenTestExtension（pumpGoldenWidget()、pumpGoldenWidgetList()）、GoldenFilePath 路径生成工具；使用 Riverpod 时另参考对应模板
test/helpers/helpers.dart：导出辅助文件的 barrel 文件
test/golden_test_issues.md：问题解决日志
在项目 CLAUDE.md 中追加 Golden Test 设置（含测试创建粒度）

测试文件生成后，Golden 文件路径规则为：

组件：goldens/components/{component_name}/{state_name}.png
页面：goldens/screens/{screen_name}/{state_name}.png

执行命令：

# 初次：生成 Golden 文件（正确图像）
flutter test --update-goldens test/ui/components/primary_button_golden_test.dart

# 之后：验证图像是否有差异（也可在 CI 中执行）
flutter test test/ui/components/primary_button_golden_test.dart

# 运行全部 Golden Test
flutter test --tags golden

# 更新指定目录的 Golden Test
flutter test --update-goldens test/ui/core/components/

生成的文件结构示例：

test/
├── flutter_test_config.dart
├── helpers/
│   ├── helpers.dart
│   └── golden_test_helper.dart
└── ui/
    └── core/
        └── components/
            ├── primary_button_golden_test.dart
            └── goldens/
                └── components/
                    └── primary_button/
                        ├── enabled.png
                        ├── disabled.png
                        └── all_states.png

生成的测试代码示例（基于资料中的 PrimaryButton 示例）：

testWidgets('有効状態', (tester) async {
  await tester.pumpGoldenWidget(
    PrimaryButton(onPressed: () {}, text: '保存する'),
  );
  await expectLater(
    find.byType(PrimaryButton),
    matchesGoldenFile(
      GoldenFilePath.component('primary_button', 'enabled'),
    ),
  );
});

适用场景

Flutter 项目中希望引入视觉回归测试，防止 UI 被意外改动
需要为按钮、卡片等可复用组件或 Screen/Page 页面添加截图测试
需要在 CI 中验证 UI 是否有差异
需要在重构时保证 UI 质量

限制与注意事项

每次只问一个问题，必须等待用户回答后再继续
初始搭建的 8 个步骤需按顺序执行，禁止跳过
网络图片（如 Image.network、CachedNetworkImage）在 Golden Test 中无法获取，需要用模拟图片或测试用资源图片替换
若使用 Roboto 等不支持日文的字体而界面含日文文本，Golden Test 中可能无法正确显示日文，需要追加日文字体并在 flutter_test_config.dart 中加载
为保证截图一致性，需设置 devicePixelRatio = 1.0
具体模板内容、知识库文件（golden-test-concepts.md、common-issues.md、best-practices.md）的细节暂未提供；收费、价格、平台支持情况暂未提供

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项