前言
我們目前的團隊在行動應用程式正式發布前，會以人工測試進行確認。
測試案例的管理一直都是使用 Google 試算表（以下簡稱試算表），但運作已經接近失控。
因此，我們改成由程式碼庫來管理案例，僅在試算表中執行測試，問題就解決了。本文將介紹我們具體做了哪些事。
試算表管理的痛點
過去是以 PR 為單位，由實作者將測試案例新增到試算表中。由於新增的人和時間點都不固定，試算表逐漸變得雜亂，並產生以下問題：
- 同一個確認項目，因為不同寫法而出現多個案例
- 舊案例與新案例之間的預期結果互相矛盾
- 無法追蹤哪個 PR 新增了哪個案例
在開發中的測試並沒有太大問題，但一旦要在發布前做整體測試，畫面就很難閱讀，也無法判斷什麼才是正確答案。
另外，在 PR Review 時也採取「在試算表的第幾行新增了案例」並附上連結、將該列反白的做法。因此當同時有兩個以上 PR 開啟時，很難分辨哪個變更屬於哪個 PR，導致 Review 變得不容易。
將案例管理搬到程式碼庫
我認為問題的根本，在於「任何人都能自由修改的地方」卻成了正本（可信的唯一資訊來源）。
因此，我們決定將角色分開，改成「案例管理放在程式碼、執行放在試算表」。
| 放置位置 | 角色 |
|---|---|
| 儲存庫內的 YAML | 案例定義，在 PR 中審查，並由 CI 驗證 |
| 試算表 | 測試執行與結果記錄，由測試人員填寫 ○× 與備註 |
試算表會匯入由已合併的 YAML 產生出的 xlsx，因此試算表中永遠都是最新的測試案例。
整體流程如下：
1. 新增／修改案例
2. 驗證
3. PR Review
4. 合併
5. 產生 xlsx
6. 匯入試算表
7. 執行測試測試案例以 YAML 管理
cases:
- id: LIB-023
feature: 我的圖書館
viewpoint: 畫面操作
precondition: 已登入
input: 在圖書館畫面向下滑動
expected: 顯示指示器並更新為最新資訊回顧試算表時代案例容易失控的經驗後，我們也決定為寫法訂定規則。例如：
id一旦編號後就不可更改。 已刪除的編號也不重複使用input只寫一個操作。 像「A 之後再 B，最後確認 C」要拆開expected要寫可觀察的結果。 不寫像「正常運作」這種無法驗證的內容
除了這些最低限度的規則外，我們也把表格結構、觀點、目標裝置整理到 config.yaml 中。因此即使新增裝置，判定欄與彙總也會自動跟著調整。
以 CI 擋下重複與矛盾的機制
驗證分成錯誤與警告兩個階段。只要有 1 個錯誤，CI 就會失敗；警告則會顯示為可考慮整併的候選項目。
| 類型 | 內容 |
|---|---|
| 錯誤 | 未知的 key（typo）、必填項目遺漏、ID 格式錯誤或重複、未定義的觀點 |
| 錯誤 | 前提條件／操作／預期結果實質相同的案例 |
| 錯誤 | 前提條件與操作互相矛盾的案例 |
| 警告 | 可能是在確認同一件事的相似案例 |
在判定「實質相同」時，會先將全形半形、空白、括號等書寫差異正規化後再比較。功能名稱不納入比較，因此即使是以不同功能名稱登錄的重複案例也能找出來。
矛盾的偵測，主要針對像「前提是裝置已橫向」但操作卻寫成「將裝置轉為橫向」這類，在前提中已成立的狀態又在操作中重新建立的案例。哪些狀態與操作的組合算是矛盾，則是以 config.yaml 中的規則定義。
相似案例則是根據預期結果與操作的字串相似度來判定。若預期結果相同，就很可能是在確認同一件事，因此以預期結果為主、操作為輔。不過，前提條件不同的配對會被視為「刻意分開條件的案例」，因此排除在外。若是刻意做得相似的案例，只要在設定檔中附上理由登錄，就可以抑制警告。
透過這種方式，把人眼容易漏掉的部分交給機器檢查，讓人工 Review 能更專注在案例內容本身。
用來製作測試案例的 Agent Skill
為了讓案例建立本身也更輕鬆，我們準備了一個能從程式碼差異自動產生案例的 Agent Skill。
實際製作的 Skill 流程如下：
- 從實作差異中整理出使用者可見的行為變化
- 讀取所有既有案例，並以相關關鍵字進行橫向搜尋
- 對照既有案例，判斷「不新增／更新既有案例／刪除／新增」
- 編輯 YAML，讓驗證中的錯誤與警告都變成 0 件
- 回報「新增了哪些」、「哪些沒有新增（依據的既有 ID）」、「變更／刪除哪些」、「有哪些需要人類判斷的地方」
重點不只是單純從差異產生新案例，而是進一步判斷是否真的有必要新增，並與既有案例比較。
不過 AI 產出的仍然只是附有依據的草稿，最後是否有過多或不足，仍由人來判斷。
xlsx 產生與試算表匯入
我們會從通過審查的測試案例產生 xlsx，並以整份置換的方式更新既有試算表。
由於是整份置換，舊案例或手動修正內容不會殘留，能一直維持乾淨狀態。
不過，以下幾點需要注意：
- 置換時執行結果也會被清除，所以在測試執行中不要匯入
- 儲存格保護會在每次匯入時消失，因此要用 Apps Script 重新套用定義欄位的保護。保護設定為編輯時顯示警告，讓人不小心碰到時能察覺
實際導入後
首先最明顯的是，因為測試案例一直維持整潔狀態，所以在做整體測試時不再會猶豫。原本有大量重複的 380 筆案例減少到 330 筆，寫法也統一了，測試執行變得更容易。
附帶的效果是，透過這個 Skill，製作測試案例的負擔也大幅降低了。
另外，測試案例會直接出現在 PR Review 的差異中，因此 reviewer 與 reviewee 的負擔都變小了，Review 也更容易進行。
結語
試算表上的案例管理之所以快要失控，原因就在於「可信的唯一資訊來源」變成了任何人都能自由修改的地方。
把定義與執行分開、將驗證機械化、以及請 AI 先產出草稿，這幾件事都讓我覺得非常值得。
雖然都不是什麼特別的機制，但組合起來之後，終於能讓測試案例維持在乾淨的狀態。
如果這篇文章能幫助到同樣正在煩惱手動測試案例的人，我會很開心。
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
