playwright-e2e-testing

Playwright E2E Testing（TypeScript）

TypeScript を使用して Playwright で Web アプリケーションのエンドツーエンドテストを行うための包括的なツールキットです。ベストプラクティスに従い、堅牢な UI テスト、UI に依存する API のセットアップ、レスポンシブデザインの検証を実現します。

有効化： バージョン管理された Playwright UI 仕様とそのテストインフラストラクチャを作成または保守する際に、このスキルが起動します。

このスキルを使用する場面

• ユーザーフロー、フォーム、ナビゲーション、認証の E2E テストを作成する
• request フィクスチャまたはネットワークインターセプトを使用して UI に依存する API をセットアップする
• モバイル、タブレット、デスクトップのビューポートで レスポンシブテストを行う
• トレース、スクリーンショット、動画、Playwright Inspector を使用して 不安定なテストをデバッグする
• Page Object Model とフィクスチャを使用して テストインフラストラクチャをセットアップする
• 分離された決定論的なテストのために API をモック／インターセプトする
• スクリーンショット比較を使用して ビジュアルリグレッションテストを行う

使用しない場面

• ブラウザーを使用しない単独の API／コントラクトテスト（api-testing を使用してください）。
• 探索やデバッグのためにライブブラウザーを対話的に操作する場合（playwright-cli を使用してください）。
• 大規模なリグレッションテストスイート、ティア、CI のシャーディング戦略を管理する場合（playwright-regression-testing を使用してください）。
• Selenium／Java によるブラウザー自動化（webapp-selenium-testing を使用してください）。

前提条件

要件	詳細
Node.js	v18+ を推奨
パッケージマネージャー	npm、yarn、または pnpm
Playwright	@playwright/test パッケージ
TypeScript	typescript + ts-node（任意ですが推奨）
ブラウザー	npx playwright install でインストール

クイックセットアップ

# Initialize new project
npm init playwright@latest

# Or add to existing project
npm install -D @playwright/test
npx playwright install

最初に確認すること

テストを作成する前に、以下を確認してください。

1. アプリの URL：ローカル開発サーバーのコマンドとポート、またはステージング URL はどれですか？
2. 重要なフロー：どのユーザージャーニーを対象にする必要がありますか（正常系とエラー状態）？
3. ブラウザー／デバイス：Chrome、Firefox、Safari のどれですか？モバイルのビューポートも対象ですか？
4. API 戦略：実際のバックエンド、モックレスポンス、またはハイブリッド方式のどれですか？
5. テストデータ：シードデータは利用できますか？リセット／クリーンアップの戦略はありますか？

---

基本原則

1. テストランナーと TypeScript

型安全性と IDE のサポート向上のため、常に TypeScript で @playwright/test を使用してください。

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

test("user can login", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill("[email protected]");
  await page.getByLabel("Password").fill("password123");
  await page.getByRole("button", { name: "Sign in" }).click();
  await expect(page).toHaveURL(/.*dashboard/);
});

2. ロケーター戦略（優先順位）

アクセシブルな名前を指定したロールベースのロケーター（getByRole）を優先し、次にラベル → プレースホルダー → テキスト → テスト ID → CSS（最後の手段）の順で使用してください。XPath は使用しません。

➡️ 優先順位の全体像、ロールのリファレンス、使用例： ロケーター戦略：優先順位 — 唯一の信頼できる情報源です。

3. 自動待機と Web ファーストアサーション

Playwright は要素を自動的に待機します。sleep() や任意のタイムアウトは使用しないでください。

// [ok] Web-first assertions (auto-retry)
await expect(page.getByRole("alert")).toBeVisible();
await expect(page).toHaveURL(/dashboard/);
await expect(page.getByTestId("status")).toHaveText("Success!");

// [no] Avoid manual waits
await page.waitForTimeout(2000); // Bad practice

4. ステップを使ったテスト構成

読みやすいレポートと失敗箇所の特定のために test.step() を使用してください。

test("checkout flow", async ({ page }) => {
  await test.step("Add item to cart", async () => {
    await page.goto("/products/1");
    await page.getByRole("button", { name: "Add to Cart" }).click();
  });

  await test.step("Complete checkout", async () => {
    await page.goto("/checkout");
    await page.getByRole("button", { name: "Pay Now" }).click();
  });

  await test.step("Verify confirmation", async () => {
    await expect(page.getByRole("heading")).toContainText("Order Confirmed");
  });
});

---

主なワークフロー

フォームとナビゲーション

// Form submit and wait for navigation (auto-waiting)
await page.getByRole("button", { name: "Login" }).click();
await expect(page).toHaveURL(/.*dashboard/);

// Form with API response validation
const responsePromise = page.waitForResponse(
  (r) => r.url().includes("/api/login") && r.status() === 200,
);
await page.getByRole("button", { name: "Login" }).click();
const response = await responsePromise;

API テスト（Request フィクスチャ）

test("API health check", async ({ request }) => {
  const response = await request.get("/api/health");
  expect(response.ok()).toBeTruthy();
  expect(await response.json()).toMatchObject({ status: "ok" });
});

API のモックとインターセプト

test("handles API error", async ({ page }) => {
  await page.route("**/api/users", (route) =>
    route.fulfill({
      status: 500,
      body: JSON.stringify({ error: "Server error" }),
    }),
  );
  await page.goto("/users");
  await expect(page.getByRole("alert")).toContainText("Something went wrong");
});

