モダンな Web アプリケーションの開発において、品質の高いテスト環境を整備することは必要不可欠です。特に複数のブラウザでの動作検証や E2E テストの自動化は、開発効率と品質向上に大きく貢献してくれますね。

今回ご紹介する Playwright は、Microsoft 社が開発したテストフレームワークで、2025 年現在も活発に機能拡張が続けられています。この記事では、Playwright の基本的なセットアップから初回テストの作成まで、段階的に詳しく解説していきます。

背景

モダンな Web テストの必要性

現代の Web アプリケーション開発では、様々なブラウザやデバイスでの動作確認が欠かせません。手動でのテストには限界があり、効率的な自動化ツールが求められています。

特に以下のような課題が顕在化してきました。

• 複数ブラウザでの互換性テストの煩雑さ
• **継続的インテグレーション（CI）**での自動テスト実行
• リグレッションテストの効率化
• モバイル環境での動作検証

下図は、モダンな Web アプリケーションにおけるテスト要件の関係性を示しています。

mermaidCopy codeflowchart TD
    webapp["Webアプリケーション"] --> browsers["ブラウザ対応"]
    webapp --> devices["デバイス対応"]
    webapp --> features["機能テスト"]

    browsers --> chrome["Chrome"]
    browsers --> firefox["Firefox"]
    browsers --> safari["Safari"]
    browsers --> edge["Edge"]

    devices --> desktop["デスクトップ"]
    devices --> mobile["モバイル"]
    devices --> tablet["タブレット"]

    features --> unit["ユニットテスト"]
    features --> integration["統合テスト"]
    features --> e2e["E2Eテスト"]

    chrome --> manual["手動テスト"]
    firefox --> manual
    safari --> manual
    edge --> manual

    manual --> time_consuming["時間がかかる"]
    manual --> error_prone["ヒューマンエラー"]
    manual --> not_scalable["スケールしない"]

図で理解できる要点：

• 複数ブラウザ・デバイスでの検証が必須
• 手動テストの限界（時間、エラー、スケーラビリティ）
• 自動化による解決の必要性

Playwright が選ばれる理由

Playwright は、以下の特徴により多くの開発者から支持を得ています。

#	特徴	詳細
1	クロスブラウザ対応	Chrome、Firefox、Safari、Edge をサポート
2	高速実行	並列実行とヘッドレスモードによる高速化
3	リッチな API	直感的で豊富なテスト記述 API
4	デバッグ機能	強力なデバッグツールとトレース機能
5	CI/CD 連携	GitHub Actions、Jenkins 等との連携が容易

特に 2025 年版では、AI 支援によるテスト生成機能や視覚的回帰テストの強化など、より実用的な機能が追加されました。

課題

従来のテストツールの限界

これまでのテストツールには、いくつかの制約がございました。

Selenium の課題：

• ブラウザドライバーの管理が煩雑
• 非同期処理の待機が複雑
• テストの不安定性（flaky テスト）

Puppeteer の課題：

• Chrome のみのサポート
• 他ブラウザでの検証ができない
• TypeScript サポートが限定的

従来ツールの問題点を整理した図：

mermaidCopy codeflowchart LR
    selenium["Selenium"] --> driver_mgmt["ドライバー管理"]
    selenium --> async_complex["非同期処理が複雑"]
    selenium --> flaky["テストが不安定"]

    puppeteer["Puppeteer"] --> chrome_only["Chrome専用"]
    puppeteer --> limited_ts["限定的なTypeScript"]
    puppeteer --> no_cross["クロスブラウザ未対応"]

    driver_mgmt --> maintenance["保守コスト増"]
    async_complex --> dev_time["開発時間増"]
    flaky --> reliability["信頼性低下"]
    chrome_only --> coverage["カバレッジ不足"]

    maintenance --> problems["開発効率の課題"]
    dev_time --> problems
    reliability --> problems
    coverage --> problems

図で理解できる要点：

• 従来ツールの個別課題が開発効率を阻害
• 保守性・信頼性・カバレッジの問題が連鎖
• 統合的な解決策の必要性

