Playwright の使い方 — ブラウザ自動化の決定版ライブラリ

一言でいうと

Playwrightは、Microsoftが開発したブラウザ自動化ライブラリです。Chromium・Firefox・WebKitの3大ブラウザエンジンを単一のAPIで操作でき、E2Eテスト・スクレイピング・UI自動化を高い信頼性で実現します。

どんな時に使う？

• E2Eテスト（End-to-End テスト） — Webアプリケーションのユーザー操作をシミュレートし、画面遷移・フォーム送信・API連携まで含めた統合テストを自動化したいとき
• Webスクレイピング — SPAやJSレンダリングが必要なページからデータを取得したいとき。動的コンテンツの待機処理が組み込まれているため安定して動作する
• スクリーンショット・PDF生成 — Webページのビジュアルリグレッションテストや、HTMLからPDFレポートを生成したいとき

インストール

# npm
npm install playwright

# yarn
yarn add playwright

# pnpm
pnpm add playwright

補足: npm install playwright を実行すると、Chromium・Firefox・WebKitのブラウザバイナリも自動的にダウンロードされます。CI環境などでサイズを抑えたい場合は playwright-core（ブラウザバイナリなし）を使い、必要なブラウザだけ個別にインストールする方法もあります。

# テスト用途なら @playwright/test が推奨
npm install -D @playwright/test

# ブラウザバイナリのインストール（明示的に行う場合）
npx playwright install

基本的な使い方

最もよく使うパターンは「ブラウザを起動 → ページを開く → 操作 → 結果を確認 → ブラウザを閉じる」という流れです。

スクリプトとして使う場合

import { chromium } from 'playwright';

async function main() {
  // ブラウザを起動
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext();
  const page = await context.newPage();

  // ページに遷移
  await page.goto('https://example.com');

  // タイトルを取得
  const title = await page.title();
  console.log(`Page title: ${title}`);

  // スクリーンショットを撮影
  await page.screenshot({ path: 'screenshot.png' });

  // ブラウザを閉じる
  await browser.close();
}

main();

@playwright/test でE2Eテストを書く場合

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

test('トップページのタイトルが正しいこと', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle('Example Domain');
});

test('リンクをクリックして遷移できること', async ({ page }) => {
  await page.goto('https://example.com');
  await page.getByRole('link', { name: 'More information...' }).click();
  await expect(page).toHaveURL(/iana\.org/);
});

# テスト実行
npx playwright test

よく使うAPI — Playwright の主要メソッド

1. page.goto() — ページ遷移

// 基本的な遷移
await page.goto('https://example.com');

// ネットワークがアイドルになるまで待機
await page.goto('https://example.com', {
  waitUntil: 'networkidle',
});

// タイムアウトを指定（ミリ秒）
await page.goto('https://example.com', {
  timeout: 30000,
});

2. page.locator() / page.getByRole() — 要素の取得と操作

Playwrightでは Locator が要素操作の中心です。自動待機（auto-waiting）が組み込まれており、要素が表示されるまで自動的にリトライします。

// CSSセレクタで取得
const button = page.locator('button.submit');
await button.click();

// ロールベースで取得（推奨）
await page.getByRole('button', { name: '送信' }).click();

// テキストで取得
await page.getByText('ログイン').click();

// テスト用IDで取得
await page.getByTestId('login-form').fill('user@example.com');

// プレースホルダーで取得
await page.getByPlaceholder('メールアドレス').fill('user@example.com');

// フォーム入力
await page.getByLabel('ユーザー名').fill('testuser');
await page.getByLabel('パスワード').fill('password123');

3. page.waitForSelector() / page.waitForResponse() — 待機処理

// 要素が表示されるまで待機
await page.waitForSelector('.loading-complete');

// 特定のAPIレスポンスを待機
const responsePromise = page.waitForResponse(
  (response) =>
    response.url().includes('/api/data') && response.status() === 200
);
await page.getByRole('button', { name: '読み込み' }).click();
const response = await responsePromise;
const data = await response.json();
console.log(data);

