playwright-docs

Playwright 測試 (JS/TS) 官方文檔精華

概述

此技能匯集了 Playwright 文檔中容易出錯的內容：自動等待規則、嚴格模式、非預期堆疊的超時、模擬盲點、快照更新模式、CI 設定以及已移除的 API。它排除了通用測試建議。每一項聲明都附有來源文檔的 URL，以便查驗。

涵蓋版本

適用於 Node.js 與 TypeScript 的 Playwright Test 1.64.1 (@playwright/test)。不包含 Python、Java 與 .NET 的內容。如果安裝的版本較舊，請在應用較新的 API 前，先查閱 references/version-changes.md 中的版本對照表。

導覽方式

1. 閱讀下方的快速入門。它涵蓋了大多數測試中重要的規則。
2. 根據任務的領域，從文末的表格中開啟對應的參考文件。
3. 在審查舊程式碼或升級之前，請閱讀下方的「舊模式」一節以及 references/version-changes.md。

快速入門

定位器

• 預設：page.getByRole(role, { name })。其次是 getByLabel、getByText (僅限非互動元素)、getByTestId 作為基於合約的備選方案。只有在沒有任何面向使用者的選擇器可用時，才使用 CSS 或 XPath。 https://playwright.dev/docs/locators#quick-guide
• 定位器是嚴格的：對一個匹配到 2 個元素的定位器執行動作會拋出錯誤。應使用 filter({ hasText })、filter({ has }) 或 inner.within(outer) 來縮小範圍，而非使用 first() / nth()。 https://playwright.dev/docs/locators#strictness
• filter({ has }) 內部的定位器是從外部匹配項進行解析，絕不是從頁面根節點。 https://playwright.dev/docs/locators#filter-by-childdescendant
• 文字匹配預設為區分大小寫的子字串匹配，且總是會正規化空白，即使使用 exact: true 也是如此。 https://playwright.dev/docs/locators#locate-by-text

動作與等待

• 動作會自動等待可操作性。不要在點擊前添加 waitForTimeout 或手動等待載入。 https://playwright.dev/docs/actionability#introduction 及 https://playwright.dev/docs/navigations#when-is-the-page-loaded
• fill() 是輸入文字時的預設方法。pressSequentially() 僅用於需要逐個按鍵處理的情況。 https://playwright.dev/docs/input#type-characters
• 事件 (彈出視窗、下載、檔案選擇器、回應)：在點擊之前建立等待的 Promise，在點擊之後等待它。

  const downloadPromise = page.waitForEvent('download');
  await page.getByText('Download file').click();
  const download = await downloadPromise;
  

  https://playwright.dev/docs/downloads#introduction
• 一個既不定義 accept 也不定義 dismiss 的 dialog 監聽器會導致頁面卡住。如果沒有監聽器，對話框會自動關閉。 https://playwright.dev/docs/dialogs#alert-confirm-prompt-dialogs

斷言

• 總是使用 await expect(locator).toX()。絕對不要使用 expect(await locator.isVisible()).toBe(true)，因為它只檢查一次。 https://playwright.dev/docs/best-practices#use-web-first-assertions
• 斷言超時時間為 5 秒，與 30 秒的測試超時時間是分開的。 https://playwright.dev/docs/test-timeouts
• 沒有匹配的匹配器時，預設使用 expect.poll。expect(...).toPass() 預設沒有超時，所以請務必傳入一個。 https://playwright.dev/docs/test-assertions#expecttopass
• 使用 Playwright 的 expect，而不是 Jest 的。 https://playwright.dev/docs/test-assertions#compatibility-with-expect-library

結構與配置

