Test Report Docx

---
name: test-report-docx
description: 把「已做完的測試結果」產成一份給 PM／客戶簽核轉發的測試報告 DOCX 檔。當使用者說「測試報告」、「修復測試報告」、「驗收報告」、「給 PM 的報告」、「report 要 Word/DOCX 檔」、「把測試結果寫成報告」、「產一份測試證明文件」時觸發。**前提是測試已做完、證據（截圖／紀錄）在手**——測試還沒跑、要設計或執行測試的，用 qa 系 skill；本 skill 只把既有測試結果文件化，不憑描述寫報告。不套固定目錄：先做組裝決定（要證明幾件事、對方拿去做什麼、修復還是新功能、有沒有動正式環境、對方之前看過什麼），再從段落構件庫按需取用。含九條鐵則（禁字清單／不寫 meta 句／讀者不懂技術／實機截圖為主證據／缺陷走交付揭露不進報告／只寫最終狀態不寫我方作業時序／不寫我方修了什麼 bug／宣稱須逐項對得上實際檢核／易讀性鐵則適用）。**產出的是檔案不是訊息**——報告定稿後若還要寫一段交付訊息把它交出去，改用 deliver-report skill。
---

# 測試報告 DOCX 輸出模式

> 交付物本身是「一份給 PM／客戶的測試報告檔案（DOCX）」時走這裡。
> **哲學與 deliver-report skill 一致：不套固定格式，先做決定、再從構件庫按需組裝，形狀自己長出來。**
> 定位：修復／功能上線前，把「改了什麼、怎麼證明它對、上線要注意什麼」寫成 PM 能直接轉發簽核的文件。
> **前提：測試已做完、證據在手**——本模式只文件化既有結果；證據還沒產生就先去做測試，不要憑描述寫報告。
> **證據以實際畫面為主（2026-08-19 使用者裁定）**：功能有畫面入口時，一切文件產出的證據必須經由**實際畫面操作**產生，不得以 API 直打等方式繞過畫面取證——繞過畫面產生的證據可能測到使用者根本走不到的路徑（實例：證書提醒信曾以 API 對「未填日期」料號直寄取證，但畫面按鈕的顯示條件根本擋掉這種料號，該證據呈現了一條 UI 上不存在的流程）。唯一例外＝本來就無畫面的機制（排程寄信、webhook 等背景作業）。**證據合法性逐張判、不按產生批次連坐**：同批取得的證據中，「呈現了 UI 不存在流程」的才排除；內容與觸發路徑無關的成品（如信件實寄畫面——範本相同）仍可用，圖說如實註記來源即可（2026-08-19 實例：誤將整批信箱截圖連坐撤除，使用者糾正後逐張回收合法者）。

## 鐵則（不分形狀全適用）

1. **禁字清單（出現即重寫）**：自動化測試、固化、迴歸測試清單、codify、紅藍對抗、紅隊、QA、code review、reviewer、pipeline、agent、AI、skill、plugin、session、commit（雜湊）、e2e／pytest 等 runner 名。
   替代寫法：「自動化測試」→「測試案例」或直接刪；「已固化為可重複執行的自動化測試」→ 整句刪。
2. **meta 句不寫**：「以上情境均已納入測試案例清單，後續版本可重複執行驗證」這類「我們流程做得很好」的自述句一律刪——報告只講交付物與證據，不講我方怎麼管理測試。
3. **預設讀者是 PM／客戶**（不懂技術）：正文全白話；技術詞只出現在「必須精確」的地方（欄位名、參數名）且緊跟白話解釋。
4. **實機截圖是主證據，流程圖不放**（使用者明確裁決過：「重點不是流程圖，我要實際系統的操作截圖」）。
5. **誠實邊界與缺陷不進報告本體，改走交付揭露**（2026-08-18 使用者裁定，取代舊制「誠實邊界必寫進報告」）：報告只呈現已驗證通過的最終狀態。測試發現的缺陷應**修復並重驗後再交付**，不寫「已知問題」章；未能驗證的情境、驗證層級缺口（如以模擬服務代真實端）、環境限制、後續建議，一律在交付時**於報告之外對使用者逐條揭露**（見「交付前的揭露」），由使用者決定要不要處理、或點名破例寫進報告。**省略可以，造假不行**——不得因此把未驗證的東西寫成已驗證。
6. **只寫最終狀態，不寫我方作業時序**（鐵則 2 的時間軸版本）：報告呈現「現在的事實」，不呈現「我方跑了幾輪、什麼時候跑的、哪一輪失敗後來又修好」。
   **禁字**：複驗、重跑、補行、補跑、第 N 輪、報告產出前、當時、稍早、後來、原先跑的、再次執行。
   替代寫法：「調整前 334 項通過；調整後複驗 192 項亦通過」→「既有 334 項全數通過；受本次調整影響之 192 項另行驗證亦全數通過」。「報告產出前之複驗因外部服務無法連線未能重現」→ 移到〔測試限制〕寫成常態性邊界（「測試環境對外連線並非恆常可用——服務不可用時通知不會送出」），不寫成「我某次跑的時候壞了」。
   **邊界**：判準一句——**這句話講的是「系統現在怎麼運作」還是「我方做了什麼」？** 後者刪。
   「修正前／修正後」只在**交付物本身就是一份缺陷修復說明**時才保留（見鐵則 7）；一般測試報告不該出現。
   > 實案（2026-08-12）：報告寫「另補行複驗 64 項，其中 61 項通過；3 項因外部通知服務當時無法連線而未能完成」——把我方第二輪補跑的流水帳寫進交付文件，讀者無從判斷這與他何干；且「當時」是我方時間軸、不是系統事實。改寫成環境限制的常態描述後，資訊量不減而雜訊全消。

