跳轉到

D-20260822-01｜人工視覺證據與自動 E2E 分層

背景與驅動力

GitHub hosted Ubuntu 的 Chromium E2E 兩次在只驗證成功截圖尺寸的 Page.captureScreenshot 呼叫間歇失敗；相鄰 run、本機、Docker 壓力測試與同一 run 的產品流程 可以通過。該截圖只供人工觀看，不判斷玩家行為，卻會使 required CI 紅燈。其他 E2E 也有成功 路徑附加截圖，若只處理單一案例，仍會保留相同的錯誤阻擋面。

考慮過的選項

  • 對 screenshot 加 retry：可能把 runner 或產品回歸洗成綠燈，且增加 private Actions 時間，否決。
  • 把所有使用 screenshot API 的測試移出 CI：會失去 Canvas 黑畫面、縮圖透明度等可機器判定的 產品視覺 gate，否決。
  • 依輸出角色分層，純人工 artifact 本機 opt-in、產品斷言與失敗證據保留自動化：採納。

決定

  • 成功截圖、完整頁面稽核與 viewport evidence helper 契約只在非 CI 本機明確 opt-in 時執行； hosted、self-hosted、nightly 與 release workflow 均不得設定人工視覺旗標。
  • OPEN4WD_LOCAL_VISUAL_AUDIT=1 控制完整頁面 inventory、canonical 成功證據與 viewport-only helper 契約；既有 OPEN4WD_RWD_AUDIT_ARTIFACTS=1 只為功能測試附加人工 RWD 圖。只要 CI 存在，兩個旗標都 fail closed 為不收集。
  • 會讀取像素或幾何並形成產品斷言的測試維持自動 CI；不能因底層使用 screenshot API 就移出。
  • Playwright only-on-failure screenshot、失敗 trace 與 error context 維持自動保存；不為人工 artifact 加 retry。

後果與影響

日常與完整平台 CI 不再被純人工 artifact 的 Chromium protocol 偶發錯誤阻擋，同時仍會攔截 黑畫面、透明度、溢位、幾何與功能回歸。維護者需要視覺證據時在本機明確啟用旗標；一次通過 只代表該次人工稽核，不成為後續 candidate 可沿用的產品證據。