Skip to main content

視覺比較

介紹​

Playwright Test 包含使用 await expect(page).toHaveScreenshot() 產生和視覺比較螢幕截圖的能力。在第一次執行時，Playwright Test 將產生參考螢幕截圖。後續執行將與參考比較。

example.spec.ts
import { test, expect } from '@playwright/test';

test('example test', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await expect(page).toHaveScreenshot();
});
warning

瀏覽器渲染可能因主機 OS、版本、設定、硬體、電源來源（電池 vs. 電源適配器）、無頭模式和其他因素而異。為了獲得一致的螢幕截圖，請在產生基準螢幕截圖的相同環境中執行測試。

產生螢幕截圖​

當您第一次執行上述程式時，測試執行器會說：

Error: A snapshot doesn't exist at example.spec.ts-snapshots/example-test-1-chromium-darwin.png, writing actual.

那是因為還沒有黃金檔案。此方法拍攝了多張螢幕截圖，直到兩張連續螢幕截圖匹配，並將最後一張螢幕截圖儲存到檔案系統。現在它已準備好新增到儲存庫。

黃金期望資料夾的名稱以您的測試檔案名稱開頭：

drwxr-xr-x  5 user  group  160 Jun  4 11:46 .
drwxr-xr-x  6 user  group  192 Jun  4 11:45 ..
-rw-r--r--  1 user  group  231 Jun  4 11:16 example.spec.ts
drwxr-xr-x  3 user  group   96 Jun  4 11:46 example.spec.ts-snapshots

快照名稱 example-test-1-chromium-darwin.png 由幾個部分組成：

  • example-test-1.png - 快照的自動產生名稱。或者，您可以將快照名稱指定為 toHaveScreenshot() 方法的第一個參數：

    await expect(page).toHaveScreenshot('landing.png');

  • chromium-darwin - 瀏覽器名稱和平台。由於不同的渲染、字體等，螢幕截圖在瀏覽器和平台之間不同，因此您需要為它們準備不同的快照。如果您在 設定檔案 中使用多個專案，則會使用專案名稱而不是 chromium。

快照名稱和路徑可以使用 Playwright 設定中的 testConfig.snapshotPathTemplate 來設定。

注意，toHaveScreenshot() 也接受快照檔案的路徑段陣列，例如 expect().toHaveScreenshot(['relative', 'path', 'to', 'snapshot.png'])。 但是，此路徑必須留在每個測試檔案的快照目錄內（即 a.spec.js-snapshots），否則會拋出錯誤。

更新螢幕截圖​

有時您需要更新參考螢幕截圖，例如當頁面發生變化時。使用 --update-snapshots 旗標來執行此操作。

npx playwright test --update-snapshots

選項​

maxDiffPixels​

Playwright Test 使用 pixelmatch 程式庫。您可以 傳遞各種選項 來修改其行為：

example.spec.ts
import { test, expect } from '@playwright/test';

test('example test', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await expect(page).toHaveScreenshot({ maxDiffPixels: 100 });
});

如果您想在專案中的所有測試之間共享預設值，您可以在 Playwright 設定中指定它，全域或每個專案：

playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
  expect: {
    toHaveScreenshot: { maxDiffPixels: 100 },
  },
});

stylePath​

您可以在拍攝螢幕截圖時將自訂樣式表應用到您的頁面。這允許過濾動態或易變元素，從而改善螢幕截圖的確定性。

screenshot.css
iframe {
  visibility: hidden;
}
example.spec.ts
import { test, expect } from '@playwright/test';

test('example test', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await expect(page).toHaveScreenshot({ stylePath: path.join(__dirname, 'screenshot.css') });
});

如果您想在專案中的所有測試之間共享預設值，您可以在 Playwright 設定中指定它，全域或每個專案：

playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
  expect: {
    toHaveScreenshot: {
      stylePath: './screenshot.css'
    },
  },
});

非影像快照​

除了螢幕截圖，您可以使用 expect(value).toMatchSnapshot(snapshotName) 來比較文字或任意二進位資料。Playwright Test 自動檢測內容類型並使用適當的比較演算法。

這裡我們比較文字內容與參考。

example.spec.ts
import { test, expect } from '@playwright/test';

test('example test', async ({ page }) => {
  await page.goto('https://playwright.dev');
  expect(await page.textContent('.hero__title')).toMatchSnapshot('hero.txt');
});

快照儲存在測試檔案旁邊，在單獨的目錄中。例如，my.spec.ts 檔案將產生並儲存快照在 my.spec.ts-snapshots 目錄中。您應該將此目錄提交到您的版本控制（例如 git），並檢視對其的任何變更。