クロスブラウザテストの複雑さ

複数ブラウザでのテスト実行には、以下のような困難さがありました。

• 環境構築：各ブラウザのセットアップが個別に必要
• テストコード：ブラウザ固有の差異への対応
• CI 環境：各ブラウザの Docker イメージ管理
• 結果確認：ブラウザごとの結果を統合して確認

これらの課題により、実際にはクロスブラウザテストを諦めるプロジェクトも少なくありませんでした。

解決策

Playwright による統一されたテスト環境

Playwright は、前述の課題を以下のアプローチで解決します。

統一された API による解決：

mermaidCopy codeflowchart TB
    playwright["Playwright"] --> unified_api["統一されたAPI"]

    unified_api --> chrome_test["Chrome テスト"]
    unified_api --> firefox_test["Firefox テスト"]
    unified_api --> safari_test["Safari テスト"]
    unified_api --> edge_test["Edge テスト"]

    chrome_test --> same_code["同じテストコード"]
    firefox_test --> same_code
    safari_test --> same_code
    edge_test --> same_code

    same_code --> auto_wait["自動待機"]
    same_code --> reliable["安定したテスト"]
    same_code --> easy_debug["デバッグ容易"]

    auto_wait --> benefits["開発効率向上"]
    reliable --> benefits
    easy_debug --> benefits

図で理解できる要点：

• 一つの API で全ブラウザに対応
• 同一のテストコードで複数ブラウザを検証
• 自動待機・安定性・デバッグ支援を統合提供

主な解決ポイント：

1. 自動ブラウザ管理：ブラウザの自動ダウンロードとバージョン管理
2. 統一 API：全ブラウザで同じコードが動作
3. スマートウェイト：要素の準備完了を自動検知
4. リッチレポート：視覚的で分かりやすいテスト結果

これにより、開発者はテストロジックに集中でき、インフラの心配をする必要がなくなります。

具体例

環境準備

まず、Playwright を動作させるために必要な環境を整備しましょう。

システム要件の確認：

#	項目	要件
1	Node.js	v18.0 以上（推奨：v20 以上）
2	OS	Windows 10+、macOS 12+、Ubuntu 20.04+
3	メモリ	4GB 以上（推奨：8GB 以上）
4	ディスク容量	2GB 以上の空き容量

Node.js のインストール確認：

Node.js がインストールされているかを確認します。

javascriptCopy code// ターミナルで以下のコマンドを実行
node --version
npm --version

もし Node.js がインストールされていない場合は、公式サイトからダウンロードしてインストールしてください。

プロジェクトディレクトリの作成：

新しいプロジェクト用のディレクトリを作成し、移動します。

javascriptCopy code// プロジェクトディレクトリの作成
mkdir playwright-tutorial
cd playwright-tutorial

// package.jsonの初期化
npm init -y

この初期化により、プロジェクトの基盤となる package.json ファイルが作成されます。

インストール手順

Playwright のインストールは、非常にシンプルです。以下の手順で進めていきましょう。

Playwright のインストール：

Yarn を使用して Playwright をインストールします。

javascriptCopy code// Playwrightの本体をインストール
yarn add -D @playwright/test

// ブラウザの自動ダウンロード
yarn playwright install

このコマンドにより、必要なブラウザ（Chrome、Firefox、Safari、Edge）が自動的にダウンロードされます。約 1-2GB の容量が必要になりますので、しばらくお待ちください。

TypeScript サポートの追加：

TypeScript を使用する場合は、以下も追加でインストールしてください。

javascriptCopy code// TypeScriptとその関連パッケージをインストール
yarn add -D typescript @types/node

// TypeScript設定ファイルの作成
npx tsc --init

インストール確認：

インストールが正常に完了したかを確認します。

javascriptCopy code// Playwrightのバージョン確認
yarn playwright --version

// インストール済みブラウザの確認
yarn playwright install --help

正常にインストールされていれば、バージョン情報が表示されます。

初期設定

Playwright の設定ファイルを作成し、プロジェクトに合わせてカスタマイズしていきます。

