Flutter Test Master

flutter-test-master

⚙️ 執行前先讀 modules/config-loader.md。 啟用條件：config.platforms.flutter.enabled = true。 若 mode = markdown-only → 走 modules/markdown-fallback.md。

為 Flutter 應用生成完整測試方案。採用 Flutter 官方推薦的三層測試金字塔，並融合通用測試流程（Google Sheet TC 模板 + JIRA 整合 + 雙平台驗證）。

🎯 適用場景

使用此 skill 的時機

• ✅ 功能由 Flutter/Dart 實作（即使是 Flutter + Native 混合）
• ✅ 需要 Widget Test 或 Integration Test（integration_test）
• ✅ 需要 Golden Test（視覺回歸）
• ✅ Platform Channel / Plugin 測試
• ✅ 純 Dart package 測試

不使用此 skill（改用 test-master）

• ❌ 純 Swift/SwiftUI iOS App
• ❌ 純 Kotlin/Jetpack Compose Android App

混合情境（Native+Flutter）

同時使用兩個 skill：

• flutter-test-master 處理 Flutter 層
• test-master 處理 Native 層（ObjC/Swift/Kotlin）

📦 前置知識：Flutter 測試三層

🎯 推薦技術棧

❌ 明確不採用：

• Appium（Flutter Canvas 渲染，widget tree 不可見）
• flutter_driver（Flutter 官方已 deprecated）
• Appium Flutter Driver / Integration Driver（社群維護、不穩定）

關鍵原則：

• ⭐ Fake over Mock：優先建 FakeUserRepository 而非 mocking library
• ⭐ ViewModel 不依賴 Flutter 框架：UI 邏輯用純 Dart 測試
• ⭐ View 注入 Fake：Widget test 時傳入 FakeViewModel + FakeRepository
• ⭐ E2E 先挑 integration_test，遇原生才升級 Patrol

🔄 執行流程

Phase 1: 需求分析

1. 讀取需求
   • JIRA 票號（{{JIRA_PROJECT_KEY}}-XXXX）→ Atlassian MCP 撈取
   • 否則請使用者描述功能 + 架構（Provider / Riverpod / BLoC / GetX）
2. 架構偵測
   • 搜尋 pubspec.yaml 確認 state management 套件
   • 搜尋 ViewModel/Repository/Service pattern（Glob: **/view_models/**, **/repositories/**）
   • 搜尋 platform channel 使用（Grep: MethodChannel, EventChannel）
3. 風險評估
   • 金流/認證/FIDO2 → P0 高風險
   • Platform Channel → Plugin 跨層風險
   • 動畫/手勢 → Widget Test 覆蓋必要
   • Isolate/並發 → 並發測試必要

Phase 2: 測試策略設計

生成 flutter-test-strategy.md（模板見 templates.md）

Flutter 特有決策點：

• Golden Test 是否啟用？（UI 穩定的畫面才啟用）
• Integration Test 執行平台？（Mobile / Web / Desktop / Firebase Test Lab）
• Mock 工具選擇？（mocktail 優先 / mockito 次選 / 純手寫 Fake 最推薦）

Phase 3: 測試用例生成

生成 黑箱 + 白箱 兩份 Google Sheet（從模板 {{GSHEET_TC_TEMPLATE_ID}} 複製，若空則 createSpreadsheet 從零建）。

Flutter 測試用例分佈建議：

• Unit / 邏輯驗證：30%
• Widget / UI 互動：25%
• Integration / E2E：15%
• 邊界條件：15%
• 錯誤處理：10%
• Golden / 視覺回歸：5%（僅穩定 UI）

依功能類型自動調整：

a11y（輔助功能）必檢項目 — 每個 UI 功能都要加：

• 字級縮放（Flutter 核心）：
  • MediaQuery.textScaler 測試（最大級距）
  • iOS Dynamic Type / Android 字型大小同步驗證
  • 裝飾性數字不應跟隨放大（用 MediaQuery(data: ...copyWith(textScaler: TextScaler.noScaling)) 包裝）
• Semantics widget：
  • 互動元件有 Semantics(label: ...)
  • 裝飾性元件 ExcludeSemantics
• VoiceOver / TalkBack：讀取順序、label 正確
• 觸控目標：Flutter kMinInteractiveDimension (48dp)
• 對比度 / Reduce Motion：同原生規則
• 詳細檢查模板見 templates.md「a11y-checklist 模板（Flutter 版）」

跨平台 a11y 配對原則（若 workflow.auto_a11y_pairing = true）：Flutter 一份程式碼跑雙平台，但系統字級的觸發路徑不同（iOS Dynamic Type vs Android fontScale），測試時兩邊都要驗。a11y bug 建議開一對 ticket 並用 Relates 連結。

Google Sheet 格式（A-N 欄）：

Phase 4: 覆蓋缺口分析

搜尋現有 Flutter 測試：

• test/**/*_test.dart → Unit + Widget
• integration_test/**/*_test.dart → E2E
• test/golden/**/*.png → Golden baselines

