Playwright Test（JS/TS）公式ドキュメントより
概要
このスキルは、Playwright のドキュメントに記載されている、間違えやすいポイントをまとめたものです。自動待機ルール、strict モード、期待通りに積み重ならないタイムアウト、モックの盲点、スナップショット更新モード、CI 設定、削除された API などが含まれます。一般的なテストアドバイスは除外しています。各主張にはその根拠となるドキュメントの URL が付記されているため、確認が可能です。
対象バージョン
Playwright Test 1.64.1 for Node.js and TypeScript（@playwright/test）。Python、Java、.NET の内容は含みません。インストールされているバージョンが古い場合は、新しい API を適用する前に references/version-changes.md のバージョン表を確認してください。
ナビゲーション方法
- 以下のクイックスタートをお読みください。ほとんどのテストで重要なルールをカバーしています。
- 最後の表から、タスクに該当する参照ファイルを1つ開いてください。
- 古いコードをレビューしたりアップグレードする前に、以下の「古いパターン」と
references/version-changes.mdをお読みください。
クイックスタート
ロケーター
- デフォルト：
page.getByRole(role, { name })。次にgetByLabel、getByText（操作可能でない要素のみ）、getByTestIdをコントラクトベースのフォールバックとして使用。CSS または XPath は、ユーザーから見えるものが何もない場合のみ使用します。 https://playwright.dev/docs/locators#quick-guide - ロケーターは strict です。2つの要素にマッチするロケーターに対するアクションはエラーをスローします。
first()/nth()に頼る代わりに、filter({ hasText })、filter({ has })、またはinner.within(outer)で絞り込んでください。 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 - イベント（popup、download、filechooser、response）：クリックの前に wait の Promise を作成し、クリック後にそれを await します。
const downloadPromise = page.waitForEvent('download'); await page.getByText('Download file').click(); const download = await downloadPromise; - ダイアログリスナーが accept も dismiss もしない場合、ページがハングします。リスナーがない場合、ダイアログは自動的に dismiss されます。 https://playwright.dev/docs/dialogs#alert-confirm-prompt-dialogs
アサーション
- 常に
await expect(locator).toX()を使用します。expect(await locator.isVisible()).toBe(true)は絶対に使わないでください（1回しかチェックしません）。 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
構造と設定
defineConfigのトップレベルにランナーオプション、use内にブラウザとコンテキストのオプションを指定します。 https://playwright.dev/docs/test-configuration#introduction- before/after フックのペアよりもフィクスチャを使用します。テストはフィクスチャファイルから
testをインポートします。 https://playwright.dev/docs/test-fixtures#with-fixtures beforeAllはワーカーごとに1回実行され、ワーカーは失敗ごとに再起動されるため、beforeAllは複数回実行される可能性があります。 https://playwright.dev/docs/test-retries#failuresdependenciesを持つセットアッププロジェクトで一度ログインし、最終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でリントしてください。 https://playwright.dev/docs/test-typescript#introduction および https://playwright.dev/docs/best-practices#lint-your-tests
ネットワーク
page.routeをpage.gotoより前に登録します。グロブは完全なURLにマッチする必要があり、?はリテラルの疑問符にのみマッチします。 https://playwright.dev/docs/mock#mock-api-requests および https://playwright.dev/docs/network#glob-url-patterns- ルートはサービスワーカーが処理したリクエストを見逃します。
serviceWorkers: 'block'を設定してください。 https://playwright.dev/docs/network#missing-network-events-and-service-workers page.requestはブラウザのクッキーを共有します。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-timeoutnpm ciの後、およびアップグレードのたびにnpx playwright install --with-depsを実行します。ブラウザをキャッシュしないでください。 https://playwright.dev/docs/ci#caching-browsersfullyParallel: 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- スクリーンショットのベースラインはブラウザとOSごとに異なります。比較する環境で生成してください。 https://playwright.dev/docs/test-snapshots#introduction
古いパターン
参照ファイル
| ファイル | 読む目的 |
|---|---|
| references/locators.md | ロケーターの優先順位、テキストマッチング、strict モード、filter、within、and/or、visible()、シャドウ DOM、フレーム、レガシーセレクター |
| references/actions-and-events.md | アクションごとの操作可能性チェック、force、入力、ドラッグ＆ドロップ、ダイアログ、ダウンロード、アップロード、ポップアップ、ナビゲーション、ハイドレーション、evaluate、初期化スクリプト、ハンドル |
| references/assertions.md | Web ファースト vs 汎用マッチャー、アサーションタイムアウト、expect.poll、toPass、ソフトアサーション、カスタムマッチャー、test.step |
| references/snapshots-and-accessibility.md | スナップショット更新モード、aria スナップショット、toHaveScreenshot のトレランスと命名、非画像スナップショット、axe スキャン |
| references/configuration.md | 設定構造、use スコープとデフォルト値、プロジェクトと依存関係、デバイスとエミュレーション、TypeScript 処理、webServer |
| references/timeouts-retries-annotations.md | すべてのタイムアウトとそのデフォルト値、リトライとワーカー再起動、シリアルモード、skip/fail/fixme、タグ、パラメータ化テストとプロジェクト |
| references/fixtures-and-auth.md | 分離、カスタムフィクスチャ、スコープ、オプション、実行順序、グローバルフック、セットアッププロジェクト、ページオブジェクト、storageState 認証、ロール、ワーカーごとのアカウント |
| references/network-and-mocking.md | route、グロブルール、ルートが触れないヘッダーとリダイレクト、HAR 記録と再生、WebSocket モック、ブラウザ API モック、サービスワーカー |
| references/api-testing-and-clock.md | request フィクスチャ、共有 vs 分離クッキー、コンテキストの破棄、page.clock メソッドと順序 |
| references/ci-parallel-sharding.md | CI ベースライン、GitHub Actions その他プロバイダー、ワーカー、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 | ストーリーとギャラリーコンポーネントテスト、experimental ct パッケージからの移行、Testing Library、Protractor、Puppeteer |
| references/codegen-and-agent-tooling.md | codegen、Library と Test、リリースチャンネル、Test Agents、playwright-cli、Playwright MCP |
| references/version-changes.md | 破壊的な動作変更、削除および非推奨の API とその代替、プラットフォームサポートの変更 |
出典と取得詳細は SOURCES.md に記載されています。