【2026年版】Playwrightの始め方 — インストールから最初のE2Eテストまで完全ガイド

まず1本、テストを動かす

Node.jsとnpmが必要です。npm init playwright@latest でテスト環境を作り、ブラウザのインストールを選んでください。下のタイトル確認のテストだけなら、ログイン機能のあるアプリを自分で用意する必要はありません。インターネット接続のある環境で npx playwright test tests/example.spec.ts --project=chromium を実行し、成功を確認しましょう。

ログインの例は、自分の検証用アプリが /login と /dashboard を持ち、指定のラベルがある場合に限って動きます。初回はタイトル確認だけを tests/example.spec.ts に保存してください。

コマンド早見表

# インストール
npm init playwright@latest
# → テスト言語、ブラウザ、CIワークフローを選択

# テスト実行
npx playwright test                    # 全テスト実行
npx playwright test --headed           # ブラウザを表示しながら実行
npx playwright test example.spec.ts    # 特定ファイルのみ
npx playwright test --trace on         # トレース収集して実行
npx playwright show-report             # HTMLレポートを表示
npx playwright show-trace trace.zip    # トレースを表示

// tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('トップページのタイトル確認', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example/);
});

test('ログインフォームのテスト', async ({ page }) => {
  // 別途、検証用アプリと baseURL の設定が必要な例
  await page.goto('/login');

  // フォームに入力
  await page.getByLabel('メールアドレス').fill('user@example.com');
  await page.getByLabel('パスワード').fill('password');
  await page.getByRole('button', { name: 'ログイン' }).click();

  // ログイン後のURLを確認
  await expect(page).toHaveURL('/dashboard');
});

// playwright.config.ts（マルチブラウザ設定）
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
  reporter: 'html',
  use: {
    // 相対URLの例を動かす場合。検証用アプリを別途起動する
    baseURL: 'http://127.0.0.1:3000',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    trace: 'on-first-retry',
  },
});

よくある詰まりポイント

Q. SeleniumやCypressとの違いは？ 対応ブラウザ、複数タブや別オリジンの扱い、既存資産との相性で選びます。CypressはFirefoxにも対応しています。「Seleniumは遅い」「CypressはChromiumだけ」といった一般化は避け、必要な操作を小さなテストで確認しましょう。

Q. テストが不安定（Flaky）になる。どうすれば安定する？ 要素の準備状態やテストデータの干渉などを確認します。Locatorの操作と await expect(locator).toBeVisible() などの自動再試行するアサーションを使いましょう。公式資料はテストでの networkidle 待機を推奨していません。固定の秒数や通信停止を待つより、検証したい画面の状態を直接確認します。

Q. ヘッドレスモードでないと遅い。CIでは必ずheadlessにすべき？ 通常のテスト実行はheadlessが既定です。ローカルで原因を調べる場合は --headed や --debug で画面や操作を確認できます。CIを組む段階になったら、次のGitHub Actions入門と公式のCI手順を参照してください。

次に読む記事を、目的で選ぶ

• テストをpushのたびに動かしたいなら：GitHub Actions入門 — ワークフローの基本を学ぶ。
• 関数単位のテストも追加したいなら：Jest入門 — 画面全体のテストと単体テストを使い分ける。
• TypeScriptの型でつまずいたら：TypeScript入門 — 型注釈と型チェックの基本を確認する。

参考資料

確認日：2026年10月5日。

• Playwright：Installation
• Playwright：Assertions
• Playwright：Page API
• Playwright：Browsers
• Playwright：Setting up CI
• Cypress：Launching browsers

ひよこ

Playwrightってブラウザを自動で操作できるツールなの？

ペンギン先生

そうだよ。Microsoftが開発したE2E（End-to-End）テストフレームワークで、ChromiumやFirefox・WebKitをコードで自動操作できるんだ。「ボタンをクリックしたらログインできるか」「フォームを送信したら正しいページに遷移するか」みたいなユーザー視点のテストを自動化できるよ。

ひよこ

SeleniumやCypressとは何が違うの？

ペンギン先生

PlaywrightはChromium・Firefox・WebKitを同じテストコードで扱えるよ。CypressもFirefoxなどに対応しているので「Chromiumだけ」とは言えない。速さだけで決めず、使うブラウザ・タブ操作・既存のテスト資産で選ぼう。

ひよこ

インストールはどうやるの？

ペンギン先生

Node.jsとnpmを用意し、作業ディレクトリで `npm init playwright@latest` を実行するよ。言語やテスト用フォルダーを選び、ブラウザのインストールを有効にしよう。省いた場合は `npx playwright install` で追加できる。

ひよこ

テストってどうやって書くの？

ペンギン先生

`test('テスト名', async ({ page }) => { })` の中に操作と結果の確認を書くよ。例えば `page.goto('https://example.com')` で開き、`await expect(page).toHaveTitle(/Example/)` でタイトルを確認する。相対URLを使うときは、設定に `baseURL` が必要なんだ。

ひよこ

要素を探すときはどう書けばいいの？

ペンギン先生

PlaywrightではLocatorという仕組みで要素を指定するよ。`getByRole`（ARIAロール）・`getByLabel`（ラベル）・`getByText`（テキスト）・`getByTestId`（data-testid属性）の4つが主なメソッドだよ。CSSセレクタより意図が伝わりやすいし、ページ構造が変わっても壊れにくいから積極的に使うといいね。

ひよこ

テストが失敗したときにどう調べるの？

ペンギン先生

`npx playwright test --trace on` でトレースを記録できるよ。操作ごとのページ状態、スクリーンショット、ネットワーク情報を調べられる。出力されたtrace.zipのパスを使い、`npx playwright show-trace <パス>` で開こう。トレースと動画は別の機能だよ。

ひよこ

複数ブラウザで一度にテストできるの？

ペンギン先生

設定の `projects` にChromium・Firefox・WebKitを指定すると、それぞれで実行できるよ。WebKitでSafari系の互換性を調べられるけれど、PlaywrightのWebKitはSafariアプリそのものではないので、実機の確認をすべて置き換えるものではないんだ。

ひよこ

スクリーンショットや動画の記録もできるの？

ペンギン先生

できるよ。`screenshot: 'only-on-failure'` と設定すると失敗時だけスクリーンショットが保存される。`video: 'retain-on-failure'` にすると失敗したテストの操作動画が保存されるんだ。HTMLレポートを見ると画像・動画付きで結果を確認できてデバッグがとても楽になるよ。