test-automation

name	test-automation
description	從測試用例（Google Sheet TC、JIRA ticket、功能描述）生成可執行的自動化測試腳本。支援雙平台原生框架（iOS: Swift Testing + XCUITest、Android: JUnit + Espresso + Mockk）。以 QA 測試工程師角度出發，將手動 TC 轉化為自動化腳本，包含 ROI 評估和 Page Object Model。當使用者提到「自動化測試」、「生成自動化腳本」、「把測試用例自動化」、「UI test 腳本」、「automation script」、「把 TC 轉成程式碼」，或提供 Google Sheet 測試用例要求生成自動化腳本，或討論哪些 TC 值得自動化時使用。

test-automation

⚙️ 執行前先讀 modules/config-loader.md。 若 mode = markdown-only 或 google MCP 不可用，TC 來源改用 Markdown 表格；報表用 modules/markdown-fallback.md 規則輸出。

適用場景與分界

	自動化 unit test 工具	test-automation
出發點	原始碼（.swift/.kt）	測試用例（Google Sheet TC）
視角	開發者 — 驗證程式碼正確性	QA — 驗證功能行為符合預期
範圍	單元測試 only	Unit + UI + Integration
平台	單平台	iOS + Android
Flutter 專案請改用	—	flutter-test-automation

執行流程

Phase 1: 輸入分析

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

1. Google Sheet URL → 讀取 TC sheet，篩選 Column L（自動化）= Y 的項目
2. JIRA 票號（如 {{JIRA_PROJECT_KEY}}-XXXX）→ 抓取需求，搜尋對應的 TC sheet 或直接從需求生成
3. 功能描述 → 分析功能，建議適合自動化的場景
4. Markdown TC 路徑 → 解析表格（同 14 欄結構）
5. 無參數 → 互動式詢問

Phase 2: 自動化 ROI 評估

對每個 TC 評估是否值得自動化：

因素	適合自動化	不適合自動化
執行頻率	每次 Release 都跑	一次性驗證
穩定性	UI/流程穩定	頻繁改版的 UI
複雜度	可程式化的步驟	需要人眼判斷（視覺/UX）
維護成本	Locator 穩定（accessibilityIdentifier）	依賴動態內容/第三方 UI
分類適合度	冒煙測試、功能測試、E2E	無障礙測試、相容性測試

ROI 公式： (手動執行時間 x 預期執行次數) / (開發時間 + 維護時間 x 預期版本數)

• ROI > 3 → 強烈建議自動化
• ROI 1-3 → 視資源決定
• ROI < 1 → 不建議

輸出 ROI 評估表，回寫 Google Sheet Column L 的建議（或 Markdown frontmatter）。

Phase 3: 平台偵測與架構分析

根據當前專案自動偵測平台：

• iOS — 搜尋 *.xcodeproj、Package.swift → 讀取既有測試 pattern
• Android — 搜尋 build.gradle、build.gradle.kts → 讀取既有測試 pattern
• Web — 搜尋 package.json + 偵測 playwright.config.* / cypress.config.* / wdio.conf.* → 對應框架
• 跨平台 — 多邊都生成

若 platforms.{ios,android,web}.repo 已設定，可從遠端 repo 抓取 pattern；否則用本地專案。

分析專案既有測試架構：

• 搜尋現有測試檔案，學習命名慣例、目錄結構、import pattern
• 識別既有 Page Object、Test Helper、Mock/Stub

Phase 4: 腳本生成

依 TC 分類選擇對應的測試類型和 pattern：

TC 分類 → 測試類型對照：

