Playwright

Playwright とは

Playwright は、Microsoft が開発したクロスブラウザ E2E (End-to-End) テストフレームワークである。Chromium、Firefox、WebKit の 3 エンジンをサポートし、1 つのテストコードで全ブラウザをテストできる。npm への最初の公開は 2019 年 12 月の 0.9.1 で、安定版 1.0 は 2020 年 5 月に出た。2026 年 8 月時点の最新は 1.62.1 (2026 年 7 月公開) である。ブラウザを別プロセスで起動し制御プロトコル経由で外側から操作する構造のため、テストコードは被検ページの JavaScript 実行環境から独立している。

基本的なテスト

@playwright/test は各テストに page フィクスチャを渡す。テストごとに独立したブラウザコンテキストが作られるため、Cookie や localStorage が前のテストから漏れてこない。expect(locator) 形式のアサーションは条件が満たされるまで再試行されるので、待機のための sleep を書く必要はない。

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

test('ログインフロー', async ({ page }) => {
  await page.goto('https://example.com/login');

  await page.fill('[name="email"]', 'user@example.com');
  await page.fill('[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  await expect(page).toHaveURL('/dashboard');
  await expect(page.locator('h1')).toHaveText('ダッシュボード');
});

Cypress との比較

差の多くは動作位置から来る。Cypress はテストコードをブラウザ内で被検アプリと同じイベントループで動かし、Playwright はブラウザの外から操作する。この違いがマルチタブや別オリジンの扱いに表れる。

観点	Playwright	Cypress
ブラウザ	Chromium, Firefox, WebKit	Chromium, Firefox。WebKit は実験的機能 (experimentalWebKitSupport・既定 off)
言語	TypeScript, JavaScript, Python, Java, C#	JavaScript, TypeScript
並列実行	ネイティブ対応	Cypress Cloud (有料)
マルチタブ	対応	非対応
iframe	対応	制限あり
ネットワークインターセプト	対応	対応
自動待機	対応	対応

強力な機能

自動待機 (Auto-waiting)

操作の前にアクション可能性の検査を通す仕組みである。クリックなら、ロケーターが 1 要素に解決すること・可視であること・アニメーションが止まっていること・他要素に覆われずイベントを受け取れること・有効であることの 5 点を検査し、すべて通ってから初めてクリックする。fill では可視・有効・編集可能を見る。検査はタイムアウトまで再試行され、通らなければ TimeoutError で失敗する。既定値はテスト全体が 30 秒、アサーションが 5 秒である。

// クリックは可視・安定・イベント受理・有効の検査が通るまで待ってから実行される
await page.click('button#submit');
// アサーションは条件が満たされるまで既定 5 秒のあいだ再試行する
await expect(page.locator('.result')).toBeVisible();

ネットワークインターセプト

// API レスポンスをモック
await page.route('**/api/users', route =>
  route.fulfill({ json: [{ id: '1', name: 'Alice' }] })
);

スクリーンショットとビデオ

// テスト失敗時に自動でスクリーンショットを保存
// playwright.config.ts
export default defineConfig({
  use: {
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    trace: 'retain-on-failure',
  },
});

trace を有効にすると、各操作の前後の DOM スナップショット・ネットワーク通信・コンソール出力・ソース位置が 1 つの trace.zip にまとまる。npx playwright show-trace trace.zip で開き、失敗した操作の時点の画面を遡って確認できる。CI で再現しない失敗の調査はここが起点になる。npm init playwright が生成する既定の設定は on-first-retry で、初回失敗のリトライ時にだけ記録する。常時記録は容量を食うため、まずは失敗時だけに絞るのが実務的だ。

Codegen (テストコード自動生成)

npx playwright codegen https://example.com
# ブラウザが開き、操作を記録してテストコードを自動生成

CI での実行

ブラウザ本体は npm パッケージに同梱されないため、CI では npx playwright install --with-deps でブラウザと OS 側の依存ライブラリまで入れる。この手順を省くと起動時に失敗する。失敗時だけ playwright-report/ を artifact に上げておけば、手元でトレースを開いて原因を追える。

# GitHub Actions
- name: Install Playwright
  run: npx playwright install --with-deps
- name: Run E2E tests
  run: npx playwright test
- uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-report
    path: playwright-report/

自動待機があっても、待つ対象を間違えれば不安定なテストは残る。読み込み途中の要素が一瞬だけ検査を通ってしまう画面では、クリックできるかどうかではなく toHaveText のように最終状態を検査するアサーションへ寄せる。要素の指定も、CSS セレクターより getByRole や getByLabel といったユーザーから見える属性で引くほうが実装変更で壊れにくい。