核准式測試(Golden-Master 基準)

核准式測試(又稱 golden-master / snapshot 測試)把「這個輸出還正確嗎?」重新表述為 「它是否仍與人工核准過的版本相符?」。verify_artifact() 將產出的內容與儲存的 <name>.approved.<ext> 基準比對:

• 相符 → 檢查通過;

• 不符或缺少基準 → 產出的位元組會被寫入 <name>.received.<ext> 且檢查失敗,讓 審查者可比對兩者,若變更為預期,即以 approve_artifact() 晉升。

它適用於*任何*產物 —— 渲染後的文字、JSON、OCR 輸出、螢幕截圖位元組 —— 因此以一個受 審查把關、與測試一起提交的基準,補強逐像素比對。純標準函式庫,不匯入 PySide6。 名稱會經過路徑穿越驗證。

無頭 API

from je_auto_control import verify_artifact, approve_artifact

result = verify_artifact("invoice_render", produced_text,
                         approvals_dir="tests/.approvals")
if not result.match:
    # 首次執行為 "new",輸出變更為 "mismatch";審查 .received 檔後再核可:
    approve_artifact("invoice_render", approvals_dir="tests/.approvals")

content 可為 str 或 bytes``(二進位快照請傳 ``extension="png")。相符的執 行會清除任何過期的 received 檔。pending_artifacts(dir) 列出仍待核准的名稱。 ApprovalResult 帶有 status``(``verified / mismatch / new)、 match 及兩個檔案路徑。

執行器指令

指令	效果
AC_verify_artifact	將 content 與已核准基準比對。
AC_approve_artifact	將 received 產物晉升為基準。
AC_pending_artifacts	列出待核准的產物。

相同操作亦提供為 MCP 工具(ac_verify_artifact / ac_approve_artifact / ac_pending_artifacts),以及 Script Builder 中 Testing 分類下的指令。