株式会社GENZが運営する技術ブログです。

Playwrightは、Microsoftが開発したモダンなWebアプリケーションのためのエンドツーエンド（E2E）テスト自動化フレームワークです。本記事では、Playwrightの導入方法を基礎から丁寧に解説します。Windows・MacOS両方の環境でのインストール手順、動作確認、そしてよくあるトラブルの対処法まで、実際のコマンドやコード例を交えながら説明していきます。

1. Playwrightとは

主な特徴

Playwrightが選ばれる理由

💰 コスト面での優位性

Playwrightは完全無料のオープンソースツールです。MagicPod（月額数万円〜）やAutify（月額10万円〜）などの有料ツールと比較して、以下のコスト優位性があります：

• 初期費用ゼロ: ライセンス費用や導入費用が一切不要
• ランニングコスト不要: テスト実行回数による従量課金なし
• スケーラブル: チーム規模に関わらず追加コスト不要
• 自社インフラで完結: クラウドサービスへの依存なし

🎨 圧倒的な自由度とカスタマイズ性

有料のノーコード/ローコードツールと異なり、プログラミングによる柔軟な制御が可能です：

• 複雑なシナリオに対応: 条件分岐、ループ、データ駆動テストなど自由に実装
• 既存システムとの統合: API連携、データベース接続など自由に組み込み可能
• カスタムフレームワーク構築: プロジェクト固有のテストフレームワークを構築可能
• 拡張性: 独自のヘルパー関数やプラグインを追加できる

🛡️ Microsoftによる信頼性とサポート

Playwrightは大手IT企業Microsoftが開発・保守しており、高い信頼性があります：

• 継続的なアップデート: 月次で新機能追加とバグ修正が行われる
• 充実したドキュメント: 公式ドキュメントが詳細で分かりやすい
• 大規模コミュニティ: GitHub Starが6万以上、活発な開発とサポート
• 企業利用の実績: Microsoft、Bing、VS Codeなど自社製品で採用

⚙️ 有料ツールとの比較優位性

MagicPodやAutifyなどのSaaS型テストツールと比較した場合の利点：

• プライバシーとセキュリティ: テストデータが外部サービスに送信されない
• ベンダーロックインの回避: 特定サービスへの依存がなく、いつでも移行可能
• 技術スキルの蓄積: プログラミング能力がチーム内に蓄積される
• 実行環境の制御: ローカル、クラウド、オンプレミスなど自由に選択可能
• 高度な制御: ネットワーク制御、認証処理、並列実行など細かく調整可能

🔍 その他の技術的優位性

• 自動待機機能: 要素が表示されるまで自動的に待機するため、明示的な待機コードが不要
• 強力なセレクタエンジン: CSS、XPath、テキスト、ARIA属性など多様な方法で要素を選択可能
• ネットワーク制御: APIリクエストのモックやインターセプトが容易
• スクリーンショット・動画録画: テスト実行時の様子を自動で記録
• TypeScript完全サポート: 型安全なテストコード作成が可能

他のテストツールとの比較

2. Playwright導入について

必要な環境

Playwrightを導入するには、以下の環境が必要です：

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

まず、Node.jsがインストールされているか確認します。以下のコマンドをターミナル（Windows: コマンドプロンプトまたはPowerShell）で実行してください：

バージョン番号（例: v18.17.0）が表示されればOKです。表示されない場合は、Node.js公式サイトからインストールしてください。

プロジェクトの準備

Playwrightをインストールする前に、テスト用のプロジェクトディレクトリを作成します：

# プロジェクトディレクトリを作成
mkdir playwright-demo
cd playwright-demo

# package.jsonを作成（npmプロジェクトの初期化）
npm init -y

これで、Playwrightをインストールする準備が整いました。

3. Windowsでのインストール方法

Windowsでは、コマンドプロンプト、PowerShell、またはWindows Terminalを使用してインストールを進めます。

? Do you want to use TypeScript or JavaScript?
  → TypeScript（推奨）またはJavaScriptを選択

? Where to put your end-to-end tests?

  → tests（デフォルトでEnter）

? Add a GitHub Actions workflow?

  → Yes（CI/CD統合したい場合）/No

? Install Playwright browsers (can be done manually via 'npx playwright install')? 
  → Yes（必ずYesを選択）

✔ Success! Created a Playwright Test project

Inside that directory, you can run several commands:

  npx playwright test
    Runs the end-to-end tests.

  npx playwright test --ui
    Starts the interactive UI mode.

Happy hacking! 🎭

4. macOSでのインストール方法

macOSでは、ターミナルアプリケーションを使用してインストールを進めます。

? Do you want to use TypeScript or JavaScript? 
  → TypeScript（推奨）またはJavaScriptを選択

? Where to put your end-to-end tests? 
  → tests（デフォルトでEnter）

? Add a GitHub Actions workflow? 
  → Yes（CI/CD統合したい場合）/No

? Install Playwright browsers (can be done manually via 'npx playwright install')? 
  → Yes（必ずYesを選択）

5. 導入後の動作確認

インストールが完了したら、Playwrightが正しく動作するか確認しましょう。

ステップ1: サンプルテストの実行

Playwrightには、インストール時にサンプルテストが自動生成されます。まずはこれを実行してみましょう：

このコマンドを実行すると、以下のようなことが起こります：