レスポンシブテスト

const viewports = [
  { width: 375, height: 667, name: "mobile" },
  { width: 768, height: 1024, name: "tablet" },
  { width: 1280, height: 720, name: "desktop" },
];

for (const vp of viewports) {
  test(`navigation works on ${vp.name}`, async ({ page }) => {
    await page.setViewportSize(vp);
    await page.goto("/");
    // Mobile: hamburger menu
    if (vp.width < 768) {
      await page.getByRole("button", { name: /menu/i }).click();
    }
    await page.getByRole("link", { name: "About" }).click();
    await expect(page).toHaveURL(/about/);
  });
}

---

設定

プロジェクト全体の設定には playwright.config.ts を使用してください。

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  retries: process.env.CI ? 2 : 0,
  reporter: [["html"], ["junit", { outputFile: "results.xml" }]],
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
  },
  projects: [
    { name: "chromium", use: devices["Desktop Chrome"] },
    { name: "mobile", use: devices["Pixel 5"] },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
});

---

トラブルシューティング

問題	原因	解決策
要素が見つからない	ロケーターが誤っている、またはレンダリングされていない	PWDEBUG=1 で調査し、getByRole で確認する
待機がタイムアウトする	要素が非表示、または読み込みが遅い	オーバーレイを確認し、タイムアウトを延長して、waitFor() を使う
テストが不安定	競合状態、アニメーション	test.step() を追加し、適切な待機を使って、アニメーションを無効にする
Strict モード違反	複数の要素が一致する	.first()、.filter()、またはより具体的なロケーターを使う
スクリーンショットが異なる	動的なコンテンツ	動的な領域をマスクし、決定的なデータを使う
CI では失敗し、ローカルでは成功する	環境の違い	baseURL、タイムアウト、webServer の設定を確認する
API モックが機能しない	ルートパターンの不一致	**/api/... グロブを使い、page.on('request') で確認する

---

CLI クイックリファレンス

コマンド	説明
npx playwright test	すべてのテストをヘッドレスで実行
npx playwright test --ui	UI モードを開く（対話型）
npx playwright test --headed	ブラウザーを表示して実行
npx playwright test --debug	Playwright Inspector を起動して実行
npx playwright test -g "login"	パターンに一致するテストを実行
npx playwright test --project=chromium	特定のプロジェクトを実行
npx playwright show-report	HTML レポートを開く
npx playwright codegen	記録してテストを生成する
PWDEBUG=1 npx playwright test	Inspector でデバッグする
DEBUG=pw:api npx playwright test	API の詳細なログを出力する

---

要注意事項

• ロール／ラベル／testId が利用できるのに CSS／XPath ロケーターを使うこと。壊れやすく、リファクタリングで動かなくなります。
• Web ファーストの自動再試行アサーションの代わりに、waitForTimeout や手動のスリープを使うこと。
• テスト間で状態を共有し、実行順序に依存すること。不安定になり、実行順序に結びついてしまいます。
• 表示状態を確認せず、ステータス／URL だけをアサーションすること。レンダリングのリグレッションが見逃されます。
• フィクスチャを使わず、各テストでページのセットアップをインラインで繰り返すこと。重複や不整合が生じます。

---

参考資料

ドキュメント	内容
スニペット：セットアップ	設定、認証セットアップ、カスタムフィクスチャ、ログ記録
スニペット：インタラクション	フォーム操作、API テスト、ネットワークのインターセプト
スニペット：ビューポートと認証	レスポンシブなビューポートと認証パターン
スニペット：アサーションとデバッグ	アサーション、デバッグコマンド、ユーティリティヘルパー
ロケーター戦略：優先順位	ロケーターの優先順位とロールベースのロケーター
ロケーター戦略：テキスト	ラベル、テキスト、プレースホルダー、代替テキスト、テスト ID のロケーター
ロケーター戦略：フィルタリング	フィルタリング、チェーン、複雑なロケーターパターン
ロケーター戦略：アンチパターンとデバッグ	アンチパターン、最終手段としての CSS、デバッグ、クイックリファレンス
POM：基本	POM の概念、ディレクトリ構造、ベースページ、フルーエント API
POM：コンポーネント	ページオブジェクトと再利用可能なコンポーネントオブジェクトの実装
POM：フィクスチャ	カスタムおよび認証済みページオブジェクトフィクスチャ
POM：プラクティス	ベストプラクティス、アンチパターン、完全な実例
デバッグ：ツールと UI	デバッグツール、UI モード、Inspector、ヘッド付きモード
デバッグ：トレースとログ	トレースビューア、詳細ログ、スクリーンショット、動画
デバッグ：エラーとネットワーク	コンソール／ページエラーとネットワークのデバッグ
デバッグ：不安定なテストとロケーター	不安定なテストの修正、ロケーターのデバッグ、クイックコマンド

---

検証

• カスタムフィクスチャの注入を使用している — spec ファイル内に new PageObject() の呼び出しがなく、すべての POM がフィクスチャ経由で注入されている
• ロケーターが推奨される戦略を使用している — すべてのロケーターが getByRole()、getByTestId()、または getByText() を使用し、操作可能な要素に CSS セレクターを使用していない
• テストが独立している — 各テストが独自の状態をセットアップおよびティアダウンし、共有された変更可能な状態を伴う beforeAll を使用していない
• エラー状態を網羅している — 少なくとも 1 つのテストで、正常系とあわせてエラー／空／読み込み状態を検証している