比對新增用例 vs 現有測試，識別缺口。模板見 templates.md「coverage-gaps.md」。

Phase 5: 自動化評估 + 測試程式碼骨架

與 test-automation skill 不同，本 phase 直接產出 Dart 測試程式碼骨架（供開發者參考）：

test/
├── unit/
│   ├── view_models/
│   │   └── home_view_model_test.dart        ← ViewModel unit test
│   └── repositories/
│       └── user_repository_test.dart         ← Repository unit test (mock HTTP)
├── widget/
│   └── home_screen_test.dart                 ← Widget test (inject Fake VM)
├── golden/
│   └── home_screen_golden_test.dart          ← Golden test
└── fakes/
    ├── fake_user_repository.dart             ← Fake 實作（優先於 Mock）
    └── fake_booking_repository.dart

integration_test/
└── app_test.dart                             ← E2E 測試

模板見 templates.md「flutter-test-code 模板」。

Phase 6: CI / Firebase Test Lab 整合指引

根據專案 CI 系統（GitHub Actions / Bitrise / Codemagic）產出執行指令：

Phase 7: 探索性測試指引（Flutter 特化）

模板見 templates.md「flutter-exploratory-guide.md」，聚焦：

• 熱重載殘留狀態（hot reload 後行為）
• Isolate 通訊（背景運算中斷）
• Platform Channel 異常（native 崩潰時 Dart 端表現）
• 多平台像素差異（iOS vs Android 相同 widget 的像素差）

Phase 8: Google Drive 上傳

僅在 mode != markdown-only 且 google.qa_tc_folder_id 設定時執行。

1. 在 QA-TC 資料夾（{{GDRIVE_QA_FOLDER_ID}}）下建立 [Flutter] [功能名] 子資料夾
2. 上傳黑箱/白箱 Google Sheet
3. 詢問是否上傳其他文件（test-strategy / coverage-gaps / 程式碼骨架壓縮檔）

📁 輸出檔案

.claude/testing/features/[feature-name]-flutter/
├── flutter-test-strategy.md
├── test-cases-{feature}-blackbox.xlsx    (Google Sheet 或 .md)
├── test-cases-{feature}-whitebox.xlsx    (Google Sheet 或 .md)
├── coverage-gaps.md
├── automation-plan.md
├── exploratory-guide.md
└── code-skeleton/
    ├── test/
    │   ├── unit/
    │   ├── widget/
    │   ├── golden/
    │   └── fakes/
    └── integration_test/

🎛 互動模式

• 基礎模式（預設）：生成所有文件
• 快速模式 --mode=quick：只生成測試用例 Sheet（黑箱 + 白箱）
• 深度模式 --mode=deep：完整文件 + 可執行的 Dart 測試程式碼（含 Fake 實作）

✅ 品質檢查

生成後自動驗證：

• 三層金字塔比例合理（Unit 70% / Widget 20% / Integration 10%）
• Fake over Mock 原則已套用（ViewModel/View test 用 Fake）
• 所有 Repository 都有 Mock HTTP/DB 的 unit test
• 所有 ViewModel 都有純 Dart unit test（不依賴 flutter_test）
• 所有 View 都有 Widget test
• 至少 1 個 Integration test 涵蓋核心流程
• Platform Channel 有 Dart + Native 雙邊測試
• CI 執行指令針對目標平台正確
• 跨 iOS/Android 像素差異已評估（Golden test 差異容忍值）

設定依賴

🤝 與其他 Skill 的關係

範例

詳見 examples.md