最佳實踐

簡介

這個指南應該能幫助您確保您遵循我們的最佳實踐並撰寫更具彈性的測試。

測試理念

測試使用者可見行為

自動化測試應該驗證應用程式程式碼對終端使用者是否有效，並避免依賴實作細節，例如使用者通常不會使用、看到或甚至了解的東西，如函式名稱、某物是否為陣列，或某元素的 CSS 類別。終端使用者會看到或與頁面上呈現的內容互動，所以您的測試通常應該只看到／與相同的呈現輸出互動。

讓測試盡可能獨立

每個測試應該與其他測試完全隔離，並使用自己的本機儲存、Session 儲存、資料、Cookie 等獨立執行。測試隔離可以提高可重現性、讓偵錯更容易，並防止級聯測試失敗。

為了避免測試特定部分的重複，您可以使用前置與後置掛勾。在您的測試檔案中新增前置掛勾，以在每個測試之前執行測試的一部分，例如前往特定 URL 或登入應用程式的一部分。這可保持您的測試隔離，因為沒有測試依賴於另一個測試。不過，當測試足夠簡單時，特別是如果能讓您的測試更清楚且更容易閱讀和維護，有一點重複也是可以的。

import { test } from '@playwright/test';

test.beforeEach(async ({ page }) => {
  // 在每個測試之前執行並在每個頁面上登入。
  await page.goto('https://github.com/login');
  await page.getByLabel('Username or email address').fill('username');
  await page.getByLabel('Password').fill('password');
  await page.getByRole('button', { name: 'Sign in' }).click();
});

test('first', async ({ page }) => {
  // 頁面已登入。
});

test('second', async ({ page }) => {
  // 頁面已登入。
});

您也可以在測試中重複使用已登入狀態的設定專案。這樣您只需要登入一次，然後就可以跳過所有測試的登入步驟。

避免測試第三方相依性

只測試您控制的內容。不要嘗試測試連結到外部網站或您無法控制的第三方伺服器。這不僅耗時且會減慢您的測試速度，而且您也無法控制您連結到的頁面內容，或是否有 Cookie 橫幅或覆蓋頁面或任何其他可能導致測試失敗的東西。

相反地，使用 Playwright Network API 並保證所需的回應。

await page.route('**/api/fetch_data_third_party_dependency', route => route.fulfill({
  status: 200,
  body: testData,
}));
await page.goto('https://example.com');

使用資料庫測試

如果使用資料庫，請確保您控制資料。針對分級環境進行測試，並確保它不會改變。對於視覺回歸測試，請確保作業系統和瀏覽器版本相同。

最佳實踐

使用定位器

為了撰寫端對端測試，我們需要先在網頁上找到元素。我們可以使用 Playwright 內建的定位器來做到這一點。定位器具有自動等待和重試能力。自動等待意味著 Playwright 會對元素執行一系列可操作性檢查，例如確保元素在執行點擊之前是可見且啟用的。為了讓測試具有彈性，我們建議優先使用面向使用者的屬性和明確的契約。

// 👍
page.getByRole('button', { name: 'submit' });

使用鏈接和過濾

定位器可以鏈接以將搜尋範圍縮小到頁面的特定部分。

const product = page.getByRole('listitem').filter({ hasText: 'Product 2' });

您也可以依文字或其他定位器來過濾定位器。

await page
    .getByRole('listitem')
    .filter({ hasText: 'Product 2' })
    .getByRole('button', { name: 'Add to cart' })
    .click();

優先使用面向使用者的屬性而非 XPath 或 CSS 選擇器

您的 DOM 可能容易改變，所以讓您的測試依賴於您的 DOM 結構可能導致測試失敗。例如，考慮透過 CSS 類別選擇這個按鈕。如果設計師改變了一些東西，那麼類別可能會改變，因此會破壞您的測試。

// 👎
page.locator('button.buttonIcon.episode-actions-later');

使用對 DOM 變更具有彈性的定位器。

// 👍
page.getByRole('button', { name: 'submit' });

產生定位器

Playwright 有一個測試產生器，可以為您產生測試並挑選定位器。它會查看您的頁面並找出最佳定位器，優先考慮角色、文字和測試 ID 定位器。如果產生器找到多個符合定位器的元素，它會改進定位器以使其具有彈性並唯一識別目標元素，所以您不必擔心因定位器而導致的測試失敗。

使用 codegen 產生定位器

要挑選定位器，請執行 codegen 指令，後面跟上您想要從中挑選定位器的 URL。

npm

npx playwright codegen playwright.dev

yarn

