playwright

🎭 Playwright

ドキュメント | API リファレンス

Playwright は、ウェブの自動化とテストのためのフレームワークです。単一の API を使って Chromium、Firefox、WebKit を操作でき、テストやスクリプト、AI エージェント向けのツールとして利用できます。

はじめに

ワークフローに合った方法を選択してください。

	最適な用途	インストール
Playwright Test	エンドツーエンドテスト	npm init playwright@latest
Playwright CLI	コーディングエージェント（Claude Code、Copilot）	npm i -g @playwright/cli@latest
Playwright MCP	AI エージェントと LLM 駆動の自動化	npx @playwright/mcp@latest
Playwright Library	ブラウザー自動化スクリプト	npm i playwright
VS Code Extension	VS Code でのテスト作成とデバッグ	Marketplace からインストール

---

Playwright Test

Playwright Test は、エンドツーエンドテスト向けに構築された多機能テストランナーです。ブラウザーを完全に分離し、自動待機とウェブ優先のアサーションを備えて、Chromium、Firefox、WebKit でテストを実行します。

インストール

npm init playwright@latest

または、手動で追加します。

npm i -D @playwright/test
npx playwright install

テストを書く

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

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

テストを実行する

npx playwright test

テストは、設定したすべてのブラウザーで並列に実行されます。デフォルトではヘッドレスモードで動作します。各テストには新しいブラウザーコンテキストが割り当てられるため、オーバーヘッドをほぼゼロに抑えながら、完全に分離できます。

主な機能

自動待機とウェブ優先のアサーション。 人工的なタイムアウトは必要ありません。Playwright は要素が操作可能になるまで待機し、条件が満たされるまでアサーションを自動で再試行します。

ロケーター。 ユーザーから見たページに即した、堅牢なロケーターを使って要素を検索できます。

page.getByRole('button', { name: 'Submit' })
page.getByLabel('Email')
page.getByPlaceholder('Search...')
page.getByTestId('login-form')

テストの分離。 各テストは独自のブラウザーコンテキスト（新しいブラウザープロファイルと同等）で実行されます。認証状態を一度保存し、複数のテストで再利用できます。

// Save state after login
await page.context().storageState({ path: 'auth.json' });

// Reuse in other tests
test.use({ storageState: 'auth.json' });

トレース。 失敗時に実行トレース、スクリーンショット、動画を記録します。Trace Viewer では、すべての操作、DOM スナップショット、ネットワークリクエスト、コンソールメッセージを確認できます。

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

npx playwright show-trace trace.zip

並列実行。 デフォルトで、設定したすべてのブラウザーにわたってテストを並列実行します。

テストに関するすべてのドキュメント

---

Playwright CLI

Playwright CLI は、コーディングエージェント向けに設計されたブラウザー自動化用のコマンドラインインターフェイスです。MCP よりもトークン効率に優れており、コマンドで大きなツールスキーマやアクセシビリティツリーをモデルのコンテキストに読み込まずに済みます。

インストール

npm install -g @playwright/cli@latest

より充実したエージェント連携を利用するには、スキルをインストールすることもできます。

playwright-cli install --skills

使い方

コーディングエージェントにタスクを指示します。

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Take screenshots for all successful and failing scenarios.

または、コマンドを直接実行します。

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot

セッションのモニタリング

playwright-cli show を使うと、実行中のすべてのブラウザーセッションをライブのスクリーンキャストプレビューで確認できるビジュアルダッシュボードが開きます。セッションをクリックすると拡大表示でき、リモート操作も行えます。

playwright-cli show

CLI のすべてのドキュメント | GitHub

---

Playwright MCP

Playwright MCP サーバーは、Model Context Protocolを通じて、AI エージェントにブラウザーの完全な制御機能を提供します。エージェントは、構造化されたアクセシビリティスナップショットを使用してページを操作するため、ビジョンモデルやスクリーンショットは必要ありません。

セットアップ

MCP クライアント（VS Code、Cursor、Claude Desktop、Windsurf など）に追加します。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

VS Code 向けワンクリックインストール：

Claude Code 向け：

claude mcp add playwright npx @playwright/mcp@latest

仕組み

AI アシスタントに任意のウェブページを操作するよう依頼します。

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

エージェントには、構造化されたアクセシビリティツリーとしてページが表示されます。

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

e5やe10などの要素参照を使って、クリック、入力、操作を視覚的な曖昧さなく確実に実行します。ツールには、ナビゲーション、フォーム入力、スクリーンショット、ネットワークのモック、ストレージ管理などが含まれます。

MCP ドキュメント全文 | GitHub

---

Playwright Library

playwrightをライブラリとして使い、ブラウザー自動化スクリプトを作成できます。ウェブスクレイピング、PDF 生成、スクリーンショットのキャプチャなど、テストランナーを使わずにプログラムからブラウザーを制御する必要があるワークフローに利用できます。

インストール

npm i playwright

使用例

スクリーンショットを撮影する：

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();

PDF を生成する：

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.pdf({ path: 'page.pdf', format: 'A4' });
await browser.close();

モバイルデバイスをエミュレートする：

import { chromium, devices } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext(devices['iPhone 15']);
const page = await context.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'mobile.png' });
await browser.close();

ネットワークリクエストをインターセプトする：

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
await page.goto('https://playwright.dev/');
await browser.close();

ライブラリのドキュメント | API リファレンス

---

VS Code Extension

Playwright VS Code 拡張機能を使うと、テストの実行、デバッグ、コード生成をエディター内で直接行えます。

エディターからワンクリックでテストを実行およびデバッグできます。ブレークポイントの設定、変数の確認、ライブブラウザービューを使ったテスト実行のステップ実行が可能です。

CodeGen でテストを生成します。「Record new」をクリックしてブラウザーを開きます。アプリ内を移動して操作すると、Playwright がテストコードを自動で作成します。

**ロケーターを選択します。**ブラウザー上の任意の要素にカーソルを合わせると、利用可能な最適なロケーターが表示されます。クリックするとクリップボードにコピーできます。

**Trace Viewer との統合。**サイドバーで「Show Trace Viewer」を有効にすると、各テスト実行後に、DOM スナップショット、ネットワークリクエスト、コンソールログ、各ステップのスクリーンショットを含む実行トレース全体を確認できます。

拡張機能をインストール | VS Code ガイド

---

クロスブラウザーのサポート

	Linux	macOS	Windows
Chromium1 157.0.8103.15	:white_check_mark:	:white_check_mark:	:white_check_mark:
WebKit 27.2	:white_check_mark:	:white_check_mark:	:white_check_mark:
Firefox 158.0	:white_check_mark:	:white_check_mark:	:white_check_mark:

すべてのプラットフォームで、ヘッドレスとヘッドありの実行に対応しています。¹ デフォルトではChrome for Testingを使用します。

その他の言語

Playwright はPython、.NET、Javaでも利用できます。

リソース

• ドキュメント
• API リファレンス
• MCP サーバー
• コーディングエージェント向け CLI
• VS Code 拡張機能
• コントリビューションガイド
• 変更履歴
• Discord