7. **測試報告不寫「我方修了什麼 bug」**（使用者裁決 2026-08-13）：測試報告的讀者是 PM／使用者，
   他要知道的是「這些功能現在能不能用」，不是「你們過程中修過哪些缺陷」。
   **不得出現的章節／列**：缺陷修復章（問題→原因→修改內容→修正前後對照）、
   「既有回歸測試」列（我方作業，非功能驗證）、「本次新增檢核 N 項」這類自述。
   驗證表只列**功能情境**——每列是「使用者做這件事，系統該有什麼結果」。
   **例外**：交付物本身就是缺陷修復說明（對方已知該缺陷、正等你回報修好沒），
   此時前後對照是主體，照寫；判準是「對方原本就在等這個修復的答案」，不是「我方覺得值得一提」。
   > 實案：報告寫了一整章「側欄選單缺陷修復」（含修正前後截圖），使用者裁決刪除——
   > 那是開發過程，PM 看了只會問「所以本來是壞的？」，徒增疑慮而無助於驗收。

8. **測試表的宣稱必須逐項對得上實際檢核**（使用者裁決 2026-08-13）：寫「N 項條件皆可篩選」
   之前，先數清楚實際 codify 了幾項。**畫面上有 9 個欄位、只驗了 4 個，就寫那 4 個**，
   不可用畫面欄位數充當驗證數。寫法：列出實際驗過的項目名（「可依歸屬單位、供應商、
   案件狀態、日期區間篩選」），而非給一個總數。
   > 實案：報告寫「九項條件皆可篩選」，實際只驗了四類——畫面確實有九個欄位，但其餘五個
   > 從未被測試碰過。這種誇大最難察覺（數字看起來很具體），且一旦被抽查就會動搖整份報告的可信度。

9. **易讀性鐵則同樣適用**：本模式產出的是交付文件本體，`../../references/document-readability.md` 的十二條鐵則（不要兩邊對照／資訊放一起／編號＝執行順序／不用未定義代號／不寫異動紀錄／能自查不丟給讀者／不重複不冗長／交付前全文機械掃描／視覺標記成套一致／能腳本化就不叫人手動／改文件前先讀實際樣貌／做完的事寫成做完）一律適用，其中鐵則 8 的五項掃描是**交付前必做**。

## 組裝前先做：證據盤點

動筆前把要引用的證據**實際開檔核對一遍，別憑對話記憶**：截圖檔真的存在且內容正確、資料庫實值／傳輸參數有留存紀錄可引用、每個要寫進測試表的「實測結果」都指得出對應證據。缺的分兩種：**已驗證過的行為只是畫面／紀錄沒留存**——重新擷取即可（重開畫面截圖、重撈紀錄），仍屬文件化。「已驗證過」的認定不憑宣稱：要指得出當時留下的其他佐證（測試紀錄、執行輸出、既有報告草稿之一）；指不出來、或重擷結果與當時佐證不一致，一律當測試沒做完處理。**需要重新執行測試情境才能產生的證據**——那是測試沒做完，退回 qa 系 skill 補跑，不在本模式內做。兩者都補不了就從報告中省略該情境、並在「交付前的揭露」對使用者如實標註——不可憑印象把「實測結果」欄填滿（那是換條路徑違反「不憑描述寫報告」）。

## 組裝前再做的決定

**沒有固定目錄。先回答這幾個問題，答案決定哪些構件入場、怎麼排：**

1. **這份報告要證明幾件獨立的事？** 每件事（一個修復、一個工具、一個功能）自成一個區塊，區塊內再挑構件。
   **編號用純序號（1、2、3…），不要加 A-／B-／C- 前綴**（2026-08-25 使用者裁決：問「A-N 是啥」＝沒過關）。多區塊時用區塊標題區隔，不靠字母前綴；交叉引用一律寫「第 N 項」，不寫「A-N」。詳見 `../../references/document-readability.md` 鐵則 4。
