Flutter Test Automation

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 分工對照

🔄 執行流程

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 特化）

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: 腳本生成策略

🔧 標準技術棧

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

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

🎯 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。

上傳到 {{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 跑的集合

設定依賴

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

🤝 與其他 Skill 的關係

範例

詳見 examples.md