• Runner 選項放在 defineConfig 的頂層，瀏覽器和上下文選項放在 use 內部。 https://playwright.dev/docs/test-configuration#introduction
• 使用 Fixture 取代 before/after 鉤子對。測試應從 fixture 檔案中引入 test。 https://playwright.dev/docs/test-fixtures#with-fixtures
• beforeAll 每個 worker 執行一次，且每次失敗後 worker 會重啟，因此 beforeAll 可能執行多次。 https://playwright.dev/docs/test-retries#failures
• 在一個帶有 dependencies 的 setup 專案中進行一次登入，等待最終 URL 後儲存 storageState，並將 playwright/.auth 加入 .gitignore。 https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
• 先展開一個裝置設定，然後再覆寫 viewport，因為裝置設定也會定義自己的 viewport。 https://playwright.dev/docs/emulation#viewport
• Playwright 不會進行型別檢查。請在 CI 上執行 tsc --noEmit，並使用 @typescript-eslint/no-floating-promises 進行 lint。 https://playwright.dev/docs/test-typescript#introduction 及 https://playwright.dev/docs/best-practices#lint-your-tests

網路

• 在 page.goto 之前註冊 page.route。Glob 模式必須匹配完整的 URL，而 ? 僅匹配字面意義上的問號。 https://playwright.dev/docs/mock#mock-api-requests 及 https://playwright.dev/docs/network#glob-url-patterns
• 路由會錯過由 Service Worker 提供的請求。請設定 serviceWorkers: 'block'。 https://playwright.dev/docs/network#missing-network-events-and-service-workers
• page.request 與瀏覽器共享 Cookie。request.newContext() 是隔離的，並且必須被釋放。 https://playwright.dev/docs/api-testing#context-request-vs-global-request

CI

• forbidOnly: !!process.env.CI、retries: process.env.CI ? 2 : 0、workers: process.env.CI ? 1 : undefined、trace: 'on-first-retry'，並且總是設定 globalTimeout，否則卡住的執行將不會產生報告。 https://playwright.dev/docs/test-configuration#basic-configuration 及 https://playwright.dev/docs/ci#global-timeout
• 在 npm ci 之後以及每次升級之後，執行 npx playwright install --with-deps。不要快取瀏覽器。 https://playwright.dev/docs/ci#caching-browsers
• 使用 fullyParallel: true 進行分片，並合併 blob 報告。 https://playwright.dev/docs/test-sharding#balancing-shards
• 對共享資源的測試使用鎖來序列化，而不是使用序列模式：test('x', { lock: 'db' }, ...)。 https://playwright.dev/docs/test-parallel#test-locks

快照

• 如果沒有 -u 參數，缺失的快照會被寫入，且測試會失敗。--update-snapshots=missing 會寫入並通過測試。-u 參數代表 changed。 https://playwright.dev/docs/aria-snapshots#updating-snapshots-with-playwrighttest-and-the---update-snapshots-flag
• 螢幕截圖基準線是按瀏覽器和作業系統劃分的。請在進行比較的地方生成它們。 https://playwright.dev/docs/test-snapshots#introduction

舊模式

