最佳實務
簡介
本指南旨在協助您確保遵循我們的最佳實務，並編寫更具彈性的測試。
測試哲學
測試使用者可見的行為
自動化測試應驗證應用程式碼是否對終端使用者有效，並避免依賴實作細節，例如使用者通常不會使用、看到或甚至知道的事物，例如函式名稱、某事物是否為陣列，或某些元素的 CSS 類別。終端使用者將看到或與頁面上呈現的內容互動，因此您的測試通常應僅查看/互動相同的呈現輸出。
盡可能隔離測試
每個測試應與另一個測試完全隔離，並且應獨立執行，具有自己的本機儲存、工作階段儲存、資料、Cookie 等。測試隔離 提高了再現性，使偵錯更容易，並防止級聯測試失敗。
為了避免在測試的特定部分重複，您可以使用前置和後置鉤子。在您的測試檔案中，新增一個前置鉤子，在每個測試之前執行測試的某一部分，例如前往特定 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.
});
您也可以使用設定專案在測試中重複使用已登入的狀態。這樣您就可以僅登入一次，然後跳過所有測試的登入步驟。
避免測試第三方依賴項
僅測試您可以控制的內容。請勿嘗試測試指向您無法控制的外部網站或第三方伺服器的連結。這不僅耗時且可能會減慢您的測試速度，而且您也無法控制您連結到的頁面內容，或者是否存在 Cookie 橫幅或覆蓋頁面或任何其他可能導致測試失敗的內容。
相反地，請使用Playwright 網路 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 具有測試產生器，可以為您產生測試並挑選定位器。它將查看您的頁面並找出最佳定位器，優先考慮 role、text 和 test id 定位器。如果產生器找到多個與定位器匹配的元素，它將改進定位器以使其具有彈性並唯一識別目標元素，因此您不必擔心由於定位器而導致測試失敗。
使用 codegen 產生定位器
若要挑選定位器，請執行 codegen 命令，後跟您要從中挑選定位器的 URL。
- npm
- yarn
- pnpm
npx playwright codegen playwright.dev
yarn playwright codegen playwright.dev
pnpm exec playwright codegen playwright.dev
這將開啟一個新的瀏覽器視窗以及 Playwright 檢查器。若要挑選定位器，請先點擊「Record」按鈕以停止錄製。預設情況下，當您執行 codegen 命令時，它將開始新的錄製。停止錄製後，「Pick Locator」按鈕將可供點擊。
然後，您可以將滑鼠懸停在瀏覽器視窗中頁面上的任何元素上，並查看游標下方突出顯示的定位器。點擊元素會將定位器新增到 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
- yarn
- pnpm
npx playwright test --debug
yarn playwright test --debug
pnpm exec playwright test --debug
然後，您可以逐步執行您的測試、檢視可操作性記錄，並即時編輯定位器，並在瀏覽器視窗中看到它突出顯示。這將向您顯示哪些定位器匹配，以及它們有多少個。
若要偵錯特定測試，請新增測試檔案的名稱和測試的行號，後跟 --debug 標誌。
- npm
- yarn
- pnpm
npx playwright test example.spec.ts:9 --debug
yarn playwright test example.spec.ts:9 --debug
pnpm exec playwright test example.spec.ts:9 --debug
在 CI 上偵錯
對於 CI 失敗，請使用 Playwright 追蹤檢視器 而不是影片和螢幕截圖。追蹤檢視器以本機漸進式 Web 應用程式 (PWA) 的形式為您提供測試的完整追蹤，可以輕鬆共用。使用追蹤檢視器，您可以檢視時間軸、使用開發人員工具檢查每個動作的 DOM 快照、檢視網路請求等等。
追蹤在 Playwright 設定檔案中設定，並設定為在失敗測試的第一次重試時執行。我們不建議將其設定為 on，以便在每個測試上執行追蹤，因為它非常耗費效能。但是，您可以在開發時使用 --trace 標誌在本機執行追蹤。
- npm
- yarn
- pnpm
npx playwright test --trace on
yarn playwright test --trace on
pnpm exec playwright test --trace on
一旦您執行此命令，您的追蹤將針對每個測試記錄，並且可以直接從 HTML 報告中檢視。
- npm
- yarn
- pnpm
npx playwright show-report
yarn playwright show-report
pnpm exec playwright show-report
可以透過點擊測試檔案名稱旁邊的圖示或開啟每個測試報告並向下捲動到追蹤區段來開啟追蹤。
使用 Playwright 的工具
Playwright 隨附一系列工具，可協助您編寫測試。
- VS Code 擴充功能在編寫、執行和偵錯測試時為您提供絕佳的開發人員體驗。
- 測試產生器可以為您產生測試並挑選定位器。
- 追蹤檢視器以本機 PWA 的形式為您提供測試的完整追蹤，可以輕鬆共用。使用追蹤檢視器，您可以檢視時間軸、檢查每個動作的 DOM 快照、檢視網路請求等等。
- UI 模式讓您可以探索、執行和偵錯測試，並具有時間旅行體驗，並配備監看模式。所有測試檔案都會載入到測試側邊欄中，您可以在其中展開每個檔案並描述區塊，以個別執行、檢視、監看和偵錯每個測試。
- Playwright 中的 TypeScript 開箱即用，並為您提供更好的 IDE 整合。您的 IDE 將向您顯示您可以執行的所有操作，並在您做錯事時突出顯示。無需 TypeScript 經驗，並且您的程式碼也無需使用 TypeScript，您只需使用
.ts副檔名建立您的測試即可。
跨所有瀏覽器進行測試
無論您在什麼平台上，Playwright 都能輕鬆地跨所有瀏覽器測試您的網站。跨所有瀏覽器進行測試可確保您的應用程式對所有使用者都有效。在您的設定檔案中，您可以設定專案，新增名稱以及要使用的瀏覽器或裝置。
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
- yarn
- pnpm
npm install -D @playwright/test@latest
yarn add --dev @playwright/test@latest
pnpm install --save-dev @playwright/test@latest
查看發行說明以查看最新版本是什麼以及已發佈的變更。
您可以透過執行以下命令來查看您擁有的 Playwright 版本。
- npm
- yarn
- pnpm
npx playwright --version
yarn playwright --version
pnpm exec playwright --version
在 CI 上執行測試
設定 CI/CD 並經常執行您的測試。您執行測試的頻率越高越好。理想情況下，您應該在每次提交和提取請求時執行測試。Playwright 隨附GitHub Actions 工作流程，以便測試將在 CI 上為您執行，無需任何設定。Playwright 也可以在您選擇的 CI 環境中設定。
在 CI 上執行測試時使用 Linux，因為它更便宜。開發人員可以在本機執行時使用任何環境，但在 CI 上使用 Linux。考慮設定分片以加快 CI 速度。
最佳化 CI 上的瀏覽器下載
僅安裝您實際需要的瀏覽器，尤其是在 CI 上。例如，如果您僅使用 Chromium 進行測試，則僅安裝 Chromium。
# Instead of installing all browsers
npx playwright install --with-deps
# Install only Chromium
npx playwright install chromium --with-deps
這可以節省 CI 機器上的下載時間和磁碟空間。
檢查您的測試
我們建議對您的測試使用 TypeScript 和 ESLint 進行檢查，以儘早捕獲錯誤。使用 @typescript-eslint/no-floating-promises ESLint 規則，以確保在對 Playwright API 進行非同步呼叫之前沒有遺失的 awaits。在您的 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 可以分片測試套件，以便可以在多部機器上執行它。
- npm
- yarn
- pnpm
npx playwright test --shard=1/3
yarn playwright test --shard=1/3
pnpm exec 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();