最佳實踐

簡介

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

測試理念

測試使用者可見行為

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

使測試儘可能隔離

每個測試應該完全與其他測試隔離，並且應該使用自己的本地存儲、會話存儲、資料、cookies 等獨立執行。測試隔離 改善了可重現性，使除錯更容易，並防止連鎖測試失敗。

為了避免在測試的特定部分重複，你可以使用前置和後置掛鉤。在你的測試檔案中添加一個前置掛鉤，在每個測試之前執行測試的一部分，例如訪問特定的 URL 或登錄到應用程式的某個部分。這樣可以保持測試的獨立性，因為沒有測試依賴於另一個測試。然而，當測試足夠簡單時，允許有一些重複，特別是如果這樣可以使你的測試更清晰、更易於閱讀和維護。

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

test.beforeEach(async ({ page }) => {
  // Runs before each test and signs in each 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 }) => {
  // page is signed in.
});

test('second', async ({ page }) => {
  // page is signed in.
});

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

避免測試第三方相依套件

只測試你能控制的部分。不要嘗試測試連結到外部網站或第三方伺服器的連結，因為你無法控制它們。不僅耗時且會減慢你的測試速度，你也無法控制你所連結頁面的內容，或者是否有 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 命令，後面跟著您想要選擇定位器的 URL。

npx playwright codegen playwright.dev

這將打開一個新的瀏覽器窗口以及 Playwright inspector。要選擇定位器，首先點擊 'Record' 按鈕以停止錄製。預設情況下，當你執行 codegen 命令時，它將開始新的錄製。一旦你停止錄製，'Pick Locator' 按鈕將可供點擊。

然後，您可以將滑鼠懸停在瀏覽器視窗中的任何頁面元素上，並在游標下方看到定位器突出顯示。點擊元素會將定位器添加到 Playwright inspector 中。您可以複製定位器並貼到您的測試檔案中，或者通過在 Playwright Inspector 中編輯定位器來繼續探索，例如修改文本，並在瀏覽器視窗中查看結果。

使用 VS Code 擴充套件來產生定位器

你也可以使用 VS Code 擴充套件 來產生定位器以及錄製測試。VS Code 擴充套件也讓你在撰寫、執行和偵錯測試時擁有極佳的開發者體驗。

使用 web first 斷言

斷言是一種驗證預期結果和實際結果是否匹配的方法。通過使用 web first 斷言 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() 等網頁優先斷言。

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

設定偵錯

本地除錯

本地偵錯我們建議你通過安裝 VS Code 擴充套件 在 VSCode 中即時偵錯你的測試。你可以通過右鍵點擊你想要執行的測試旁邊的行來在偵錯模式下執行測試，這將打開一個瀏覽器窗口並在設置斷點處暫停。

您可以通過點擊或編輯 VS Code 中測試中的定位器來即時偵錯您的測試，這將在瀏覽器窗口中突出顯示此定位器，並顯示頁面上找到的任何其他匹配定位器。

你也可以使用 Playwright 檢查器來偵錯你的測試，方法是使用 --debug 旗標來執行你的測試。

npx playwright test --debug

然後，您可以逐步執行您的測試，查看可操作性日誌並即時編輯定位器，並在瀏覽器視窗中看到它被突出顯示。這將顯示哪些定位器匹配，以及它們的數量。

要偵錯特定測試，請添加測試檔案的名稱和測試的行號，並加上 --debug 旗標。

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

在 CI 上除錯

對於 CI 失敗，使用 Playwright trace viewer 代替影片和截圖。trace viewer 為您提供測試的完整追蹤，作為一個可以輕鬆共享的本地漸進式 Web 應用程式 (PWA)。使用 trace viewer，您可以查看時間軸，使用開發工具檢查每個動作的 DOM 快照，查看網路請求等。

Playwright 配置檔案中配置了追蹤，並設定在 CI 上第一次重試失敗測試時執行。我們不建議將其設定為 on，以便在每次測試時都執行追蹤，因為這會非常影響效能。然而，你可以在開發時使用 --trace 旗標在本地執行追蹤。

npx playwright test --trace on

一旦你執行此命令，你的追蹤將會為每個測試記錄，並且可以直接從 HTML 報告中查看。

npx playwright show-report

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

使用 Playwright 的工具

Playwright 附帶一系列工具來幫助你撰寫測試。

• VS Code 擴充套件 在撰寫、執行和偵錯測試時為您提供了極佳的開發者體驗。
• 測試產生器 可以為您生成測試並選擇定位器。
• 追蹤檢視器 為您提供測試的完整追蹤，作為本地 PWA，可以輕鬆分享。使用 trace viewer，您可以查看時間軸、檢查每個動作的 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 install -D @playwright/test@latest

查看發行說明以了解最新版本和已發佈的變更。

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

npx playwright --version

在 CI 上執行測試

設定 CI/CD 並經常執行你的測試。你執行測試的次數越多越好。理想情況下，你應該在每次提交和拉取請求時執行測試。Playwright 附帶一個 GitHub actions workflow，因此測試將在 CI 上為你執行，無需設定。Playwright 也可以在你選擇的 CI environment 上設定。

在 CI 上執行測試時使用 Linux，因為它更便宜。開發人員在本地執行時可以使用任何環境，但在 CI 上使用 Linux。考慮設定 Sharding 以加快 CI。

檢查你的測試

我們建議使用 TypeScript 和 ESLint 進行 linting 來早期捕捉錯誤。使用 @typescript-eslint/no-floating-promises ESLint 規則來確保在 Playwright API 的非同步呼叫之前沒有遺漏的 await。在你的 CI 上，你可以執行 tsc --noEmit 來確保函式是用正確的簽名呼叫的。

使用平行處理和分片

Playwright 預設會平行執行測試。單個文件中的測試會按順序在同一個工作程序中執行。如果你在單個文件中有許多獨立的測試，你可能會希望平行執行它們。

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 可以分片測試套件，使其能夠在多台機器上執行。

npx playwright test --shard=1/3

生產力秘訣

使用軟性斷言

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

// Make a few checks that will not stop the test when failed...
await expect.soft(page.getByTestId('status')).toHaveText('Success');

// ... and continue the test to check more things.
await page.getByRole('link', { name: 'next page' }).click();