概要
このガイドは、Playwrightを全く知らない状態から、基本的な概念を理解し、実際にテストを書き始められるようになることを目的としています。Webアプリケーションの自動テストが初めての方でも、順を追って学べるように構成されています。
1. Playwrightとは？ 🤖
Playwrightは、Microsoftが開発したモダンなWebアプリケーション向けの自動テストツールです。主な特徴は以下の通りです。
-
クロスブラウザ対応: Chromium (Google Chrome, Edge), Firefox, WebKit (Safari) の主要なブラウザエンジンでテストを実行できます。
-
高速で信頼性が高い: 自動待機機能が組み込まれており、不安定になりがちなテスト（"flaky tests"）を減らします。
-
多機能: E2Eテストだけでなく、スクリーンショット撮影、APIテスト、コンポーネントテストなど、幅広い用途に利用できます。
-
優れた開発者体験: UIモードやデバッグツール、トレースビューアなど、テスト開発を強力にサポートする機能が充実しています。
2. 最初のステップ：環境構築 🛠️
Playwrightのセットアップは非常に簡単です。以下のコマンドを実行するだけで、必要な設定が対話形式で完了します。
# プロジェクトのルートディレクトリで実行
npm init playwright@latest
実行すると、以下のようなファイルやディレクトリが自動で生成されます。
-
playwright.config.ts: Playwrightの動作を定義する設定ファイル。 -
tests/: テストコードを保存するディレクトリ。 -
package.json: 依存関係や実行スクリプトが追記される。 -
tests-examples/: サンプルのテストファイルが含まれる（不要なら削除してOK）。
package.json のスクリプト例
セットアップ後、package.json には便利なスクリプトが追加されます。
{
"scripts": {
"test": "playwright test",
"test:ui": "playwright test --ui",
"test:debug": "playwright test --debug",
"test:report": "playwright show-report"
},
"devDependencies": {
"@playwright/test": "^1.45.0", // バージョンは異なる場合があります
"playwright": "^1.45.0"
}
}
3. テストの実行と確認 🏃
基本的なテストの実行コマンドは以下の通りです。
-
npm run testすべてのテストをヘッドレスモード（ブラウザUIなし）で実行します。CI/CD環境での実行に最適です。
-
npm run test:uiUIモードでテストを起動します。テストのステップを視覚的に確認したり、コードを編集しながらリアルタイムでテストを実行できるため、開発中に非常に便利です。
-
npm run test:debugデバッグモードで実行します。ステップ実行やブラウザコンソールでの確認が可能です。
-
npm run test:report最後に実行したテストの結果をまとめたHTMLレポートを表示します。
4. テストファイルの基本構造 📝
Playwrightのテストは、test関数とexpect関数を組み合わせて記述します。テストコードは AAAパターン (Arrange, Act, Assert) を意識すると分かりやすくなります。
// tests/example.spec.ts
import { test, expect } from '@playwright/test';
test('基本的なページの操作と検証', async ({ page }) => {
// Arrange: 準備（テスト対象のページにアクセス）
await page.goto('https://playwright.dev/');
// Act: 実行（"Get started"リンクをクリック）
await page.getByRole('link', { name: 'Get started' }).click();
// Assert: 検証（ページのタイトルが期待通りか確認）
await expect(page).toHaveTitle(/Installation/);
});
-
test('テスト名', async ({ page }) => { ... }): 個々のテストケースを定義します。pageオブジェクトはブラウザページを操作するためのメインAPIです。 -
async / await: Playwrightの操作はすべて非同期なので、async/awaitが必須です。 -
expect(): アサーション（検証）を行うための関数です。
5. 設計図：設定ファイル (playwright.config.ts) ⚙️
このファイルはPlaywrightプロジェクト全体の「設計図」です。テストの実行方法や環境を細かくカスタマイズできます。
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
// テストファイルが格納されているディレクトリ
testDir: './tests',
// テストを並列実行するかどうか
fullyParallel: true,
// CI環境では失敗したテストを2回リトライ、ローカルではリトライしない
retries: process.env.CI ? 2 : 0,
// レポートの形式。'html', 'json', 'junit' などが指定可能
reporter: 'html',
// 全てのテストで共通して使われる設定
use: {
// ベースURLを設定しておくと page.goto('/') のように相対パスで指定できる
baseURL: 'http://localhost:3000',
// テスト失敗時のトレース設定。'on' 'off' 'on-first-retry' など
trace: 'on-first-retry',
// スクリーンショットの撮影設定。'on' 'off' 'only-on-failure'
screenshot: 'only-on-failure',
},
// テストを実行するブラウザやデバイスの設定
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
},
{
name: 'webkit',
use: { ...devices['Desktop Safari'] },
},
],
// テスト実行前にローカルサーバーを起動する設定
webServer: {
command: 'npm run dev',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
});
6. デバッグは友達：問題解決のヒント 🔍
テストがうまくいかない時は、以下のツールを活用しましょう。
-
UIモード (
npm run test:ui):- テストの各ステップを視覚的に確認しながら実行・編集できます。
- 要素のセレクタを検証したり、アサーションの結果をリアルタイムで確認できるため、テスト作成時の第一の選択肢です。
-
デバッグモード (
npm run test:debug):- コードを一行ずつ実行するステップ実行が可能です。
- 特定の行で処理を止め、ブラウザの状態やコンソールの内容を詳しく調査したい場合に役立ちます。
-
Trace Viewer:
- テストが失敗した際（特にCI環境で）、その実行過程をまるごと記録したファイル（トレース）が生成されます。
- このトレースファイルを開くと、テスト中のDOMスナップショット、アクション、ネットワークリクエストなどを時系列で確認でき、問題の原因究明に非常に強力です。
7. 質の高いテストを書くための原則 ✨
-
単一責任: 1つのテストケースでは、1つのことだけを検証する。
-
独立性: 他のテストの結果に依存しないように作成する。テストはどんな順番で実行されても成功する必要があります。
-
明確なアサーション:
expectを使い、「何が」「どうあるべきか」を明確に検証する。 -
ユーザー視点: テストは技術的な実装ではなく、ユーザーが実際にどのようにアプリケーションを操作するかを模倣するように書く。
getByRoleやgetByTextなどのユーザー向けセレクタを優先的に使いましょう。 -
自動待機を信頼する:
Playwrightは要素が表示されるまで自動で待機します。waitForTimeoutのような固定時間の待機は、テストを不安定にするため避けるべきです。
8. 参考リンク 📚
より詳しい情報は公式サイトで確認できます。