4.2 截圖與影片：失敗證據保存#
為什麼要截圖？#
測試在 CI 上失敗了，但你不在現場、看不到畫面。截圖與影片就是失敗的證據——打開圖片就知道當時頁面長什麼樣。
設定檔的預設行為#
// playwright.config.ts
use: {
screenshot: "only-on-failure", // 失敗時自動截圖
video: "retain-on-failure", // 失敗時保留影片
trace: "retain-on-failure", // 失敗時保留 trace
},
失敗的證據會存到 test-results/ 目錄。
screenshot 的選項#
| 值 | 行為 |
|---|---|
"off" | 不截圖（預設） |
"on" | 每個測試都截圖 |
"only-on-failure" | 只在失敗時截圖（最常用） |
手動截圖#
// 頁面截圖
await page.screenshot({ path: "screenshot.png" });
// 只截某個元素
await page.getByRole("form").screenshot({ path: "form.png" });
// 整頁（含捲動範圍）
await page.screenshot({ path: "full.png", fullPage: true });
視覺比對測試（Snapshot Testing）#
驗證「畫面長得跟上次一樣」，適合偵測非預期的 UI 變化：
test("首頁不應該有非預期的視覺變化", async ({ page }) => {
await page.goto("https://my-site.com");
await expect(page).toHaveScreenshot(); // 第一次跑會建立基準圖，之後自動比對
});
基準圖不符時會失敗，並輸出差異圖。更新基準圖：
npx playwright test --update-snapshots
⚠️ 注意：視覺比對測試很敏感（字型渲染不同就會失敗），跨機器比對要設定
maxDiffPixels或用 Docker 統一環境。關鍵元件（如 logo、價格區塊）比對整頁更實用。
錄影的選項#
| 值 | 行為 |
|---|---|
"off" | 不錄影 |
"on" | 每個測試都錄 |
"retain-on-failure" | 失敗才保留影片（最常用） |
分工建議#
| 需求 | 用什麼 |
|---|---|
| CI 失敗後看當時畫面 | screenshot: "only-on-failure" |
| 看操作過程 | video: "retain-on-failure" 或 Trace Viewer |
| 偵測非預期 UI 變化 | toHaveScreenshot() 視覺比對 |
心法：失敗要留證據。CI 上的失敗你看不到畫面，截圖、影片、trace 三選一至少開一個（推薦全開
retain-on-failure）。