CloudyWing/desktop-smoke

Desktop Smoke Verification

此 Skill 用於完成 WinForm 或 WPF 桌面應用變更後的低成本煙霧驗證。它不是完整 E2E 測試框架，不負責新增可重跑的測試案例；若使用者要求建立正式測試，改依專案既有測試架構處理。

啟動條件

符合任一條件時套用：

• 使用者明確要求「測這個 WinForm / WPF」、「測一下桌面程式」、「檢查視窗程式」。
• 本次修改影響 WinForm / WPF 的視窗、控制項、互動或繪製邏輯。
• 由 integration-verify 判定為桌面應用專案後路由進入。

以下情境不強制套用：

• 只修改與 UI 無關的內部邏輯、文件或設定。
• 專案已有明確的 CI 桌面 UI 測試，且本輪只需執行該測試。

驗證流程

1. 確認驗證目標：本次修改涉及的視窗、控制項或操作流程。若無法判斷，回報需要使用者指明。
2. 建置：執行 dotnet build，確認編譯通過。編譯失敗先修正再繼續。
3. 判斷可用驗證層級：依下節「驗證層級」由高至低判斷，採用最高可用層級。
4. 依層級執行驗證。

驗證層級

AI 看不到桌面視窗，實際能做到的程度取決於環境提供的工具。依序判斷，採用最高可用層級。

層級 A：環境提供桌面 UI 操作工具

當前環境若提供桌面 UI 操作工具（如基於 FlaUI 的 MCP server 所暴露的工具），優先使用，比照 browser-smoke 操作瀏覽器的方式：

• 讀取 UI Tree，定位本次修改相關的控制項。
• 走完整段操作流程（如開啟視窗 → 輸入 → 觸發動作 → 確認結果），而非只點單一控制項。
• 涵蓋正常、邊界與錯誤情境，確認各情境的實際回饋與預期一致。
• 讀 UI Tree 比對操作後實際顯示的值，確認狀態變更正確，無未預期的錯誤對話框、版面無明顯異常。
• 操作會寫入資料時，查詢資料來源確認寫入正確，並重開視窗或重啟程式確認資料正確載回。

此為一次性即時驗證，不產生可重跑的測試案例。

層級 B：專案已有 UI 自動化測試

無桌面操作工具，但專案已整合 FlaUI、WinAppDriver 或 Appium：

• 執行專案既有的 UI smoke / e2e 測試。
• 必要時依專案既有測試架構，協助撰寫涵蓋本次修改的測試。

層級 C：無 UI 自動化能力（fallback）

• 啟動存活檢查：以 dotnet run 在背景啟動程式（GUI 程式不會自行返回，須以背景或非同步方式啟動以免阻塞工具呼叫），等待數秒後確認 process 仍存活、未設定非零 exit code、stdout / stderr 無未處理例外，檢查後主動結束該 process。這只能證明「啟動後沒有立即崩潰」，不能證明畫面或互動正確。
• 視覺呈現、互動行為、版面正確性 AI 無法驗證。必須誠實回報「桌面 UI 互動需手動驗證」，並列出本次修改相關的手動檢查清單（操作哪個控制項、開哪個視窗、預期看到的結果）交給使用者，不得宣稱已驗證實際未驗證的項目。

提高自動化程度的方向：桌面程式的邏輯與 UI 分離得越好（WPF 採 MVVM、商業邏輯抽離 code-behind），可被單元測試與層級 A / B 涵蓋的比例越高。若要長期提升，可評估在專案導入 FlaUI（.NET 原生、較輕量）或 WinAppDriver + Appium。

共用規範

以 integration-verify 為單一來源的共用規範（行為基準、結果驗證原則、主動詢問規範、步驟二判定執行環境、步驟六寫入回查 gate、資料異動安全規範、修正迴圈）：由 integration-verify 路由進入時已套用；獨立執行本 skill 時，先讀取上述各節並套用。

修正迴圈

修正迴圈規範以 integration-verify §修正迴圈 為單一來源，由 integration-verify 路由進入時已套用；獨立執行本 skill 時，先讀取並套用。本 skill 重跑驗證時的標的為「同一組桌面驗證」。

停止時回報（本 skill 領域專屬延伸）：

• 失敗的視窗或操作。
• 觀察到的錯誤對話框、例外或畫面現象。
• 已修正的項目。
• 尚未解決的原因或需要使用者補充的條件。

收尾清理

驗證結束後（成功或中止皆適用）：

• 關閉本流程以 dotnet run 自行啟動的桌面程式。
• 層級 A 操作期間開啟的視窗，驗證後關閉。
• 刪除驗證過程產生的臨時檔案。

驗證報告格式

完成後用精簡格式回報：

桌面應用煙霧驗證：
- 程式 / 視窗：
- 驗證層級：A / B / C
- 檢查項目與結果：
- 修正迴圈：
- 未解決項目：

若沒有問題，未解決項目 可省略。採用層級 C 時，必須附上手動檢查清單。若未能執行驗證，必須說明缺少的工具、服務或資料條件。

有未解項目或阻塞條件時的檔案輸出：

• 本流程由 integration-verify 呼叫時，未解項目交回由其統一輸出，不自行寫檔。
• 本流程為獨立執行時，將未解項目、阻塞條件與手動檢查清單寫入 <work-root>/.local/ai-sessions/verify-pending.md（覆寫模式）。
• 全部通過時不寫檔；若該檔先前已存在，刪除它。