Playwright 完全ガイド【2026年最新】｜E2E / コンポーネント / API テスト・Locator・Web-first Assertions・Fixtures・storageState・Trace Viewer・UI Mode・Codegen・Aria Snapshots・CI 統合まで実戦パターンで解説

# 対話形式で雛形生成
npm init playwright@latest
# or Bun: bun create playwright
# or Deno: deno run -A npm:create-playwright@latest
#
# ? Do you want to use TypeScript or JavaScript? TypeScript
# ? Where to put your end-to-end tests? tests
# ? Add a GitHub Actions workflow? y
# ? Install Playwright browsers? y

# 既存プロジェクトに追加
npm install --save-dev @playwright/test
npx playwright install --with-deps

# バージョン確認
npx playwright --version

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

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,        // CI で .only が残っていたら失敗
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: [
    ["html", { open: "never" }],
    ["github"],                         // GitHub Actions 用 inline annotation
    ["json", { outputFile: "playwright-report/results.json" }],
  ],

  use: {
    baseURL: process.env.BASE_URL ?? "http://localhost:3000",
    trace: "on-first-retry",           // 失敗リトライ時に trace 保存
    screenshot: "only-on-failure",
    video: "retain-on-failure",
    locale: "ja-JP",
    timezoneId: "Asia/Tokyo",
  },

  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox",  use: { ...devices["Desktop Firefox"] } },
    { name: "webkit",   use: { ...devices["Desktop Safari"] } },
    { name: "mobile",   use: { ...devices["iPhone 15"] } },
  ],

  // 開発サーバーを自動起動（次の URL が返るまで待つ）
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

test("login flow", async ({ page }) => {
  await page.goto("/login");

  // ラベルで入力欄を特定（スタイル変更の影響を受けない）
  await page.getByLabel("メールアドレス").fill("alice@example.com");
  await page.getByLabel("パスワード").fill("secret-pw");

  // ボタンは role + name で
  await page.getByRole("button", { name: "ログイン" }).click();

  // 見出しで画面遷移を検証
  await expect(page.getByRole("heading", { name: "ダッシュボード" })).toBeVisible();
});

// 商品リストの中から「Product 2」の「Add to cart」だけを押す
const product = page.getByRole("listitem")
  .filter({ hasText: "Product 2" });
await product.getByRole("button", { name: "Add to cart" }).click();

// 1 つしかないはずだが複数マッチしたら失敗させる
await page.getByRole("button", { name: "送信" }).click();

// 複数マッチが合法なら first() / last() / nth(n)
await page.getByRole("listitem").first().click();
await page.getByRole("listitem").nth(2).click();

// visible: true で可視要素のみにフィルタ（v1.51+）
await page.getByRole("button", { name: "削除" }).filter({ visible: true }).click();

const submitButton = page
  .getByRole("button", { name: "送信" })
  .describe("メインフォームの送信ボタン");

await submitButton.click();
// Trace Viewer / HTML Report 上で「メインフォームの送信ボタン」と表示される

// 可視・存在・状態
await expect(banner).toBeVisible();
await expect(modal).toBeHidden();
await expect(submit).toBeEnabled();
await expect(check).toBeChecked();

// テキスト・属性
await expect(h1).toHaveText("ようこそ");
await expect(h1).toContainText("ようこそ");
await expect(link).toHaveAttribute("href", "/home");
await expect(btn).toHaveClass(/primary/);
await expect(btn).toContainClass("primary");          // v1.52+（個別クラス判定が簡潔に）

// 数・URL・タイトル
await expect(page.getByRole("listitem")).toHaveCount(5);
await expect(page).toHaveURL("/dashboard");
await expect(page).toHaveTitle(/ダッシュボード/);

// カスタムタイムアウト（グローバル 5s → 個別 10s）
await expect(slowItem).toBeVisible({ timeout: 10_000 });

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

