Communitygithub.com

prove-it

驗證某個 pytest 迴歸測試是否在修復提交前捕捉到指定錯誤,並在修復後通過測試,包含重複執行與可審查的證據。用於驗證錯誤修復的聲明或檢查一個即使沒有修復也能通過的測試。

prove-it 是什麼?

此技能專為驗證一個狹義的聲明而設計:同一個 pytest 測試案例,在套用錯誤修復前會因捕捉到特定缺陷行為而失敗,在套用修復後則會通過。它透過比較兩個已提交的 Git 參考(before 與 after)來達成此目的,其中 after 參考必須包含修復程式碼與測試案例。技能會執行一個腳本,在每次執行時覆蓋指定的測試檔案,分別針對兩個快照重複運行測試(預設三次),並檢查測試中的特定斷言訊息(以 PROVEIT: 前綴標記)。 此技能支援在 Claude Code、Cursor 或 Codex 等 AI agent 環境中使用,但強烈依賴於本地 Git 倉庫與已安裝的 pytest 及其依賴項。它不會自動安裝依賴、存取網路或修改 Git 狀態,只會建立暫存快照進行測試。最終產出包含 report.md、report.json、差異檔案等證據,並明確區分三種結果:supported(支援聲明)、not_supported(不支援聲明)與 inconclusive(無法判定)。 使用此技能時,需仔細選擇測試節點與斷言訊息,確保該斷言確實觀察到缺陷行為。它不適用於驗證整體正確性、消除測試不穩定性或評估測試品質。結果的可靠性取決於測試環境的隔離性與共用依賴的穩定性,因此在使用前應確認測試環境的設定不會干擾結果的解讀。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/K-kiron/ProveIt/tree/main/skills/prove-it

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Prove It

建立一個狹義的聲明:同一個測試在修復前能捕捉到指定的缺陷行為,並在修復後通過測試。僅有測試套件通過並不能證明這一點。

選擇見證者

檢查修復程式碼與相關測試。識別預期的輸入/輸出或狀態轉換,並選擇確切的一個 pytest 節點。使用兩個已提交的本地 Git 參考;after 參考必須同時包含修復程式碼與測試。未提交的編輯不會被納入。不要為了執行此工具而提交他人的程式碼。

缺陷斷言需要一個特定的訊息,例如:

assert expired(now=10, deadline=10), "PROVEIT:expiry-boundary"

該訊息必須位於所選測試函數中的斷言上。不要將其放在無關的斷言、fixture、應用程式程式碼或 print 語句中。檢查此斷言確實觀察到錯誤描述的行為。如果現有測試需要一個訊息,只能在授權的編輯範圍內添加,並將該測試納入 after 修訂版本中。否則,請解釋缺乏輸入的原因。

執行比較

使用其絕對安裝路徑執行捆綁的腳本。所選的直譯器需要已安裝 pytest 以及專案的相依套件。不會執行相依套件安裝、網路存取、Git checkout、reset、stash 或 commit。

python <skill-directory>/scripts/proveit.py --repo <repository> --before <old-ref> --after <fixed-ref> --test tests/test_expiry.py::test_at_deadline --expect PROVEIT:expiry-boundary --output <new-directory-outside-repository>

執行器會將 after 修訂版本的所選測試檔案覆蓋到兩個快照上,每次嘗試使用全新的副本,預設每個修訂版本執行三次,每次執行超時 10 秒。僅在任務需要時才使用 --python、--repeat 2..5 或 --timeout。如果測試是參數化的,請選擇完整的參數 ID。

快照隔離檔案,而非執行環境。僅執行在當前環境中已被授權執行的程式碼。測試保留使用者的檔案系統、網路和憑證存取權限。不要將暫存目錄解讀為安全沙箱。切勿清理無關的工作樹或目錄。執行器只會移除其自身的暫存快照,並保留證據目錄以供審查。

審查證據

閱讀 report.md、report.json、selected-test.py、fix.diff 以及相關日誌。檢查觀察到的斷言、所選的節點、階段記錄以及變更的路徑。

結果解釋退出碼
supported每次舊版本執行都命中宣告的斷言;每次新版本執行都通過。0
not_supported舊測試也通過,或修復後的修訂版本仍然命中該斷言。1
inconclusive環境、無關的失敗、超時、跳過、不完整或不穩定的執行。2

即使新修訂版本通過,無關的呼叫失敗也屬於 inconclusive。集合、相依套件、語法、setup 和 teardown 的失敗永遠不是見證者。不要將其重新標記為捕捉到的錯誤。在範圍內解決觀察到的原因,並重新執行到一個新的證據目錄中;不要重複執行未變更的失敗設定。

在接受 supported 結果之前,檢查修訂版本特定的 fixtures/configuration,並確認它們不能解釋行為的變化。只有所選的測試檔案會被覆蓋。已安裝的相依套件是共享的,第三方 pytest 外掛程式的自動載入功能已停用,並且專案的 addopts 已被清除。需要外部外掛程式或建置的專案可能需要一個單獨準備的環境;請如實報告不支援的執行情況。

報告測試、參考、結果、證據位置以及重大限制。說明此見證者在這些執行中捕捉到了指定的行為。不要聲明證明了整體正確性、消除了不穩定性、一般測試品質或可衡量的生產力提升。未經審查並獲得適用的發佈授權,請勿發佈包含本機路徑或日誌的報告。

相關技能