TC 分類	測試類型	iOS 框架	Android 框架	Web 框架
冒煙測試（4 階段）	UI Test	XCUITest	Espresso	Playwright / Cypress E2E
功能測試	Unit + UI	Swift Testing + XCUITest	JUnit + Espresso	Jest/Vitest + Playwright
異常/邊界測試	Unit Test	Swift Testing	JUnit + Mockk	Vitest / Jest
端對端測試	UI Test	XCUITest	Espresso	Playwright (multi-project)
效能測試	Performance Test	XCTest.measure	Benchmark	Lighthouse CI / Playwright trace
並發安全測試	Unit Test (TSAN)	Swift Testing + Actor	JUnit + Coroutine	(N/A — browser single-thread)
API 驗證測試	Unit Test	Swift Testing + Stub	JUnit + Mockk	Playwright request / cy.request
Component Test	(N/A — UIKit/SwiftUI 用 UI Test)	(N/A — Compose 用 UI Test)	Playwright Component / Cypress Component
Visual Regression	XCUITest snapshot (rare)	Espresso 截圖比對 (rare)	Playwright snapshot / Percy / Chromatic
Cross-browser	(N/A)	(N/A)	Playwright multi-project (chromium / webkit / firefox)

腳本生成規則：

iOS pattern 詳見 ios-patterns.md，Android pattern 詳見 android-patterns.md，Web pattern 詳見 web-patterns.md。

核心原則：

• Unit Test：遵循 AAA（Arrange/Act/Assert）或 Given/When/Then
• UI Test：使用 Page Object Model，每個頁面一個 Page Object
• 命名：從 TC 標題（Column E）生成方法名，保留 TC ID 在註釋中
• TC 步驟對應：Column J（測試步驟）→ test body，Column K（預期結果）→ assertions
• 前置條件：Column I → test setup / Page Object navigation

Phase 5: 整合與驗證

1. 放置檔案 — 遵循專案目錄慣例
   • iOS 範例：{ProjectName}Tests/ 或 {ProjectName}UITests/
   • Android 範例：app/src/test/ 或 app/src/androidTest/
   • Web 範例：tests/ / e2e/ / cypress/e2e/ / src/**/__tests__/ / playwright/
2. 編譯檢查
   • iOS：xcodebuild build-for-testing
   • Android：./gradlew compileDebugUnitTest
   • Web：npx tsc --noEmit / eslint / npx playwright test --list
3. 執行測試 — 確認生成的腳本能通過（或標記需要環境配置的項目）
   • Web：npx playwright test --project=chromium / npx cypress run --browser chrome
4. 回寫 Google Sheet — 更新 Column L = Y，Column M 備註加入測試檔案路徑

Phase 6: 輸出完成度報表

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

Tab	內容
總攬	Dashboard — 分類統計（iOS Unit/Android Unit/UI/Manual）+ 完成率 + 視覺化進度條
Unit Test 明細	每個 unit test 目標
iOS 測試檔案明細	iOS 測試檔案清單
Android 測試檔案明細	Android 測試檔案清單
UI Automation 明細	UI 自動化進度 + ROI 評估
額外完成項目	超出原始計劃的額外覆蓋
測試方法清單	所有測試方法逐一列出

上傳到 {{GDRIVE_QA_FOLDER_ID}} 對應的 feature 或 release 資料夾。

Markdown-only 模式下，報表改為 .claude/testing/automation/{feature}/report.md。

品質檢查

• 每個自動化腳本都能對應回原始 TC（TC ID 在註釋中）
• UI Test 使用 Page Object Model，不在 test body 寫 raw locator
• Unit Test 使用 Stub/Mock，不依賴真實網路或資料庫
• 命名清晰：方法名反映測試行為，不是 test1/test2
• 前置條件正確處理（登入狀態、資料準備）
• 斷言對應 TC 的預期結果，不只是 "not nil"

整合其他 Skill

test-master (生成 TC) → test-automation (生成腳本) → 覆蓋率工具
                     ↗
test-review (審查 TC 品質，確認 Column L 標記正確)

• test-master 完成後 → 詢問是否自動化
• test-review 發現自動化標記不合理 → 觸發 ROI 重新評估
• 腳本生成後 → 量測覆蓋率變化（iOS：xccov / Android：jacoco）

設定依賴

設定 Key	用途	缺值時行為
google.qa_tc_folder_id	上傳報表	改寫本地 .md
platforms.{ios,android}.repo	抓遠端 pattern	用本地專案分析
mode = markdown-only	全程模式	全部以 .md 處理（不寫回 Sheet）

範例

詳見 examples.md