2. **對方拿報告去做什麼？** 簽核放行 → 結論與測試表前置；理解問題始末 → 白話對照前置；照著操作 → 執行程序構件必入且靠後放。
3. **交付的是「修復」還是「工具／新功能」？** 修復類重「前後對照」；工具類必帶〔部署後執行程序〕（對方要照著跑的步驟比證明更重要；測試限制不進報告，走交付揭露）。
4. **有沒有動過正式環境？** 有 → 〔資料修正紀錄〕必入（動了什麼、何時、事前確認了什麼）。
5. **對方之前看過什麼？** 對方親歷過的錯誤畫面／提過的問題，用它開場錨定（他的截圖、他的原話），比任何說明都快。

> 構件的順序原則只有一條：**對方最想先看到的放前面**（與 deliver-report skill「決定一」同一個判準）。

## 段落構件庫（按需取用，用不到就不出現）

### 〔總覽與結論〕——結論句按範圍分列，不用單一總數
結論句寫成「〈範圍A〉 N 項、〈範圍B〉 M 項…，全數驗證通過，建議部署」——按驗證範圍分列數量，讓簽核者一眼看到覆蓋的形狀（2026-08-19 使用者裁定）。**不用**「共執行 299 條測試案例」這種單一總數（對讀者無資訊量，細節本來就在各章表格）。分列的數字必須與總覽表逐項對得上；有未全過的範圍照實寫「N 項通過、M 項△△」。

### 〔白話對照〕——說明「問題是什麼、修了什麼」
每個問題／流程一組，粗體標題用使用者視角的一句話：
```
（一）〈使用者會怎麼描述這個問題〉
- 原因：〈系統為什麼會這樣，白話因果〉
- 修正後：〈使用者會觀察到的新行為〉
- （資料回補類加）回補方式：〈用什麼資料、怎麼補〉
```
語氣參考：「原因：系統送資料給 SAP 時，讀取到的是尚未存檔的舊資料。」「修正後：SAP 會正確收到最新的銀行帳號、戶名及分行資訊。」

### 〔修改內容表〕——一眼看出動了哪幾層
欄位：層別（前端／後端／資料庫）｜修改項目｜白話說明。只在「多層都有改」時才值得成表；單層小改用一句話講完就好，別為了表格而表格。

### 〔測試結果表〕——證據主體
| 欄位 | 內容 |
|---|---|
| 編號 | 純序號（1、2、3…），截圖圖說要能引用；不加字母前綴 |
| 測試情境 | 一句白話，含資料形態（「材料類別僅有空白明細＋共通有負責人」） |
| 預期結果 | 可觀察行為 |
| 實測結果 | **值層級證據**：資料庫實值、送出參數逐欄比對——不是「畫面有東西」「回 200」 |
| 判定 | 通過／不通過 |

證據強度（有就寫進實測結果欄，沒有不硬湊）：
- **前後對照**：「修正前重現：資料庫正確、SAP 收到舊值」。
- **變異測試**是最強的即時性證明（改值→重送→參數即時反映→還原），有做必列一列。
- 完整鏈路測試註明起訖（「由供應商送件、簽核回調到核可寫入 SAP，非單點函式測試」）。

### 〔實測畫面〕——每張錨到測試編號
- **截圖時機＝等 DOM 載入完成，不是 sleep**（2026-08-19 使用者裁定，實例：外站首頁在使用者名稱與計數卡回來前被截成空頁）：按快門前以「關鍵元素就位」為據——歡迎詞帶出名稱、計數卡有實值、清單有資料列（或明確的空狀態文案）；用等待元素的方式等，不用固定秒數賭運氣。**「還沒載入」與「真的沒資料」要分辨**：名稱缺、骨架屏、spinner、計數未回＝未載入必重拍；關鍵欄位就位後的空清單＝真實現況可入圖。每張拍完開圖確認，不憑檔名與時間戳。
- 圖說格式：`圖 N　〈修正前／修正後／系統畫面〉（對應第 N 項「〈測試情境名〉」）：〈這張證明了什麼〉`。**帶上情境名，讀者才不用回頭查表**。
- 修正前的真實錯誤畫面（尤其使用者提供的正式環境截圖）最有說服力，有就用。
- 敏感區裁切：Authorization／token 區必裁；瞬時元素（1 秒消失的 toast）截不到就用動作後的落地畫面替代，圖說**如實寫**是落地畫面。
- 三方一致採證是好模式：畫面值＋系統傳輸紀錄＋資料庫值，同值各一張。
- 圖寬統一 16.5cm、置中、圖說 9pt 灰字置中。

### 〔資料修正紀錄〕——動過正式環境才出現
動了什麼（幾筆、什麼條件）、何時、事前確認了什麼、事後狀態；加一句時效警語（「程式修正部署前若使用者重新儲存，資料會再產生，部署後由程式自動處理」這類）。