yarn playwright codegen playwright.dev

pnpm

pnpm exec playwright codegen playwright.dev

這會開啟一個新的瀏覽器視窗以及 Playwright 檢查器。要挑選定位器，請先點擊「Record」按鈕以停止錄製。預設情況下，當您執行 codegen 指令時，它會開始新的錄製。停止錄製後，「Pick Locator」按鈕將可供點擊。

您接著可以在瀏覽器視窗中懸停在頁面上的任何元素上，並看到定位器在游標下方亮起。點擊元素會將定位器新增到 Playwright 檢查器中。您可以複製定位器並貼到測試檔案中，或繼續透過在 Playwright 檢查器中編輯定位器來探索定位器，例如修改文字，並在瀏覽器視窗中查看結果。

使用 VS Code 擴充功能產生定位器

您也可以使用 VS Code 擴充功能來產生定位器以及錄製測試。VS Code 擴充功能在撰寫、執行和偵錯測試時也為您提供絕佳的開發者體驗。

使用 Web 優先斷言

斷言是驗證預期結果和實際結果是否符合的方法。透過使用 Web 優先斷言，Playwright 會等待直到滿足預期條件。例如，在測試警告訊息時，測試會點擊一個讓訊息出現的按鈕，並檢查警告訊息是否存在。如果警告訊息需要半秒鐘才出現，像是 toBeVisible() 的斷言會等待並在需要時重試。

// 👍
await expect(page.getByText('welcome')).toBeVisible();

// 👎
expect(await page.getByText('welcome').isVisible()).toBe(true);

不要使用手動斷言

不要使用未等待 expect 的手動斷言。在下面的程式碼中，await 在 expect 內部而不是在它之前。當使用像是 isVisible() 的斷言時，測試不會等待一秒鐘，它只會檢查定位器是否存在並立即回傳。

// 👎
expect(await page.getByText('welcome').isVisible()).toBe(true);

改為使用像是 toBeVisible() 的 Web 優先斷言。

// 👍
await expect(page.getByText('welcome')).toBeVisible();

設定偵錯

本機偵錯

對於本機偵錯，我們建議您透過安裝 VS Code 擴充功能在 VSCode 中即時偵錯您的測試。您可以透過右鍵點擊您想要執行的測試旁邊的行來以偵錯模式執行測試，這會開啟瀏覽器視窗並在設定中斷點的地方暫停。

您可以透過在 VS Code 中點擊或編輯測試中的定位器來即時偵錯您的測試，這會在瀏覽器視窗中亮起此定位器，並顯示在頁面上找到的任何其他符合的定位器。

您也可以透過使用 --debug 旗標執行測試來使用 Playwright 檢查器偵錯您的測試。

npm

npx playwright test --debug

yarn

yarn playwright test --debug

pnpm

pnpm exec playwright test --debug

您可以逐步執行您的測試、檢視可操作性記錄，並即時編輯定位器，並在瀏覽器視窗中看到它亮起。這會顯示哪些定位器符合，以及有多少個。

要偵錯特定測試，請新增測試檔案名稱和測試的行號，後面跟著 --debug 旗標。

npm

npx playwright test example.spec.ts:9 --debug

yarn

yarn playwright test example.spec.ts:9 --debug

pnpm

pnpm exec playwright test example.spec.ts:9 --debug

在 CI 上偵錯

對於 CI 失敗，使用 Playwright 追蹤檢視器而不是影片和螢幕截圖。追蹤檢視器為您提供測試的完整追蹤，作為一個可以輕易分享的本機漸進式 Web 應用程式 (PWA)。使用追蹤檢視器，您可以檢視時間軸、使用開發工具檢查每個動作的 DOM 快照、檢視網路請求等等。

追蹤在 Playwright 設定檔中設定，並設定為在 CI 上的失敗測試的第一次重試時執行。我們不建議將此設定為 on，以便在每個測試上執行追蹤，因為這會非常耗費效能。不過，您可以在開發時使用 --trace 旗標在本機執行追蹤。

npm

npx playwright test --trace on

yarn

yarn playwright test --trace on

pnpm

pnpm exec playwright test --trace on

一旦您執行此指令，您的追蹤將為每個測試錄製，並可以直接從 HTML 報告中檢視。

npm

npx playwright show-report

yarn

yarn playwright show-report

pnpm

pnpm exec playwright show-report

可以通過點擊測試檔案名稱旁邊的圖標來打開追蹤，或者打開每個測試報告並向下滾動到追蹤部分。

使用 Playwright 的工具

Playwright 提供一系列工具來幫助您撰寫測試。