• すべてのテストファイル（tests/ディレクトリ内）が実行される
• デフォルトではヘッドレスモード（ブラウザが表示されない）で実行
• Chromium、Firefox、WebKitの3つのブラウザでテストが実行される
• テスト結果がターミナルに表示される

Running 6 tests using 3 workers

  ✓  [chromium] › example.spec.ts:3:1 › has title (1s)
  ✓  [chromium] › example.spec.ts:8:1 › get started link (1s)
  ✓  [firefox] › example.spec.ts:3:1 › has title (2s)
  ✓  [firefox] › example.spec.ts:8:1 › get started link (2s)
  ✓  [webkit] › example.spec.ts:3:1 › has title (1s)
  ✓  [webkit] › example.spec.ts:8:1 › get started link (2s)

  6 passed (9s)

ステップ2: UIモードでの実行

Playwrightには、テストを視覚的に確認できるUIモードがあります。これを使うと、テストの実行状況をリアルタイムで確認できます：

このコマンドを実行すると、ブラウザが開き、以下のような画面が表示されます：

UIモードでは以下のことができます：

• 個別のテストを選択して実行
• テストの実行速度を調整
• 各ステップでのブラウザの状態を確認
• 失敗したテストのスクリーンショットを確認
• DOM要素の検査とセレクタの確認

ステップ3: ヘッド付きモードでの実行

ブラウザを実際に表示させて、テストの実行を目で確認することもできます：

このコマンドを実行すると、ブラウザウィンドウが開き、テストが自動的に実行される様子を見ることができます。

ステップ4: 特定のブラウザでの実行

特定のブラウザだけでテストを実行したい場合：

# Chromiumのみ
npx playwright test --project=chromium

# Firefoxのみ
npx playwright test --project=firefox

# WebKitのみ
npx playwright test --project=webkit

ステップ5: レポートの確認

テスト実行後、詳細なHTMLレポートを生成して確認できます：

ブラウザが開き、以下の情報を含む詳細なレポートが表示されます：

• 各テストの成功/失敗状況
• 実行時間
• スクリーンショット（失敗時）
• エラーメッセージとスタックトレース
• ブラウザごとの結果

ステップ6: 簡単なテストを作成して実行

動作確認の最後に、簡単なテストを自分で作成してみましょう。tests/my-first-test.spec.tsというファイルを作成し、以下のコードを記述します：

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

test('Google検索ページが表示される', async ({ page }) => {
  // Googleのトップページにアクセス
  await page.goto('https://www.google.com');
  
  // ページタイトルに「Google」が含まれることを確認
  await expect(page).toHaveTitle(/Google/);
  
  // 検索ボックスが表示されていることを確認
  const searchBox = page.locator('textarea[name="q"]');
  await expect(searchBox).toBeVisible();
  
  console.log('✅ テスト成功！');
});

このテストを実行します：

便利なコマンド一覧

6. トラブルシューティング

インストールや動作確認時によく発生する問題と、その解決方法をまとめました。

インストール時のトラブル

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bash_profile
source ~/.bash_profile

# 環境変数を設定
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
npx playwright install

# node_modulesを削除して再インストール
rm -rf node_modules package-lock.json
npm install
npm install -D @playwright/test

実行時のトラブル

import { defineConfig } from '@playwright/test';

export default defineConfig({
  timeout: 60000, // 60秒に延長
  expect: {
    timeout: 10000, // アサーションのタイムアウトも延長
  },
});

test('長時間かかるテスト', async ({ page }) => {
  test.setTimeout(120000); // このテストだけ120秒
  // テストコード
});

# Windows
rd /s /q %USERPROFILE%\AppData\Local\ms-playwright

# macOS/Linux
rm -rf ~/Library/Caches/ms-playwright

# その後再インストール
npx playwright install

Windows特有のトラブル

# 管理者権限でPowerShellを開き、以下を実行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS特有のトラブル

一般的なデバッグ方法

まとめ

本記事では、Playwrightの導入からインストール、動作確認、そしてトラブルシューティングまで詳しく解説しました。

重要ポイントの再確認

• Playwrightとは: Microsoftが開発した、クロスブラウザ対応のE2Eテスト自動化フレームワーク
• 必要な環境: Node.js 16以上、約1GBのディスク空間
• インストールコマンド: npm init playwright@latestで簡単にセットアップ可能
• 動作確認: npx playwright testでサンプルテストを実行
• UIモード: npx playwright test --uiで視覚的にテストを確認

Playwrightは強力でありながら、比較的学習コストの低いツールです。本記事で紹介した基本的な使い方を押さえれば、すぐに実践的なE2Eテストの作成を始められます。

問題が発生した場合は、本記事のトラブルシューティングセクションを参照してください。それでも解決しない場合は、Playwright GitHub Issuesで同様の問題が報告されていないか確認するか、質問を投稿してください。

これからPlaywrightを使って、高品質なWebアプリケーションの開発を実現していきましょう！

＜過去の記事＞
単体テスト完全ガイド｜ソフトウェア品質の基盤を築く最重要プラクティス
アジャイル開発でのテスト品質向上法｜テスト自動化とベンダー活用の実例付き
開発会社様向け！失敗しない初めてのテストアウトソーシングのすすめ
結合テストITaとITbの違いとその重要性
ソフトウェアテストにおける「真の受入テスト」とは