設定ファイルの生成：

Playwright には便利な初期化コマンドが用意されています。

javascriptCopy code// 初期化コマンドの実行
yarn playwright init

このコマンドを実行すると、対話式で以下の設定を行えます：

• テストディレクトリの指定
• GitHub Actions ワークフローの生成
• 設定ファイルのカスタマイズ

playwright.config.ts の確認：

生成された設定ファイルを確認してみましょう。

typescriptCopy codeimport { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  // テストディレクトリの指定
  testDir: './tests',

  // 全てのテストでフルページのスクリーンショットを失敗時に取得
  fullyParallel: true,

  // CI環境での設定
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,

  // レポーターの設定
  reporter: 'html',

  // 共通設定
  use: {
    baseURL: 'http://127.0.0.1:3000',
    trace: 'on-first-retry',
  },
});

プロジェクト設定のカスタマイズ：

実際のプロジェクトに合わせて設定を調整します。

typescriptCopy code// プロジェクト固有の設定例
export default defineConfig({
  testDir: './tests',

  // タイムアウトの設定
  timeout: 30 * 1000,
  expect: {
    timeout: 5000,
  },

  // 並列実行の設定
  fullyParallel: true,
  workers: process.env.CI ? 1 : undefined,

  // レポート設定
  reporter: [
    ['html'],
    ['json', { outputFile: 'playwright-report.json' }],
  ],

  use: {
    // ベースURLの設定
    baseURL: 'https://example.com',

    // スクリーンショット設定
    screenshot: 'only-on-failure',

    // ビデオ録画設定
    video: 'retain-on-failure',
  },
});

ブラウザプロジェクトの設定：

複数ブラウザでのテスト実行を設定します。

typescriptCopy codeexport default defineConfig({
  // 既存の設定...

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },

    // モバイルブラウザの設定
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
  ],
});

初回テスト作成

実際にテストケースを作成してみましょう。まずはシンプルなページアクセステストから始めます。

基本的なテストファイルの作成：

tests ディレクトリに最初のテストファイルを作成します。

typescriptCopy code// tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('基本的なページアクセステスト', async ({ page }) => {
  // ページにアクセス
  await page.goto('https://playwright.dev/');

  // ページタイトルの確認
  await expect(page).toHaveTitle(/Playwright/);

  // Get Startedリンクのクリック
  await page
    .getByRole('link', { name: 'Get started' })
    .click();

  // URLの確認
  await expect(page).toHaveURL(/.*intro/);
});

このテストでは、Playwright の公式サイトにアクセスし、基本的な操作を行っています。

フォーム操作のテスト：

より実践的なフォーム入力テストを作成してみましょう。

typescriptCopy code// tests/form.spec.ts
import { test, expect } from '@playwright/test';

test('お問い合わせフォームのテスト', async ({ page }) => {
  // テスト用ページにアクセス
  await page.goto('https://example.com/contact');

  // 名前の入力
  await page.fill('[data-testid="name"]', '山田太郎');

  // メールアドレスの入力
  await page.fill(
    '[data-testid="email"]',
    'yamada@example.com'
  );

  // メッセージの入力
  await page.fill(
    '[data-testid="message"]',
    'テストメッセージです。'
  );

  // 送信ボタンのクリック
  await page.click('[data-testid="submit"]');

  // 完了メッセージの確認
  await expect(
    page.locator('.success-message')
  ).toBeVisible();
  await expect(
    page.locator('.success-message')
  ).toContainText('送信完了');
});

ページナビゲーションのテスト：

複数ページにわたるナビゲーションをテストします。

typescriptCopy code// tests/navigation.spec.ts
import { test, expect } from '@playwright/test';

test('ページナビゲーションのテスト', async ({ page }) => {
  await page.goto('/');

  // ホームページの確認
  await expect(page.locator('h1')).toContainText('ホーム');

  // サービスページへの移動
  await page.click('[href="/services"]');
  await expect(page).toHaveURL('/services');
  await expect(page.locator('h1')).toContainText(
    'サービス'
  );

  // 会社概要ページへの移動
  await page.click('[href="/about"]');
  await expect(page).toHaveURL('/about');
  await expect(page.locator('h1')).toContainText(
    '会社概要'
  );

  // パンくずリストの確認
  await expect(page.locator('.breadcrumb')).toContainText(
    'ホーム > 会社概要'
  );
});

