手動測試 是做什麼的?
測試證明程式碼做了什麼。手動測試則證明使用者得到了預期的東西。對於每個使用者可以看到、聽到或感受到的變更,你必須製作一份陌生人也能在一分鐘內冷靜判斷的證據:一支影片和一張看板,BEFORE(紅色徽章)與 AFTER(綠色徽章)並排顯示,同一個位置、同一個操作,只有該項變更不同。變更在審核者說 OK 之前不得合併。
專案的事實記錄在該使用者儲存庫的 docs/agents/hand-test.md 中:如何取得 BEFORE、如何驅動與錄製這個介面、裝置規則、證據存放位置、誰負責審核,以及 OK 與 Not OK 的處理方式。如果該檔案不存在,請先遵循 SETUP.md。
工具是 scripts/handtest.py。執行方式為 uv run <此技能資料夾>/scripts/handtest.py <command>;任何指令加上 --help 會列出其旗標。它需要 ffmpeg 與 ffprobe 在 PATH 中;uv 會帶入 Pillow。如果沒有 uv,請在儲存庫外建立虛擬環境(python3 -m venv <dir> && <dir>/bin/pip install pillow),然後使用 <dir>/bin/python 來執行工具。
1. 分類變更
在 PR 主體(或描述變更的任何地方)加上 ## Hand test 章節:
yes: <要觀察的內容>:針對使用者可以看到、聽到或感受到的任何事物:UI、行為、時序、聲音、文案、設計。no: <為何沒有看到、聽到或感受到>:針對工具鏈、建置、測試、文件,或輸出一致的重構。
若有疑慮,則為 yes。
完成條件: 章節已存在。no 則結束此技能。
2. 規劃拍攝
命名關鍵時刻:變更顯現的那一個步驟。如果變更從第一幀就在畫面上(顏色、標籤、版面),則那一個時刻就是畫面出現的瞬間,或是之後的第一步。
將步驟撰寫成腳本,用來驅動真實的應用程式,雙邊必須完全相同(各介面的指令請見 CAPTURE.md):
- 透過應用程式自己的 UI 進行真實輸入:測試捷徑應跳過使用者實際操作的程式碼。
- 根據元素的標籤或角色來尋找,絕不使用座標:版面移動往往就是變更本身。
- 在關鍵時刻之前等待真實狀態(例如顯示了某個標籤、請求完成),絕不使用固定計時器。在關鍵時刻之後則維持一段固定時間。
- 雙邊使用相同的裝置、視窗大小、語言、資料與初始狀態。
- 在
finally區塊中將所有狀態恢復。
BEFORE 來自真正的舊狀態:基礎提交的建置結果,或是在執行時期關閉該變更。不要為了它儲存任何檔案變更。
如果變更涉及空間、時間或感覺等問題,且在建置前沒有人確定(例如多大、多快、應該是什麼感覺),則停止並告知使用者。這屬於建置前的互動式草稿範疇;手動測試只是驗證決策,而非制定決策。
完成條件: 腳本能乾跑(不錄製任何內容)BEFORE 與 AFTER,找到每個元素(或達到每個只能拍攝靜止畫面的狀態),且裝置與工作目錄恢復原狀,工作樹的 checksum 在執行前後保持一致。
3. 錄製雙邊
先錄製 BEFORE,再錄製 AFTER,使用相同的腳本。遵循專案的裝置規則:僅觸碰受測應用程式、不安裝任何軟體、不更改任何系統設定,且只在受測應用程式位於前景時發送輸入。
完成條件: 存在兩份原始錄製檔案,各顯示了關鍵時刻,且工作樹的 checksum 仍然一致。
4. 製作證據
init --out "$HANDTEST_ROOT/<group>" --id <N> --topic <kebab-case> --title "<plain words>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>"。group、OK 與 Not OK 來自專案檔案。你的 shell 可能不會在指令之間保留HANDTEST_ROOT:請在同一個指令中設定。- 在每個錄製檔案中,於關鍵時刻前後執行
find-change <raw> --from <s> --to <s>。同步時間是畫面變化的那一幀,而非步驟的記錄時間。 pair --before <raw> --after <raw> --sync-before <s> --sync-after <s> --title ... --what ... --caption ... --out <folder>/<id>_<topic>.mp4。它會將影片時間填入 README.md 與 PACKAGE.md,並印出關鍵時刻在影片中的位置。- 從原始錄製檔案中,在關鍵時刻之後的一個時間點,為每邊擷取一張靜止畫面:
stills <raw> --at <s> --out <scratch>/before,AFTER 同理。它會印出每個檔案。然後執行board --before <png> --after <png> --title ... --caption ... --out <folder>/<id>_<topic>_BEFORE_AFTER.png。 - 填寫所有
<fill in: ...>標記。文字與數字的規則請見 EVIDENCE.md。
完成條件: check <folder> 印出「ready for a person」。
5. 審查者自檢
在任何人看到之前,先以陌生人的角度自行審查。從影片中擷取靜止畫面兩次:stills <video> --every 1 --out <scratch>,然後 stills <video> --at <t-0.5> <t> <t+0.5> --out <scratch>,其中 t 是影片中關鍵時刻的時間點,而非原始錄製中的時間(pair 會印出它;handtest.json 會把它記錄為 video.change_at)。檢視每一張靜止畫面以及看板。
- 每張畫面都必須顯示其標題要觀察的內容。如果被遮蓋、空白、狀態錯誤、語言錯誤、或變更上有覆蓋層:則將資料夾
archive歸檔,並從步驟 3 重新錄製。重新錄製,而不是在 README 中為不佳的圖片找理由。 - 數字必須與圖片一致。如果不一致,則數字有誤:找出原因。
- 通過測試但圖片錯誤則代表發現了問題。向使用者回報為一個 bug。
完成條件: 每張靜止畫面與看板都顯示了標題所宣稱的內容,且 README 中的每個數字都與圖片相符。
6. 交付
將資料夾放到專案的證據存放位置。將 PACKAGE.md 張貼到專案檔案指定的位置,僅提及資料夾的相對路徑,絕不包含帳號或絕對路徑。在 PR 的 yes 行中補上該路徑以及等待審核的人員(格式請見 EVIDENCE.md 中的「The PR section」)。通知審核者。在手動測試尚未關閉期間,變更保持未合併狀態(在有 PR 的環境中則為 Draft PR)。
完成條件: 資料包已張貼,PR 中的該行已命名資料夾,已通知審核者,且變更的任何部分都尚未合併。
7. 記錄 verdict
Verdict 由審核者決定。絕不記錄他們未給予的 OK。
- OK:
verdict <folder> --ok --by "<who>"(它會拒絕一個未通過check的資料夾),然後執行專案檔案中 OK 所指示的動作(通常為將 PR 標記為就緒)。 - Not OK:
verdict <folder> --not-ok --by "<who>" --note "<他們說的話>"。在同一個分支上修正問題,將資料夾archive歸檔,然後回到步驟 3。重做時會再次產生相同的檔名;舊的拍攝會被移動到previous/資料夾。當init寫入新的 README.md 時,請從previous/<stamp>_README.md複製仍然適用的行;pair會重寫時間。
完成條件: handtest.json 中記錄了使用者的 verdict,且追蹤器與之一致。
發版
將每個手動測試的資料夾放在每個發版的一個 group 資料夾下,然後執行 report <group> --title "<release>"。它會寫出 REPORT.md 與一個自包含的 index.html,待審核的手動測試會排在前面。請見 EVIDENCE.md。