test.describe("認証フロー", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto("/");
  });

  test.afterEach(async ({ page }, testInfo) => {
    // 失敗時のみスクリーンショットを artifact に添付
    if (testInfo.status !== "passed") {
      await page.screenshot({ path: `fail-${testInfo.title}.png` });
    }
  });

  test("正しい認証情報でログインできる", async ({ page }) => {
    await page.getByRole("link", { name: "ログイン" }).click();
    await page.getByLabel("メール").fill("alice@example.com");
    await page.getByLabel("パスワード").fill("correct-pw");
    await page.getByRole("button", { name: "ログイン" }).click();
    await expect(page).toHaveURL("/dashboard");
    await expect(page.getByText("ようこそ, Alice")).toBeVisible();
  });

  test("誤ったパスワードはエラー表示", async ({ page }) => {
    await page.getByRole("link", { name: "ログイン" }).click();
    await page.getByLabel("メール").fill("alice@example.com");
    await page.getByLabel("パスワード").fill("wrong-pw");
    await page.getByRole("button", { name: "ログイン" }).click();
    await expect(page.getByRole("alert")).toContainText("パスワードが違います");
  });

  // 並列モード切替（ファイル単位で直列にしたい場合）
  test.describe.configure({ mode: "serial" });
});

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

const authFile = ".auth/user.json";

setup("authenticate", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("メール").fill(process.env.E2E_EMAIL!);
  await page.getByLabel("パスワード").fill(process.env.E2E_PASSWORD!);
  await page.getByRole("button", { name: "ログイン" }).click();
  await expect(page).toHaveURL("/dashboard");
  // Cookie / LocalStorage / IndexedDB を丸ごとダンプ
  await page.context().storageState({ path: authFile });
});

export default defineConfig({
  projects: [
    // 1) セットアップ専用プロジェクト
    {
      name: "setup",
      testMatch: /global\.setup\.ts/,
    },
    // 2) 通常のテストは setup 後に走る + storageState を使う
    {
      name: "chromium",
      dependencies: ["setup"],
      use: {
        ...devices["Desktop Chrome"],
        storageState: ".auth/user.json",
      },
    },
  ],
});

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

type Fixtures = {
  apiClient: { get: (url: string) => Promise<any> };
  todoPage: import("./todo-page").TodoPage;
};

export const test = base.extend<Fixtures>({
  // 各テストで API 呼び出しできる軽量クライアント
  apiClient: async ({ request }, use) => {
    await use({
      async get(url) {
        const res = await request.get(url);
        return await res.json();
      },
    });
  },

  // Page Object Model を fixture として提供
  todoPage: async ({ page }, use) => {
    const { TodoPage } = await import("./todo-page");
    const todoPage = new TodoPage(page);
    await todoPage.goto();
    await use(todoPage);
  },
});

export { expect };

import { test, expect } from "../fixtures/test-fixtures";

test("TODO を追加できる", async ({ todoPage }) => {
  await todoPage.addTodo("レポートを書く");
  await expect(todoPage.listItem("レポートを書く")).toBeVisible();
});

test("API で残数を確認", async ({ apiClient }) => {
  const data = await apiClient.get("/api/todos/stats");
  expect(data.pending).toBeGreaterThan(0);
});

export const test = base.extend<{ adminClient: unknown }>({
  adminClient: [async ({}, use) => {
    // 中身はテストレポートの step tree に出さない
    await use(createAdminClient());
  }, { box: true, title: "Admin API クライアント" }],
});

import type { Locator, Page } from "@playwright/test";

export class TodoPage {
  constructor(private readonly page: Page) {}

  readonly input = this.page.getByPlaceholder("やることを入力");
  readonly list = this.page.getByRole("list", { name: "TODO 一覧" });

  async goto() { await this.page.goto("/todos"); }

  listItem(name: string): Locator {
    return this.list.getByRole("listitem").filter({ hasText: name });
  }

  async addTodo(text: string) {
    await this.input.fill(text);
    await this.input.press("Enter");
  }

  async toggleDone(name: string) {
    await this.listItem(name).getByRole("checkbox").check();
  }

  async deleteTodo(name: string) {
    await this.listItem(name).getByRole("button", { name: "削除" }).click();
  }
}

npx playwright codegen http://localhost:3000

# ブラウザと Playwright Inspector が開く
# 画面を操作するだけで対応する TS コードが Inspector に生成される
# v1.55+ はクリック操作のあとに toBeVisible / toHaveText 等を自動提案
# 完了したらコピーしてテストファイルに貼り付け

npx playwright test --ui