舊模式	目前模式	來源
locator.type(), page.type()	locator.fill(), 或 pressSequentially()	https://playwright.dev/docs/release-notes#version-138
page.$(), ElementHandle, page.$eval + 通用 expect	定位器 + 優先使用 Web-First 斷言	https://playwright.dev/docs/handles#locator-vs-elementhandle
expect(await locator.isVisible()).toBe(true)	await expect(locator).toBeVisible()	https://playwright.dev/docs/best-practices#dont-use-manual-assertions
:visible 偽類	locator.visible()	https://playwright.dev/docs/release-notes#version-163
text=Log in, id=, data-testid= 選擇器	getByText, getByTestId	https://playwright.dev/docs/other-locators#legacy-text-locator
:right-of(), :near() 佈局選擇器	使用者可見的定位器	https://playwright.dev/docs/other-locators#css-matching-elements-based-on-layout
_react, _vue 選擇器	標準定位器	https://playwright.dev/docs/release-notes#version-158
page.accessibility	@axe-core/playwright	https://playwright.dev/docs/release-notes#version-157
用於登入或資料填充的 globalSetup	帶有 dependencies 的 setup 專案	https://playwright.dev/docs/test-global-setup-teardown#introduction
為共享資源使用 test.describe.configure({ mode: 'serial' })	測試鎖	https://playwright.dev/docs/test-parallel#test-locks
webServer.port	webServer.url	https://playwright.dev/docs/test-webserver#configuring-a-web-server
videosPath, videoSize	recordVideo, 或在 runner 中使用 use.video	https://playwright.dev/docs/release-notes#version-160
devtools: true 啟動選項	args: ['--auto-open-devtools-for-tabs']	https://playwright.dev/docs/release-notes#version-158
-gv 標誌	--grep-invert 或 -G	https://playwright.dev/docs/release-notes#version-154
使用 npx playwright open 錄製	npx playwright codegen	https://playwright.dev/docs/release-notes#version-154
使用 updateSnapshots: 'all' 重新整理已變更的快照	'changed' ('all' 會重寫所有內容)	https://playwright.dev/docs/release-notes#version-150
waitUntil: 'networkidle'	自動等待與 Web-First 斷言	https://playwright.dev/docs/puppeteer#automation-example
使用 JSX mount(<C />) 的 @playwright/experimental-ct-*	來自 @playwright/test 的故事 + mount('Story/Id', props)	https://playwright.dev/docs/test-components#migration-from-the-experimental-packages
由 npm install 下載的瀏覽器	npx playwright install --with-deps	https://playwright.dev/docs/release-notes#version-138

參考文件

檔案	適用於
references/locators.md	定位器優先級、文字匹配、嚴格模式、filter、within、and / or、visible()、Shadow DOM、框架、舊版選擇器
references/actions-and-events.md	每個動作的可操作性檢查、force、輸入、拖放、對話框、下載、上傳、彈出視窗、導航、水合、evaluate、初始化腳本、處理器
references/assertions.md	Web-First 與通用匹配器、斷言超時、expect.poll、toPass、軟斷言、自訂匹配器、test.step
references/snapshots-and-accessibility.md	快照更新模式、ARIA 快照、toHaveScreenshot 容差與命名、非圖片快照、axe 掃描
references/configuration.md	配置結構、use 作用域與預設值、專案與依賴、裝置與模擬、TypeScript 處理、webServer
references/timeouts-retries-annotations.md	每個超時及其預設值、重試與 worker 重啟、序列模式、跳過 / 失敗 / 修正、標籤、參數化測試與專案
references/fixtures-and-auth.md	隔離性、自訂 Fixture、作用域、選項、執行順序、全域鉤子、Setup 專案、頁面物件、storageState 認證、角色、按 Worker 劃分的帳戶
references/network-and-mocking.md	route、Glob 規則、路由無法觸及的標頭與重定向、HAR 記錄與重播、WebSocket 模擬、瀏覽器 API 模擬、Service Worker
references/api-testing-and-clock.md	request Fixture、共享與隔離的 Cookie、釋放上下文、page.clock 方法與順序
references/ci-parallel-sharding.md	CI 基準線、GitHub Actions 與其他供應商、worker、fullyParallel、測試鎖、分片、Blob 報告合併
references/browsers-and-docker.md	瀏覽器安裝與快取、Chromium 頻道、代理與鏡像、Docker 映像、Chrome 擴充功能、WebView2、Selenium Grid
references/debugging-and-reporting.md	CLI 標誌、--debug、檢查器、追蹤與影片模式、追蹤檢視器、UI 模式、報告器
references/component-testing-and-migration.md	故事與圖庫元件測試、從實驗性 ct 套件遷移、Testing Library、Protractor、Puppeteer
references/codegen-and-agent-tooling.md	程式碼生成器、Library 與 Test、發布頻道、測試代理、playwright-cli、Playwright MCP
references/version-changes.md	破壞性行為變更、已移除與棄用的 API 及其替代方案、平台支援變更

來源與擷取細節請見 SOURCES.md。