flutter-test-automation

name	flutter-test-automation
description	專為 Flutter 應用量身打造的自動化測試腳本生成 Skill。從 Google Sheet TC、JIRA 票號或功能描述生成可執行的 Dart 測試腳本，涵蓋 Unit Test（flutter_test）、Widget Test（WidgetTester）、Integration Test（integration_test）、Golden Test、Platform Channel Test。採用 Fake-over-Mock 原則、Robot Pattern / Page Object Model、Mocktail/Mockito 策略，並整合 Firebase Test Lab、`flutter test --coverage` 覆蓋率工具。當使用者提到「Flutter 自動化」、「寫 Dart 測試」、「把 Flutter TC 轉成程式碼」、「widget test 自動化」、「integration_test 腳本」、「Flutter UI test」、「patrol 測試」、「Golden test 自動化」，或針對 Flutter/Dart 專案要求生成自動化腳本時使用。與 test-automation 並存：test-automation 適用原生 iOS (XCUITest) / Android (Espresso)，flutter-test-automation 適用 Flutter/Dart 專案或 Flutter+Native 混合。
disable-model-invocation	false
allowed-tools	Read, Grep, Glob, Write, Edit, Bash, mcp__google__readSpreadsheet, mcp__google__getSpreadsheetInfo, mcp__google__writeSpreadsheet, mcp__atlassian__getJiraIssue
argument-hint	[Google Sheet URL、JIRA 票號、功能描述、或 dart 測試檔案路徑]

flutter-test-automation

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

從手動測試用例生成可執行 Dart 自動化腳本。輸出遵循 Flutter 官方推薦架構：Unit → Widget → Integration 三層金字塔。

---

🎯 適用場景

• ✅ Flutter/Dart 專案（純 Flutter app 或 Flutter package）
• ✅ Flutter + Native 混合專案的 Flutter 層
• ✅ 需要 Widget Test / Integration Test / Golden Test 自動化
• ✅ Platform Channel 測試腳本

🚫 不使用本 skill（改用 test-automation）

• 純 Swift iOS（XCUITest）
• 純 Kotlin Android（Espresso）

🧭 Skill 分工對照

	test-automation	flutter-test-automation	flutter-test-master
出發點	TC (iOS/Android)	TC (Flutter)	需求 → TC
視角	QA → 原生自動化	QA → Dart 自動化	QA → TC 規劃
輸出	Swift/Kotlin 測試檔	Dart 測試檔	Google Sheet TC
框架	XCUITest / Espresso	flutter_test / integration_test	N/A

---

🔄 執行流程

Phase 1: 輸入分析

偵測輸入類型並收集資訊：

1. Google Sheet URL → 讀取 TC sheet，篩選 Column L（自動化）= Y 的項目
2. JIRA 票號（{{JIRA_PROJECT_KEY}}-XXXX）→ 抓取需求，搜尋對應 TC sheet 或從需求生成
3. 功能描述 → 分析功能，建議適合自動化的場景
4. Dart 檔案路徑 → 補強既有測試覆蓋
5. Markdown TC 路徑 → 解析表格
6. 無參數 → 互動式詢問

Phase 2: 自動化 ROI 評估（Flutter 特化）

因素	適合自動化	不適合
執行頻率	每次 commit / PR	一次性驗證
穩定性	UI/流程穩定（Key 固定）	頻繁改版的 UI
測試層級	Unit / Widget / Integration 都適合	需要人眼判斷視覺/UX
Locator 策略	用 ValueKey 或 Key	依賴動態 text / 位置
跨平台需求	Dart 自動化一次跑 iOS+Android	Golden 需雙 baseline
分類適合度	功能測試、邏輯、E2E	無障礙、真實裝置 UX

Flutter ROI 加權：

• Widget Test ROI 通常高於 XCUITest/Espresso（執行更快、跨平台）
• Golden Test ROI 依 UI 穩定性決定
• Integration Test 建議限制在 關鍵路徑（登入、支付、核心功能）

ROI > 3 → 強烈建議；1-3 → 視資源；< 1 → 不建議。