# 機能:
# - テストツリーから選んで実行
# - タイムトラベル（過去の任意のステップに戻れる）
# - Locator Pick（画面からクリックでロケーター取得）
# - Watch モード（ファイル保存で自動再実行）
# - ネットワークパネル、コンソール、ソース表示
# - v1.58+ は JSON レスポンスの自動整形、コードエディタ内 Ctrl+F 検索

# trace: "on-first-retry" 設定済みなら CI で自動収集される
# ローカルで強制収集したい場合
npx playwright test --trace on

# trace ファイルを開く
npx playwright show-trace test-results/.../trace.zip

# HTML Report 経由でも開ける
npx playwright show-report

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

test.describe("REST API", () => {
  test("GET /api/posts", async ({ request }) => {
    const res = await request.get("/api/posts");
    expect(res.status()).toBe(200);
    const body = await res.json();
    expect(Array.isArray(body)).toBe(true);
  });

  test("POST /api/posts で新規作成", async ({ request }) => {
    const res = await request.post("/api/posts", {
      data: { title: "test", body: "content" },
      headers: { "Content-Type": "application/json" },
    });
    expect(res.status()).toBe(201);
    const body = await res.json();
    expect(body.id).toBeDefined();
  });
});

# React の場合
npm init playwright@latest --ct
# or Vue / Svelte / Solid 用の別パッケージ

npx playwright test --ui

import { test, expect } from "@playwright/experimental-ct-react";
import { Button } from "./Button";

test("variant prop が適用される", async ({ mount }) => {
  const component = await mount(
    <Button variant="primary">保存</Button>
  );
  await expect(component).toContainClass("bg-primary-500");
  await expect(component).toHaveText("保存");
});

test("onClick が呼ばれる", async ({ mount }) => {
  let clicked = 0;
  const component = await mount(
    <Button onClick={() => clicked++}>Click me</Button>
  );
  await component.click();
  expect(clicked).toBe(1);
});

await expect(page.locator("main")).toMatchAriaSnapshot(`
  - heading "ようこそ" [level=1]
  - navigation:
    - link "ホーム"
    - link "設定"
  - button "新規作成"
`);

test("ランディングページのデザイン", async ({ page }) => {
  await page.goto("/");
  await expect(page).toHaveScreenshot("landing.png", {
    maxDiffPixelRatio: 0.01,
    fullPage: true,
    mask: [page.locator(".dynamic-time")],  // 時刻表示など動的部分をマスク
  });
});

# 初回は --update-snapshots を付けて正解画像を保存
npx playwright test --update-snapshots

# 以降は変更検知したら失敗する
npx playwright test

# ローカルでもワーカ並列が既定（workers: 自動）
npx playwright test --workers 8

# CI で複数マシンに分散（4 マシン構成）
npx playwright test --shard=1/4    # マシン 1
npx playwright test --shard=2/4    # マシン 2
npx playwright test --shard=3/4    # マシン 3
npx playwright test --shard=4/4    # マシン 4

# レポートを後で合体させる
npx playwright merge-reports --reporter=html ./all-blob-reports

name: E2E Tests
on:
  push: { branches: [main] }
  pull_request:

jobs:
  e2e:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 22, cache: npm }
      - run: npm ci

      - name: Playwright ブラウザ
        run: npx playwright install --with-deps chromium firefox webkit

      - name: E2E 実行（シャード ${{ matrix.shard }}/4）
        run: npx playwright test --shard=${{ matrix.shard }}/4 --reporter=blob
        env:
          BASE_URL: http://localhost:3000
          E2E_EMAIL:    ${{ secrets.E2E_EMAIL }}
          E2E_PASSWORD: ${{ secrets.E2E_PASSWORD }}

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: blob-${{ matrix.shard }}
          path: blob-report
          retention-days: 3

  merge-reports:
    if: always()
    needs: [e2e]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 22 }
      - run: npm ci
      - uses: actions/download-artifact@v4
        with: { pattern: blob-*, merge-multiple: true, path: all-blob-reports }
      - run: npx playwright merge-reports --reporter=html all-blob-reports
      - uses: actions/upload-artifact@v4
        with: { name: html-report, path: playwright-report, retention-days: 7 }