• VS Code 擴充功能讓您在撰寫、執行和偵錯測試時擁有絕佳的開發者體驗。
• 測試產生器可以為您產生測試並挑選定位器。
• 追蹤檢視器為您提供測試的完整追蹤，作為可以輕易分享的本機 PWA。使用追蹤檢視器，您可以檢視時間軸、檢查每個動作的 DOM 快照、檢視網路請求等等。
• UI 模式讓您以時間旅行的體驗來探索、執行和偵錯測試，並配有觀察模式。所有測試檔案都會載入測試側邊欄，您可以展開每個檔案和描述區塊來單獨執行、查看、觀察和偵錯每個測試。
• Playwright 中的 TypeScript 開箱即用，並為您提供更好的 IDE 整合。您的 IDE 會顯示您可以做的所有事情，並在您做錯事情時醒目提示。不需要 TypeScript 經驗，您的程式碼也不必是 TypeScript，您只需要使用 .ts 副檔名建立測試即可。

跨所有瀏覽器測試

無論您在什麼平台上，Playwright 都能讓您輕鬆跨所有瀏覽器測試您的網站。跨所有瀏覽器測試可確保您的應用程式適用於所有使用者。在您的設定檔案中，您可以設定專案，新增名稱以及要使用的瀏覽器或裝置。

playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
});

保持您的 Playwright 相依性為最新版本

透過保持您的 Playwright 版本為最新，您將能夠在最新的瀏覽器版本上測試您的應用程式，並在最新瀏覽器版本公開發佈之前捕捉失敗。

npm

npm install -D @playwright/test@latest

yarn

yarn add --dev @playwright/test@latest

pnpm

pnpm install --save-dev @playwright/test@latest

查看版本發佈紀錄以了解最新版本以及已發佈的變更。

您可以透過執行以下指令來查看您擁有的 Playwright 版本。

npm

npx playwright --version

yarn

yarn playwright --version

pnpm

pnpm exec playwright --version

在 CI 上執行測試

設定 CI/CD 並經常執行您的測試。您執行測試的頻率越高越好。理想情況下，您應該在每次提交和拉取請求時執行測試。Playwright 配備 GitHub actions workflow，因此測試會在 CI 上為您執行而無需任何設定。Playwright 也可以在您選擇的 CI 環境上設定。

在 CI 上執行測試時使用 Linux，因為它比較便宜。開發者在本機執行時可以使用任何環境，但在 CI 上使用 Linux。考慮設定分片以讓 CI 更快。

在 CI 上最佳化瀏覽器下載

只安裝您實際需要的瀏覽器，特別是在 CI 上。例如，如果您只使用 Chromium 測試，就只安裝 Chromium。

.github/workflows/playwright.yml

# 不要安裝所有瀏覽器
npx playwright install --with-deps

# 只安裝 Chromium
npx playwright install chromium --with-deps

這樣可以節省 CI 機器上的下載時間和磁碟空間。

檢查您的測試

我們建議為您的測試使用 TypeScript 和 ESLint 檢查以提早捕捉錯誤。使用 @typescript-eslint/no-floating-promises ESLint 規則以確保在對 Playwright API 的非同步呼叫之前沒有遺漏 await。在您的 CI 上，您可以執行 tsc --noEmit 以確保函式以正確的簽章呼叫。

使用平行處理和分片

Playwright 預設會平行執行測試。單一檔案中的測試會在相同的 Worker 程序中按順序執行。如果您在單一檔案中有許多獨立測試，您可能會想要平行執行它們

import { test } from '@playwright/test';

test.describe.configure({ mode: 'parallel' });

test('runs in parallel 1', async ({ page }) => { /* ... */ });
test('runs in parallel 2', async ({ page }) => { /* ... */ });

Playwright 可以分片測試套件，以便可以在多台機器上執行。

npm

npx playwright test --shard=1/3

yarn

yarn playwright test --shard=1/3

pnpm

pnpm exec playwright test --shard=1/3

生產力秘訣

使用軟性斷言

如果您的測試失敗，Playwright 會給您一個錯誤訊息，顯示測試的哪個部分失敗，您可以在 VS Code、終端機、HTML 報告或追蹤檢視器中看到。不過，您也可以使用軟性斷言。這些不會立即終止測試執行，而是在測試結束後編譯並顯示失敗斷言的清單。

// 進行一些失敗時不會停止測試的檢查...
await expect.soft(page.getByTestId('status')).toHaveText('Success');

// ... 並繼續測試以檢查更多東西。
await page.getByRole('link', { name: 'next page' }).click();