場景測試與報告

單個請求只能證明一次呼叫。場景測試證明的是一個工作流：一個有序的請求序列，其中一個回應中的值餵給後續請求，並在每一步檢查斷言。場景捕捉了原本只存在於開發者腦中的端到端流程。

場景包含什麼

• 有序步驟，每一步引用規範中的一個操作；
• 步驟之間的資料傳遞——例如，從已建立資源取出 id 並在下一個請求中使用；
• 對狀態碼、回應頭或回應欄位的斷言；
• 執行前讀者必須提供的值。

順序和斷言是一等公民：執行期間從不會被悄悄丟棄。

執行場景

場景在主程序中透過來自 @powerduck/openapi-cli 的 runScenario 引擎執行：

• scenario:run 用場景、規範和請求配置啟動一次執行；
• 步驟執行時進度透過 scenario:event 串流回傳；
• scenario:cancel 停止正在執行的任務。

你可以觀察每一步，看到流程在哪裡失敗，並取消長時間的執行。

助手如何建構場景

助手不會在規範內部憑空捏造測試定義。場景是獨立的宿主工作流，從不會儲存在 OpenAPI 文件中——不存在 x-scenarios 鍵或內嵌步驟。

當你要求既設計介面又測試它們時，工作會被排序：

1. 助手先只提出介面補丁；
2. 你套用後，它回傳一張動作卡片來執行流程：
   • test.single 用於單個介面；
   • scenario.plan 讓宿主發現端到端流程；
   • scenario.run 準備並執行一個有序流程。

一張 scenario.run 卡片按執行順序（兩到八個）列出操作並陳述目標，包括哪個回應欄位、回應頭或狀態餵給每個後續請求。每個引用都從當前規範逐字複製。

報告

執行後，你可以匯出一份自包含 HTML 報告。它是一份總結性文件，而不是原始 CLI 輸出：它以可讀的版面呈現流程、每步結果、斷言和最終結果。

匯出時選擇一種語言。內建十種語言：

1. English
2. 简体中文（簡體中文）
3. 繁體中文（繁體中文）
4. 日本語（日語）
5. 한국어（韓語）
6. Français（法語）
7. Deutsch（德語）
8. Español（西班牙語）
9. Português — Brasil（葡萄牙語-巴西）
10. العربية（阿拉伯語）

其他／自訂選項可輸入其他語言，但沒有內建翻譯時，報告介面文字會回退為英文；輸入語言不會自動翻譯報告。

分享前請檢查匯出的報告：

• 已識別的憑證欄位會自動遮罩，但任意內文、URL 與自訂欄位仍可能包含敏感資料，請在分享前檢查並移除；
• 大型內文以摺疊方式顯示，方便閱讀。摺疊內容不會從匯出的 HTML 中刪除資料。

HTML 是獨立的，因此可以附到工單或隨版本歸檔。

何時使用場景

• 驗證多步驟業務流程（建立、讀取、更新、刪除）；
• 確認認證和權杖傳遞在跨呼叫時正常工作；
• 為發布或交接產出 API 行為的證據；
• 在合約變更後對流程做回歸檢查。

相關：請求工作區、用助手進行設計、Mock 伺服器。