### 〔測試限制〕——已廢除（2026-08-18）
測試限制不再寫進報告，改走「交付前的揭露」對使用者逐條揭露；使用者點名要寫進報告的個別項目，才以最小篇幅入報告。

### 〔部署後執行程序〕——對方要照著做的步驟
逐步、每步一句、含核對點（「步驟二：挑選 1 家執行，確認 SAP 端資料正確更新」）。工具類交付必帶，放文件尾端。

### 〔上線建議〕／〔附註〕
上線建議：一兩句部署順序與注意事項。附註：附帶改善、另案事項，一句一條——與 deliver-report skill 的「另案建議」同一個精神：計數清楚、不展開。

## DOCX 產出（python-docx 技術要點）

- **樣式基準＝同專案前一份已交付報告**（2026-08-18 使用者抓過不一致）：動筆前先開前一份報告抽實際樣式（Title/Heading 用內建或自訂、內文字級與粗細、表格字級、圖說樣式與對齊、圖寬、頁邊界），逐項對齊後才產出——勿自創版式；無前例可循時才用下方預設。抽樣式用程式讀 document.xml 的 run 屬性，勿憑肉眼；字型要抄全三軌（ascii/hAnsi/eastAsia）——只設 eastAsia 時拉丁字母與數字會 fallback 到佈景主題（常是 Cambria 襯線）造成兩份文件字型不一致；粗體判讀認 `w:b` 的 `w:val`（`val=0` 是明確關閉，元素存在≠粗體）。
- 生成腳本落在 scratchpad，可重跑（迭代＝改腳本→重生成→同檔名覆蓋，不開 v2 檔名）。
- 字型：`Calibri`＋東亞字型 `微軟正黑體`（heading 的 runs 也要逐一設，python-docx 不會自動繼承）：
  ```python
  r.font.name = "Calibri"
  r.element.rPr.rFonts.set(qn("w:eastAsia"), "微軟正黑體")
  ```
- 表格 `Table Grid`、表頭粗體、內文 10pt；欄寬 `Cm()` 逐欄設。
- 檔名：`〈系統〉_〈主題〉_測試報告_YYYYMMDD.docx`。
- **交付位置與資料夾紀律**（通則：**除最終交付檔外，一切產出進 `_work/` 納管，不散出來**）：
  - 最終交付檔放**專案內慣用交付路徑**下、為本次交付**另開的專屬資料夾**（例：`tests/reports/〈主題〉_〈YYYYMMDD〉/`）；資料夾第一層**只有最終交付檔**（報告 DOCX；若交付物含多份檔案如明細 Excel，同列第一層）——收件人點進來就是成品。
  - **其餘一切過程產物**（測試結果檔、截圖、文字傾印、中間資料…不分格式）收進該資料夾內的 **`_work/`** 子資料夾，不與交付檔混放。
  - 交付路徑根層**只承載各次交付的資料夾**，不得散落任何檔案。
  - 生成腳本留 scratchpad（可重跑，迭代同檔名覆蓋）；**不主動複製到桌面或使用者個人目錄**，除非使用者當次點名（2026-08-18 裁定）。
  ```
  tests/reports/
  └─ 〈主題〉_〈YYYYMMDD〉/
     ├─ 〈系統〉_〈主題〉_測試報告_YYYYMMDD.docx   ← 第一層只放最終交付檔
     └─ _work/                                    ← 其餘一切過程產物
  ```

## 交付前的揭露（報告之外，給使用者）

報告定稿交給使用者時，**把不進報告的誠實資訊逐條列給使用者**（不進報告本身；主觀取捨要留人覆核機會）。揭露的項目：

- **誠實邊界類（鐵則 5 的落點）**：未能驗證的情境與原因、驗證層級缺口（模擬服務代真實端）、環境限制、測試發現但未修復的缺陷、後續建議事項——報告本體不寫這些，全在這裡讓使用者決定要處理、要破例寫進報告、還是知悉即可。
- **編寫取捨類**：被省略或另案化的項目有哪幾條、截圖替代（落地畫面代瞬時畫面，圖說仍須如實）——不揭露使用者就無從覆核。

格式例：「另外提醒：寄送失敗情境這輪無從重現、電力欄深度比對缺測試資料，都沒寫進報告；圖 5 是落地畫面。哪條你覺得該寫進報告或要先處理就跟我說。」

## 迭代慣例

- 使用者的逐條修訂（刪某句、補某圖、改措辭）直接改腳本對應段，不重排整份。
- 報告定稿後若使用者要交付訊息（信件），改用 **deliver-report skill** 走它的四個決定——報告檔的地位（主體／佐證）由該 skill 的決定一逐案判，不預設。