Phase 3: 專案架構偵測

自動偵測 Flutter 專案：

• pubspec.yaml → 確認 Flutter 版本、dependencies
• State management: provider / riverpod / bloc / get / mobx
• Mock 套件: mocktail（優先） / mockito / 純 Fake
• 測試套件: 已安裝 integration_test / patrol / alchemist（golden）
• 既有測試目錄：
  • test/ → Unit + Widget
  • test/golden/ → Golden baselines
  • integration_test/ → E2E

搜尋既有 pattern：

• **/view_models/*.dart → 找 ViewModel
• **/repositories/*.dart → 找 Repository
• test/fakes/*.dart → 找現有 Fake 實作
• test_driver/ → 舊版 driver 檔

Phase 4: 腳本生成策略

🔧 標準技術棧

層級	工具	備註
Unit Test	flutter_test + Fake	純 Dart，不依賴 Flutter binding
Widget Test	flutter_test + WidgetTester	Fake ViewModel 注入
Golden Test	flutter_test + alchemist（可選）	雙平台 baseline
Integration Test (基礎)	integration_test	官方套件、純 Dart E2E
Integration Test (進階)	Patrol	原生對話框、權限、通知、跨 app
Platform Channel	flutter_test + XCTest/JUnit	Dart + Native 雙邊

❌ 不採用：Appium（Flutter widget tree 不可見，相容性差） ❌ 不採用：flutter_driver（官方已 deprecated）

---

TC 分類 → Flutter 測試類型對照：

TC 分類	測試類型	主要工具	檔案位置
冒煙-Feature Done	Integration Test	integration_test	integration_test/smoke/
功能測試	Unit + Widget	flutter_test	test/unit/, test/widget/
異常/邊界測試	Unit Test	flutter_test + Fake	test/unit/
Widget Test	Widget Test	flutter_test (WidgetTester)	test/widget/
Integration Test（純 Flutter）	Integration Test	integration_test	integration_test/
Integration Test（含原生對話/權限）	Integration Test	Patrol	integration_test/patrol/
Platform Channel	Unit Test + Native	flutter_test + XCTest/JUnit	test/unit/services/, native tests
Golden Test	Widget Test	flutter_test + matchesGoldenFile	test/golden/
API 驗證測試	Unit Test	flutter_test + Mock HTTP	test/unit/repositories/

---

🎯 integration_test vs Patrol 決策樹：

需要點擊「允許位置權限」系統對話框？ → Patrol
需要處理「推播通知授權」？           → Patrol
需要跨 App 流程（外部瀏覽器回跳）？  → Patrol
需要控制 WiFi / 網路 / 飛航模式？   → Patrol
需要處理 biometric（指紋/Face ID）？ → Patrol
以上都沒有，純 Flutter 畫面內流程？ → integration_test（較輕量）

核心原則（詳見 flutter-patterns.md）：

• ⭐ Fake over Mock：ViewModel/View test 優先用 Fake 實作
• ⭐ Robot Pattern / Page Object：Widget/Integration test 封裝互動邏輯
• ⭐ AAA（Arrange/Act/Assert） 或 Given/When/Then 結構
• ⭐ ValueKey 作為 locator：find.byKey(const ValueKey('login_button'))
• ⭐ TC ID 註釋：每個測試方法頂部加 // TC: BB-FLT-001
• ⭐ pumpAndSettle 管理：動畫/異步操作後必 settle

Phase 5: 整合與驗證

1. 放置檔案 — 遵循專案慣例（test/ 或 integration_test/）
2. 編譯檢查 — dart analyze / flutter analyze
3. 執行測試：
   • Unit/Widget: flutter test [path]
   • Integration: flutter test integration_test/[file] (需裝置/emulator)
   • Golden: flutter test --update-goldens（首次建立 baseline）
4. 回寫 Google Sheet：更新 Column L = Y、Column M 加測試檔案路徑

Phase 6: CI 整合產出

根據偵測的 CI 系統產出範本：

GitHub Actions（範例）：

- name: Setup Flutter
  uses: subosito/flutter-action@v2
  with:
    flutter-version: '3.24.x'

- name: Unit + Widget Tests
  run: flutter test --coverage

- name: Integration Tests (Android)
  run: |
    flutter build apk --debug
    ./gradlew app:assembleAndroidTest
    # 上傳至 Firebase Test Lab

- name: Coverage Report
  uses: codecov/codecov-action@v4
  with:
    file: coverage/lcov.info

Firebase Test Lab：

gcloud firebase test android run \
  --type instrumentation \
  --app build/app/outputs/apk/debug/app-debug.apk \
  --test build/app/outputs/apk/androidTest/debug/app-debug-androidTest.apk \
  --device model=redfin,version=30,locale=en,orientation=portrait

Phase 7: 輸出完成度報表

生成 Google Sheet「{Feature} Flutter 自動化完成度報表」，包含 7 個 tab。格式詳見 report-template.md。

Tab	內容
總攬	Dashboard — 三層統計（Unit/Widget/Integration）+ 完成率 + 覆蓋率
Unit Test 明細	目標：ViewModel/Repository/Service/Utility
Widget Test 明細	Screen/Widget + Fake 注入狀況
Integration Test 明細	E2E 流程 + 平台執行狀態（iOS/Android/Web）
Golden Test 明細	Baseline 清單 + 雙平台狀態
Platform Channel 明細	Dart + Native（iOS XCTest / Android JUnit）配對狀態
測試方法清單	所有 Dart 測試方法逐一列出

上傳到 {{GDRIVE_QA_FOLDER_ID}} 對應資料夾。

Markdown-only 模式下，改寫到 .claude/testing/automation/{feature}-flutter/report.md。

---

✅ 品質檢查

生成後自動驗證：

• 每個測試對應回原始 TC（TC ID 在註釋中）
• Widget/Integration Test 使用 Robot 或 Page Object Pattern
• Unit Test 使用 Fake/Mock，不依賴真實網路或 DB
• 命名清晰：方法名反映行為，不是 test1/test2
• 使用 ValueKey 做 locator，不用動態 text
• 前置條件透過 setUp() 或 Robot helper 處理
• 異步操作後有 pumpAndSettle() 或 pump(Duration)
• 斷言對應 TC 預期結果，不只 isNotNull
• 遵循 Fake-over-Mock 原則（ViewModel/View test）
• Golden test 有雙平台 baseline（iOS + Android）

---

🔗 整合其他 Skill

flutter-test-master (規劃 TC)
    ↓
flutter-test-automation (本 skill：生成 Dart 腳本)
    ↓
test-review (審查測試品質)
    ↓
smoke-test-analyzer (選出每日 smoke 測試集)

• flutter-test-master 產出 TC → 本 skill 轉成程式碼
• test-review 找出 Column L 標記不合理 → 觸發 ROI 重新評估
• 腳本生成後 → smoke-test-analyzer 選出每日 CI 跑的集合

---

設定依賴

設定 Key	用途	缺值時行為
platforms.flutter.enabled	啟用此 skill	提示使用者改用 test-automation
google.qa_tc_folder_id	上傳目標	改寫本地 .md
mode = markdown-only	全程模式	不呼叫 google MCP

❌ 不採用的工具（明確排除）

工具	原因
Appium	Flutter Canvas 渲染 → UIAutomator/XCUITest 看不到 widget
flutter_driver	Flutter 官方已 deprecated，改推 integration_test
Appium Flutter Driver / Integration Driver	社群維護、Flutter 版本升級常壞
Maestro（主力）	作為次要補充可以，但對 Flutter 的理解不及 Patrol

---

🤝 與其他 Skill 的關係

Skill	分工
test-automation	原生 iOS (XCUITest) / Android (Espresso)
flutter-test-automation	Flutter/Dart (本 skill)
flutter-test-master	Flutter TC 規劃（產出 Google Sheet）
test-master	原生 TC 規劃
test-review	審查 TC 品質（跨框架）
smoke-test-analyzer	選 Daily Smoke 測試集（跨框架）

範例

詳見 examples.md