テスト実行とデバッグ

作成したテストを実際に実行し、結果を確認してみましょう。

基本的なテスト実行：

コマンドラインからテストを実行します。

javascriptCopy code// 全てのテストを実行
yarn playwright test

// 特定のテストファイルのみ実行
yarn playwright test tests/example.spec.ts

// 特定のブラウザのみで実行
yarn playwright test --project=chromium

ヘッドフルモードでの実行：

ブラウザの動作を視覚的に確認したい場合は、ヘッドフルモードを使用します。

javascriptCopy code// ブラウザを表示してテスト実行
yarn playwright test --headed

// デバッグモードでの実行
yarn playwright test --debug

デバッグモードでは、ステップバイステップでテストの動作を確認できます。

テスト結果の確認：

テスト実行後、HTML レポートを生成して結果を確認できます。

javascriptCopy code// HTMLレポートの生成と表示
yarn playwright show-report

以下は、テスト実行フローの概要図です：

mermaidCopy codeflowchart TD
    start["テスト開始"] --> config["設定ファイル読み込み"]
    config --> browser["ブラウザ起動"]
    browser --> test_run["テスト実行"]

    test_run --> pass{"テスト結果"}
    pass -->|成功| report_success["成功レポート生成"]
    pass -->|失敗| screenshot["スクリーンショット取得"]

    screenshot --> video["ビデオ録画保存"]
    video --> trace["トレース情報保存"]
    trace --> report_failure["失敗レポート生成"]

    report_success --> cleanup["ブラウザ終了"]
    report_failure --> cleanup
    cleanup --> done["テスト完了"]

図で理解できる要点：

• 設定ファイルに基づいた自動実行
• 失敗時の詳細情報自動収集
• レポート生成の自動化

デバッグのベストプラクティス：

テストが失敗した場合の効果的なデバッグ方法をご紹介します。

typescriptCopy code// デバッグ用の設定追加例
test('デバッグしやすいテスト', async ({ page }) => {
  // ステップごとにスクリーンショットを取得
  await page.goto('/');
  await page.screenshot({ path: 'debug-step1.png' });

  // 要素の存在確認
  const button = page.locator('[data-testid="submit"]');
  await expect(button).toBeVisible();

  // クリック前の状態を保存
  await page.screenshot({ path: 'debug-before-click.png' });
  await button.click();

  // クリック後の状態を保存
  await page.screenshot({ path: 'debug-after-click.png' });
});

まとめ

この記事では、Playwright のセットアップから初回テスト作成までの完全な手順をご紹介しました。

重要なポイントの振り返り：

1. 環境準備：Node.js v18 以上とプロジェクト初期化
2. インストール：yarn add -D @playwright​/​test と yarn playwright install
3. 設定：playwright.config.ts でプロジェクト固有の設定
4. テスト作成：基本的なページアクセスから実践的なフォームテストまで
5. 実行とデバッグ：コマンドライン実行と HTML レポート確認

Playwright を導入することで、以下のメリットを享受できます：

• 開発効率の向上：統一された API による学習コスト削減
• テスト品質の向上：自動待機とスマートセレクターによる安定性
• 保守性の向上：豊富なデバッグ機能と詳細なレポート
• CI/CD 連携：GitHub Actions などとの簡単な統合

2025 年版の Playwright は、AI 支援機能や視覚的回帰テストなど、さらに強力な機能を提供しています。ぜひこの機会に導入を検討してみてください。

次のステップとして、より高度なテストパターンや継続的インテグレーションとの連携なども学習されることをお勧めします。

関連リンク

• Playwright 公式ドキュメント
• Playwright GitHub リポジトリ
• Best Practices | Playwright
• CI with Playwright
• Visual comparisons | Playwright
• TypeScript | Playwright