はじめに
先日、Next.js の勉強会で、Playwright による E2E テストを取り上げました 🎭
ウェブアプリに、E2E テストを導入することで、
ブラウザ上での動作確認を自動化することができます。
今回は、E2E テスト初心者の方向けに、
「Playwright を Next.js へ導入するガイド」をまとめました！
E2E テスト入門として、参考になれば嬉しいです 🙌
E2E テストとは？
E2E（End-to-End）テストとは、アプリケーションの全体的な動作を検証するテスト手法です。
ユーザーの視点で、実際のブラウザを操作して行うテストであり、
ユーザーがアプリケーションを使う際の一連の流れを自動で検証できます。
要は、実際のブラウザ環境で、アプリ全体を動作を自動でシミュレーションできます！
そもそもの、テストの種類と関係性
そもそも、
ソフトウェアの自動テストには、いくつかの種類があります。
ポイントは、
各テストの種類は、信頼性とコストがトレードオフの関係にあるということです！
なので、アプリケーションの特性に応じて、
バランスの取れた「テスト戦略」を検討することが重要になってきます！
特に、代表的なテスト戦略の 1 つは、Kent C. Dodds が提唱する「Testing Trophy」です：
出典:https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications
これは、一言で言うと、
「上記の面積の比率（統合テストに重きを置く）でテストを書く」という戦略です。
（もし、テストの種類に関して興味があれば、下記をチェックしてみてください！）
このように、自動テストにも、いくつかの種類があるので、
それぞれ使い分けることが、重要になってきます 😎
Next.js App Router（RSC） と従来のテストツールの課題
Next.js 公式の要約：
知っておくと良い点：async サーバーコンポーネントは React エコシステムにとって新しいため、Jest /Vitest は現在サポートしていません。同期的なサーバーコンポーネントとクライアントコンポーネントのユニットテストは実行できますが、async コンポーネントには、E2E テストを使用することをお勧めします。
当記事執筆時点（2025/03/19）では、
Next.js AppRouter などのフレームワークで使用できる、React Server Components (RSC) は、従来のテストツール（Jest, Vitest など）で、まだ完全にサポートされていません。
なので、サーバーコンポーネントでの実装をテストしたい場合、
実際のブラウザで動作確認できる E2E テストが、役立ちます。
Playwright とは？
Playwright は、E2E テストを比較的簡単に行うことができるツールです。
Microsoft が開発・サポートしている、ライブラリでもあります。
Playwright の特徴：
- Next.js（RSC）のテストでも使用可能
- Chrome、Safari、Firefox など、複数のブラウザをデフォルトでサポート
- 実際のブラウザ操作から、コードを生成できる codegen 機能が便利
- 自動待機機能によりテストの安定性が向上
とにかく、デフォルトの状態で使いやすいのが、お気に入りです 🤩
Playwright と他のテストツールの違いは？
上記の npm trends にある通り、
E2E テストツールとしては playwright が、最も勢いがあります！
これの要因として、
前述した通り、E2E テストのニーズが高まっていることに加え、：
- 複数ブラウザ・OS をデフォルトでサポート
- パフォーマンスと安定性に優れ、
- テストコードの生成（codegen）まで行える
などが挙げられます 🫠🫠
Next.js に Playwright を導入する手順
さて、Playwright の概要を把握できましたね！
では、公式を参照しつつ、
実際に Next.js App Router への導入を紹介します：
1. まずは、Playwright のインストールです
npm init playwright@latest
↓ 以下の設定で進めます！
nitializing project in '.'
✔ Where to put your end-to-end tests? · e2e
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true
ターミナルに表示される通りですが、
いろんなコマンドが用意されています：
-
npx playwright test: E2E テストの実行 -
npx playwright test --ui: UI モードで E2E テストの実行 -
npx playwright test --project=chromium: Desktop Chrome を指定した E2E テストの実行 -
npx playwright test example: 特定のファイルを指定した E2E テストの実行 -
npx playwright test --debug: テストをデバッグモードで実行 -
npx playwright codegen: Codegen によるテスト自動生成モード
2. E2E テスト用の設定ファイルを、適宜更新
先ほどのインストールにて、
設定ファイル作成されているので、プロジェクトに合わせて更新します！
例：）
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./e2e",
/* Run tests in files in parallel */
fullyParallel: true,
/* Fail the build on CI if you accidentally left test.only in the source code. */
forbidOnly: !!process.env.CI,
/* Retry on CI only */
retries: process.env.CI ? 2 : 0,
/* Opt out of parallel tests on CI. */
workers: process.env.CI ? 1 : undefined,
/* Reporter to use. See https://playwright.dev/docs/test-reporters */
reporter: "html",
/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
use: {
/* Base URL to use in actions like `await page.goto('/')`. */
baseURL: "http://localhost:3000",
/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
trace: "on-first-retry",
},
/* Configure projects for major browsers */
projects: [
{
name: "chromium",
use: { ...devices["Desktop Chrome"] },
},
],
/* Run your local dev server before starting the tests */
webServer: {
command: "npm run start",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
},
});
個人的に、最初に設定しておきたいのは、：
-
baseURL を設定: これにより、テスト内で
page.goto("/")と記述するだけで TOP ページに遷移できます - projects を設定: テストする環境ブラウザを選べます。実行時間短縮のため、Chrome のみ有効！など変更できます
- webServer を設定: テスト実行時に、一緒に立ち上げるサーバーのコマンドを記載できます。
この辺りです 👍
3. 実行するコマンドを追加
npm scripts を更新して、
E2E テストを実行するコマンドを追加しましょう！
例：
"scripts": {
"dev": "next dev --turbopack",
"build": "next build",
"start": "next build && next start",
"lint": "next lint",
"test": "playwright test"
},
4. E2E テストを実行
では、初期状態でテストを実行してみましょう！
（インストール時に、初期状態で、サンプルのテストファイルが用意されています）
npm run test
↓ 2 つのテストが pass していますね！
上の画像にある通り、テストのレポートも見れるみたいです！
npx playwright show-report
↓
ブラウザで、確認できるの便利ですね 👍
これにて、セットアップが完了です！
あとは、自分のアプリに対する、テストコードを作成していくだけです！
意外と簡単ですね 😎
なぜ Playwright なのか？
筆者の考える利点は、
なんといっても、使いやすさです！
言い換えると、：
- ここまで簡単に導入できて、
- 複数ブラウザ・OS をデフォルトでサポートしていて、
- パフォーマンスと安定性が良く、
- テストコードの生成機能まで付いている
というツールが、他に見当たらないというのが、現状でしょうか！
Playwright の Codegen（テストコード自動生成）とは？
これは少し、実際のユースケース的な内容ですが、便利なので紹介しておきます！
Playwright の Codegen というのは、
実際のブラウザ操作を記録して、テストコードを自動生成する機能です。
公式の動画を見るのが、１番早いですね！
使い方は、：
- まず、VSCode の拡張を導入します
- ローカルで、サーバーを立ち上げましょう！
- そして、サイドバーのテストのマークから、「Record new」をクリック！
- ブラウザが立ち上がるので、手動で動作確認を行います！
- その手動の操作により、リアルタイムでコードが生成されます！
この機能を使えば、複雑な操作のテストコードを素早く作成できます。
要素の取得方法などで、つまる事がなくなりますね！
生成されたコードを元に、必要に応じて調整・リファクタリングを行うのが効率的です！
おまけ：Next.js における E2E/Playwright
冒頭で触れた通り、
それぞれのテストの種類というのは、トレードオフの関係にあります。
一方、現状でテスト戦略を考えると、
- RSC に、主要テストツールが対応していない点
- Playwright が E2E テストの導入をより簡略化している点
を踏まえると、
Kent C. Dodds が提唱する「Testing Trophy」をベースに、
サーバーコンポーネント周りの実装は、E2E に寄せていくというのが、安定でしょうか。
そして、タイムリー（2025/03/11）に、
TypeScript のパフォーマンス改善の発表もありましたね：
出典:https://devblogs.microsoft.com/typescript/typescript-native-port/
Playwright では 10 倍以上、TS の読み込みが早くなる？？w
というリークが出ています。
（もちろんこれが E2E のコストの全てとは思いませんが、、）
Playwright の実行速度は、今後もある程度は向上する模様ですね！
結論として、
トレードオフの関係にあった、
「E2E のコスト」という部分は、各ツールのアップデートにより、日に日に解消されつつあります。
本記事で紹介した通り、Playwright のインストールからセットアップを完了し、
簡単に最初のテストを実行できます。
あとは、codegen の機能で、
ブラウザ操作からテストコードを生成し、適宜修正を加えるだけでテストコードが作成できますよ！
ぜひこの機会に、E2E テストに入門してみてください！
おわりに
最後まで読んでいただき、ありがとうございます 🥳
下記の、React/Next.js ハンズオン勉強会での、振り返りのような記事ですが、
E2E テストへの入門として、当記事が参考になれば幸いです！
そして、もし、間違いや補足情報などがありましたら、
ぜひコメントを追加してください！
Happy Hacking :)
参考
Discussion