// URLの変化を待機
await page.waitForURL('**/dashboard');

4. page.screenshot() / page.pdf() — キャプチャ・PDF生成

// ページ全体のスクリーンショット
await page.screenshot({ path: 'full.png', fullPage: true });

// 特定の要素だけキャプチャ
await page.locator('.chart-container').screenshot({ path: 'chart.png' });

// PDF生成（Chromiumのみ）
await page.pdf({
  path: 'report.pdf',
  format: 'A4',
  margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' },
});

5. page.evaluate() — ブラウザ内でJavaScriptを実行

// ブラウザコンテキストでJSを実行
const dimensions = await page.evaluate(() => {
  return {
    width: document.documentElement.clientWidth,
    height: document.documentElement.clientHeight,
    devicePixelRatio: window.devicePixelRatio,
  };
});
console.log(dimensions);

// 引数を渡す
const text = await page.evaluate(
  (selector: string) => {
    const el = document.querySelector(selector);
    return el?.textContent ?? null;
  },
  '.target-element'
);

番外編: route() — ネットワークリクエストのインターセプト

// 特定のAPIをモックする
await page.route('**/api/users', async (route) => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify([
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' },
    ]),
  });
});

// 画像リクエストをブロック（スクレイピング高速化）
await page.route('**/*.{png,jpg,jpeg,gif,svg}', (route) => route.abort());

類似パッケージとの比較

選定の目安: 新規プロジェクトでE2Eテストを導入するなら、Playwrightが現時点で最もバランスの良い選択肢です。Puppeteerからの移行も容易で、APIの設計思想が似ています。

注意点・Tips

1. headless: true がデフォルト

デバッグ時は headless: false にしてブラウザの動作を目視確認しましょう。

const browser = await chromium.launch({
  headless: false,
  slowMo: 500, // 操作間に500msの遅延を入れる（デバッグ用）
});

2. テストのデバッグには --debug フラグが便利

npx playwright test --debug

ステップ実行ができるInspectorが起動します。

3. Codegen でテストコードを自動生成

npx playwright codegen https://example.com

ブラウザ上の操作を記録し、テストコードを自動生成してくれます。初期のテスト作成を大幅に効率化できます。

4. BrowserContext を活用する

BrowserContext はブラウザのシークレットウィンドウに相当します。テストごとにContextを分離することで、Cookie・ストレージ・認証状態が干渉しません。

// 認証状態を保存して再利用
const context = await browser.newContext({
  storageState: 'auth.json', // 事前に保存した認証状態
});

5. CI環境での注意

# CI環境ではシステム依存ライブラリのインストールが必要な場合がある
npx playwright install --with-deps

GitHub Actionsでは公式のDockerイメージ mcr.microsoft.com/playwright:v1.59.1-noble を使うのが最も安定します。

バージョン注記: この記事はPlaywright v1.59.1時点の情報です。APIは安定していますが、新しいバージョンで追加・変更される機能がある場合があります。

6. テストの並列実行とリトライ

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,       // テストを並列実行
  retries: process.env.CI ? 2 : 0, // CIでは2回リトライ
  workers: process.env.CI ? 1 : undefined,
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry', // 失敗時にトレースを記録
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
    { name: 'firefox', use: { browserName: 'firefox' } },
    { name: 'webkit', use: { browserName: 'webkit' } },
  ],
});

まとめ

Playwrightは、マルチブラウザ対応・自動待機・テストランナー内蔵・APIモック・トレースビューアなど、ブラウザ自動化に必要な機能をオールインワンで提供するライブラリです。Puppeteerの設計思想を引き継ぎつつ、テスト体験を大幅に改善しています。E2Eテストの新規導入はもちろん、スクレイピングやPDF生成などの用途でも、2024〜2025年現在で最も信頼性の高い選択肢と言えるでしょう。