playwright

Playwright

概要

Playwright は、単一の API で Chromium、Firefox、WebKit をサポートする、Node.js および Python 向けのブラウザー自動化フレームワークです。自動待機、Web ファーストのアサーション、完全なテスト分離を備え、信頼性の高いエンドツーエンドテストを実現します。

使用する場面： ブラウザー自動化、Web スクレイピング、スクリーンショット／PDF の生成、API テスト、Playwright Test の設定、Playwright エラーのトラブルシューティング、ステルスモードとボット対策の回避。

使用しない場面： 単純な HTTP リクエスト（fetch を使用）、ユニットテスト（Vitest/Jest を使用）、大規模なサーバーレススクレイピング（Cloudflare Browser Rendering を検討）。E2E テストのアーキテクチャ（ページオブジェクトモデル、CI のシャーディング、テストの整理、認証パターン）については、e2e-testing スキルを使用してください。

クイックリファレンス

パターン	API / 設定	主なポイント
基本テスト	test('name', async ({ page }) => {})	自動待機、ウェブファーストのアサーション、テストの分離
ロケーター	page.getByRole() / page.locator()	CSS よりもロール／ラベル／テキストのセレクターを優先する
アサーション	expect(locator).toBeVisible()	自動再試行、タイムアウトを設定可能
API テスト	request フィクスチャ / apiRequestContext	HTTP リクエストを送信し、レスポンスを検証する
Aria スナップショット	expect(locator).toMatchAriaSnapshot()	YAML を使用してアクセシビリティツリーの構造を検証する
クラスアサーション	expect(locator).toContainClass('active')	個々の CSS クラス名に一致させる（v1.52+）
表示フィルター	locator.filter({ visible: true })	表示されている要素のみを対象にする（v1.51+）
テストステップ	test.step('name', async (step) => {})	タイムアウト、スキップ、添付ファイル（v1.50+）
ステルスモード	playwright-extra + ステルスプラグイン	20 種類以上の検出方法を回避するパッチを適用する
認証済みセッション	context.cookies() + addCookies()	Cookie と IndexedDB を保存／復元して状態を保持する
スクリーンショット	page.screenshot({ fullPage: true })	先に主要な要素が読み込まれるまで待機する
PDF 生成	page.pdf({ format: 'A4' })	Chromium のみ。printBackground: true を設定する
Clock API	page.clock	テストで時間を停止、早送り、またはシミュレートする
A11y アサーション	toHaveAccessibleName, toHaveRole	axe-core 依存なしでネイティブのアサーションを使用する
ビューポートアサーション	expect(locator).toBeInViewport()	要素が表示ビューポート内にあることを検証する
変更されたテストのみ	--only-changed=$GITHUB_BASE_REF	ベースブランチ以降に変更されたテストファイルのみを実行する
Docker	mcr.microsoft.com/playwright:v1.58.2-noble	--init --ipc=host フラグを使用する
デバッグメソッド	page.consoleMessages() / page.requests() (v1.56+)	イベントリスナーは不要
Speedboard	HTML レポーター (v1.57+)	実行の遅いテストとボトルネックを特定する
Playwright Agents	npx playwright init-agents	LLM 主導のテスト向けのプランナー、ジェネレーター、ヒーラー
不安定なテストの検出	--fail-on-flaky-tests (v1.50+)	CI で不安定なテストがある場合に終了コード 1 を返す
実際のレスポンスを変更する	route.fetch() + route.fulfill()	実際のレスポンスをインターセプトし、JSON を調整して返す
ソフトアサーション	expect.soft(locator)	失敗してもテストを停止せず、最後にすべて報告する
再試行ブロック	expect(async () => {}).toPass()	デフォルトのタイムアウトは 0（無期限）— 必ず設定する
カスタムマッチャー	expect.extend() / mergeExpects()	カスタムアサーションメソッドを定義または結合する
アクション可能性マトリックス	アクションごとの自動待機チェック	click：5 つすべてのチェック、fill：3 つ、focus／blur：なし
テスト修飾子	test.fixme() / test.fail() / test.slow()	fixme＝スキップ＋追跡、fail＝アサーション失敗、slow＝3 倍
並列モード	test.describe.configure({ mode: 'serial' })	describe ブロックごとに serial、parallel、またはデフォルトを指定
ティアダウンプロジェクト	セットアッププロジェクトの teardown オプション	すべての依存先の完了後に自動クリーンアップする

よくある間違い

間違い	正しいパターン
ロールセレクターより CSS セレクターを使う	堅牢性を高めるため、getByRole、getByLabel、getByText を優先します
ブラウザーを閉じない	常に finally ブロックで await browser.close() を実行します
待機に setTimeout を使う	ロケーターの自動待機または waitForLoadState を使います
CI コードに page.pause() を残す	if (!process.env.CI) で囲みます。CI が無期限に停止します
待たずにクリックする	自動待機が組み込まれた locator().click() を使います
テスト間で状態を共有する	フィクスチャを通じて、各テストに新しいコンテキストが割り当てられます
実装の詳細をテストする	DOM 構造ではなく、ユーザーに見える動作を検証します
動的コンテンツに固定の待機時間を設定する	セレクターの出現またはコンテンツの安定化を待ちます
アサーションに await を付け忘れる	すべての expect() アサーションはプロミスを返すため、await が必要です
すべてのスクレイピングで同じユーザーエージェントを使う	大量のスクレイピングではユーザーエージェントをローテーションします
時間に依存するテストで setTimeout を使う	page.clock API を使って時間を停止または早送りします
簡単な a11y チェックに axe-core をインストールする	ネイティブの toHaveAccessibleName／toHaveRole アサーションを使います
明示的なタイムアウトなしで toPass() を使う	常に { timeout: 10_000 } を渡します。デフォルトは 0（無期限）です
サービスワーカーが page.route() を気付かれずにブロックする	MSW を使う場合は、コンテキスト設定で serviceWorkers: 'block' を設定します
オートコンプリート／デバウンス入力に fill() を使う	キー入力ごとに処理するには、必要に応じて遅延を指定し、pressSequentially() を使います
storageState で sessionStorage が失われる	storageState が保存するのは Cookie と localStorage のみです。addInitScript() で sessionStorage を挿入します

委任

• セレクターのトラブルシューティング：Explore エージェントを使います
• テストパターンのレビュー：Task エージェントを使います
• コードレビュー：code-reviewer エージェントに委任します

E2E テストのアーキテクチャ、Page Object Model パターン、CI のシャーディング戦略、認証フロー、ビジュアルリグレッションのワークフロー、またはテストの構成については、e2e-testing スキルを使います。

参考資料

• クイックスタートとインストール
• E2E テストのパターンとアサーション
• セレクター戦略とベストプラクティス
• 設定と Docker のデプロイ
• Docker と CI
• デバッグ方法とパフォーマンス分析
• 一般的な自動化パターン
• ステルスモードとボット対策の回避
• 既知の問題と解決策
• サイト固有のブロックと回避方法
• よくある問題のトラブルシューティング
• ネットワークテスト、モック、API パターン
• 入力パターン、操作可能性、テスト修飾子
• 高度なアサーション、ポーリング、カスタムマッチャー、アノテーション
• 高度なトピック：MCP、AI エージェント、並列コンテキスト