手動測試計畫 是做什麼的?
撰寫在正在運行的應用程式中檢查此分支的計畫。該計畫涵蓋自動化測試無法顯示的內容:變更在真實數據、真實流程中,以及使用者可達到的各種狀態下,其外觀和行為如何。
每個案例都分配給能夠解決它的人:驅動瀏覽器的代理、驅動 iOS 模擬器的代理,或人工操作。給予代理所有代理可以解決的事項。對於僅有人類才能解決的案例,先讓代理作為排演嘗試,以便在人工花費時間之前發現明顯問題,並且讓人工知道該往何處查看。
在應用程式中執行一個案例的代價很高。驅動瀏覽器的代理在相同檢查上所花費的 token 是程式碼測試的許多倍,而人工則需要花費數分鐘。因此,計畫要小而精:它只包含最可能暴露重大錯誤的案例,而不包含任何程式碼測試也能同樣涵蓋的內容。一個好的計畫足夠簡短,可以完整執行。
基於同樣原因,請在後期才撰寫並執行計畫:在審查程式碼、根據審查意見進行的修正和重構,以及程式碼測試就緒之後。然後,針對將要合併的程式碼,僅執行一次計畫;而先前的通過已經進行了成本較低的檢查。如果程式碼仍在變更中,請在計畫頂部說明。如果在計畫執行後程式碼發生變更,請指出哪些案例需要重新執行:其「捕捉」行指向已變更程式碼的那些案例。
本地注意事項。 如果此檔案旁有一個名為 LOCAL.md 的檔案,請在開始之前閱讀它。它包含使用者為其專案設定的預設值(命令、主機、帳戶、路徑),且不屬於發布的技能的一部分。只要它涵蓋了當前專案,就視為專案說明的一部分;如果沒有,則忽略它。
收集變更
請求可能會指定一個基礎分支。如果沒有給定,則按以下順序選擇:
- 分支拉取請求的基礎分支(如果有):
gh pr view --json baseRefName --jq .baseRefName。 - 儲存庫的預設分支:
git symbolic-ref --short refs/remotes/origin/HEAD。 origin/main,然後是main。
優先使用遠端追蹤引用(origin/<branch>)而非同名的本地分支。包含尚未提交的工作:
base=$(git merge-base <base> HEAD)
git diff --stat "$base" # 已提交 + 已暫存 + 未暫存
git diff "$base"
git status --short # 未追蹤的檔案不在 diff 中;請閱讀它們
git log --oneline "$base"..HEAD
閱讀 diff 未包含的三個來源
diff 顯示了變更的內容。它沒有顯示變更的目的、人們已經發現的問題,或者在此對話中已做出的決定。在選擇任何案例之前,請閱讀所有這三個來源。它們是必要的輸入,而非背景;計畫會報告讀取了哪些內容,並顯示每個來源如何影響了計畫。
1. 拉取請求及其評論
pr=$(gh pr view --json number --jq .number)
gh pr view --json title,body,baseRefName
for kind in "issues/$pr/comments" "pulls/$pr/reviews" "pulls/$pr/comments"; do
gh api "repos/{owner}/{repo}/$kind" --paginate --jq '.[]
| select(.user.type != "Bot" and (.body // "") != "")
| {id, reply_to: .in_reply_to_id, user: .user.login, path, line: (.line // .original_line), body}'
done
這三個列表分別是對話評論、審查摘要以及 diff 中行內代碼的評論,已排除機器人輸出。但機器人通常仍會提供部署鏈接,因此請單獨查找。部署環境不是執行計畫的地方(請參閱下面的「測試本地 build」);鏈接僅用於比較和作為備用:
gh api "repos/{owner}/{repo}/issues/$pr/comments" --paginate \
--jq '.[] | select(.user.type == "Bot") | .body' | grep -oE 'https?://[^ )|>"]+' | sort -u
閱讀描述、每個人類評論以及作者的回覆。描述中的報告與評論中的報告具有同等效力。從中獲取:
- 任何人在應用程式中看到的內容: 一個錯誤的值、一個永不結束的狀態、一個中斷的流程、一個螢幕截圖。每一個都成為一個案例,無論程式碼是否已更改,都重新測試該確切報告。然後詢問同樣的錯誤可能在何處再次出現(同級畫面、通過其他方式達到的相同狀態),並考慮在該處添加案例。
- 審查中提出的行為疑慮(例如「順序可能與顯示的內容不一致」):每一個都是候選案例,評級為高可能性,因為程式碼的閱讀者已經懷疑它。
- 描述中的測試說明: 作者聲稱已測試的內容以及他們聲明未測試的內容。根據提交日誌(
git log --format='%h %ad %s' --date=short "$base"..HEAD)為說明標註日期:在後續提交觸及相同程式碼之前測試的內容,尚未以其當前形式進行測試。在最後一次手動測試之後落地的提交,是計畫應首先針對的目標。 - 部署環境的鏈接: 分支本身的部署以及基礎分支的部署,用於並排比較。
- 討論線程中關於行為應如何的決定。 這些確定了預期結果。
2. 議題
在分支名稱、提交主題、拉取請求標題或正文,或拉取請求上跟蹤機器人的評論中,找到議題標識符。使用專案說明中命名且可用的工具,通過跟蹤器查找它。閱讀描述、接受標準、討論以及任何附加的螢幕截圖或重現步驟。從中獲取:
- 原始報告。 如果議題描述了錯誤,其重現步驟將成為計畫中的第一個案例:按報告的步驟操作,以修正後的行為作為預期結果。如果議題只是一個標題,或者指向無法閱讀的線程或附件,請說明,從標題和拉取請求描述中重建案例,並標記為重建。
- 每個接受標準。 每一個必須歸入以下三個位置之一:計畫中的案例、涵蓋它的命名程式碼測試,或被排除的清單並附上原因。
- 議題中提到的受影響使用者、數據和平台, 這些說明了要使用的數據形狀和測試設備。
- 它連結的相關議題, 這些議題描述了同一區域以另一種方式失敗的情況。
3. 到目前為止的對話
在撰寫之前回顧本次對話。從中獲取:
- 審查發現: 首先針對當前程式碼樹檢查每個發現,因為它可能已經被修復。需要運行應用程式來確認的發現將獲得一個案例:一個確認修復的案例,或一個顯示未修復缺陷的案例。可以由程式碼測試確定的發現將進入待撰寫測試清單,而不是案例。
- 來自早期審查階段的「未驗證」清單和手動驗證步驟。 這些是為了在應用程式中檢查而編寫的;它們是最直接的輸入。
- 使用者對變更的陳述: 他們擔心的部分、提到的狀態、已手動測試的內容,以及要求不要花時間的內容。明確的擔心會提高案例的評級;「我已經檢查過了」則將其移除。
- 對話中關於行為的決定, 這些確定了單靠程式碼無法確定的預期結果。
- 對話期間程式碼中發生的變更。 在此會話中編寫或重寫的程式碼受到的測試最少。
如果對話中沒有任何相關內容,請在計畫中說明;不要假裝有。
當無法讀取來源時
如果 gh 缺失或未登入、分支沒有拉取請求、沒有連結議題,或跟蹤器無法訪問,請利用現有資源繼續進行。在計畫頂部列出每個未讀取的來源,並說明計畫可能遺漏了它所包含的內容。不要將僅基於 diff 建立的計畫呈現為完整的計畫。
閱讀其他可能影響計畫的內容
- 如何在本地運行應用程式: 專案文檔中記錄的本地 build 命令、它連接的後端以及使用的端口。閱讀專案關於測試環境、測試帳戶和功能標誌的說明,以及應用程式發布的平台(網頁、iOS、Android)。
- 自動化測試涵蓋的內容: 閱讀 diff 中的測試,這樣計畫就不會浪費任何人的時間在測試已經確定的內容上。
- 此處代理有哪些工具: 它可以驅動的瀏覽器和設備模擬器。在 Orca 中,這些是嵌入式瀏覽器(
orca-cli技能)和 iOS 模擬器(orca-emulator技能;Android 是orca-emulator-android)。也要查找:- 代理可以驅動的螢幕閱讀器, 例如
voiceover技能,它針對頁面運行真實的 macOS VoiceOver 並返回其朗讀的內容。 - 腳本化瀏覽器(帶有已安裝瀏覽器的 Playwright),用於嵌入式瀏覽器無法執行的操作。例如,嵌入式瀏覽器可能無法將內容放入系統剪貼簿,因此檢查複製的內容需要一個代理可以讀取剪貼簿的瀏覽器。
- 代理可以驅動的螢幕閱讀器, 例如
請注意此會話中可用的工具;計畫會在其設置中說明。
測試本地 build,而不是已部署的分支
針對工作目錄的本地 build 規劃每個案例。已部署的功能或預覽環境僅包含已提交和推送的內容:它落後於正在處理的程式碼,無法顯示未提交的變更,並且在測試期間進行的修復需要提交和推送才能在那裡重新測試。本地 build 顯示當前的程式碼,並且修復可以立即重新測試。
因此,計畫的設置應說明:
- 如何本地構建和啟動應用程式, 使用專案文檔中的確切命令、運行它的目錄以及它提供的 URL。如果其他會話或工作目錄可能正在運行應用程式,請說明如何選擇空閒端口。
- 本地 build 連接哪個後端。 它必須是暫存或測試後端,絕對不能是生產環境。指向生產環境的本地 build 會對真實客戶的系統運行每個案例,包括模擬的案例和訂單。專案通常為每個環境提供一個命令(例如
stage和prod腳本):在計畫中指定暫存環境的命令,並明確說明不得使用生產環境的命令。如果專案文檔未明確說明哪個命令針對哪個後端,請從 build 配置中查明;如果仍然不清楚,請停下來詢問使用者,不要猜測。 - 如何在第一個案例之前檢查後端: 查看運行中的應用程式發送請求的位置(網路日誌中 API 調用的主機,或配置的 API URL)並確認它是暫存主機。計畫會指定預期的主機。如果是生產環境主機,請停止:不要登入,也不要執行任何案例。
- 如何確認 build 是當前程式碼: 在最後一次更改後從工作目錄啟動它,並在進一步更改後重建或重新加載。如果應用程式顯示版本或提交,請檢查它。
- 如何停止它 當運行結束時。
僅在以下情況下使用部署環境:
- 與基礎分支比較: 基礎分支的部署,與分支的本地 build 相鄰,用於並排比較案例。
- 本地 build 無法顯示的內容: 關於部署本身的案例,例如 build 後的資產、緩存或包裝部署站點的原生應用程式。在執行此類案例之前,請確認工作目錄是乾淨的、已推送,並且部署服務於該提交,並在案例中說明。
- 當無法本地 build 應用程式時的備用方案。 在計畫頂部說明原因,並聲明部署提供哪個提交以及工作目錄中缺少哪些內容。
相同的規則適用於計畫使用的任何部署環境:使用暫存部署,絕不使用生產部署。如果一個分支同時具有暫存和生產部署,請僅在計畫中提供暫存 URL。
確定要測試的內容
-
列出使用者可以看到或執行的不同之處。 將 diff 中的每個更改向外追溯到顯示它的畫面和流程。共享程式碼中的更改會影響使用它的每個畫面;搜索調用者並列出所有畫面,包括分支原本不涉及的畫面。
-
對於每個畫面,確定是否需要運行應用程式。 詢問程式碼測試是否可以解決它。如果已經有測試,則跳過。如果可以輕鬆編寫測試(純函數、解碼器、排序順序、給定狀態的視圖函數、狀態轉換),則將其從案例中排除,而是加入待撰寫測試清單;這樣該檢查將在每次變更時自動運行,而無需每次在應用程式中運行案例。只保留程式碼測試無法達到或不可信的內容:來自真實後端的真實數據如何傳遞、在真實瀏覽器中如何渲染和佈局、單獨測試的部件組合在一起時的行為、真實請求的時間和順序、真實導航後應用程式的狀態,以及提供給輔助技術的內容。
-
找出狀態。 對於每個畫面,閱讀程式碼以了解它可以採用的分支:已加載、加載中、空、錯誤、缺失或部分數據、零值和負值、非常長的值、一個項目和多個項目、每個改變顯示的設置或模式、每個帳戶或用戶類型。保留 diff 觸及到的狀態。
-
確定如何到達每個狀態。 命名導航路徑,並按其形狀描述所需的數據(例如「在兩個帳戶中持有的工具,其中一個沒有購買成本」),而不是使用您尚未確認存在的帳戶。如果某個狀態難以使用真實數據達到,請說明如何產生它(功能標誌、重寫響應、限制網路、設置),或將其標記為需要特定的測試帳戶。
當案例依賴於重寫的響應時,計畫必須使重寫可重複;
reference/mocks.md說明了如何操作。為每個案例提供一個不依賴於帳戶數據運氣的方法。如果真實數據可能缺少該狀態,請在應用程式中命名可以打開它的控制項(設置、切換、另一個帳戶)
...
[為翻譯而截斷]