E2Eテストは、sleepで待たせると壊れます。Playwrightで1本目を書き、何をE2Eにするかを先に決めます。
前回: node_modulesが重い理由 — pnpmとBunを測る 作業場所はVMの中(Ubuntu)です。確認だけ、ホストのWindowsのブラウザを使います。これまで作ってきた
~/react-demo/と~/server/を、両方いっぺんに動かします。
テストの回の最後に、こう書いて先送りしました。
E2E は「最後に、数本だけ」書きます。 フロントとサーバーを繋いだあとに、必要になってから入れます。
その「あと」が来ました。 そして、先送りした理由も、いま全部ひっくり返っています。
| あのとき書いた理由 | いまはどうか |
|---|---|
| 繋ぐ先が無い(フロントはサーバーを1度も呼んでいない) | ~/server に認証まで入った。 繋ぐ先はある |
| VMにブラウザが無い | ここが、この記事の最初の関門です |
| 一番壊れやすいものから始めることになる | 壊れやすさの正体(待ち方)を、正面から扱えるだけの下地ができた |
とくに2つめです。あなたのUbuntu Serverには、画面がありません。 デスクトップも、マウスカーソルも、ウィンドウもありません。
画面が無いマシンで、ブラウザのテストが動くのか。
動きます。 ただし、「なぜ動くのか」を知らないまま入れると、最初のエラーで詰みます。 そこから始めます。
そして、この記事の山場は導入ではありません。こちらです。
E2Eは「たまに落ちる」ようになります。そして、たまに落ちるテストは、そのうち誰も見なくなります。 原因のほとんどは、アプリのバグではなく、待ち方です。
対象レベル: 初級 / 区分: 必修
この記事でわかること
- コンポーネントのテストとE2Eは、規模の違いではないこと。前者は偽物のDOMの中で完結し、後者は本物のブラウザが本物のサーバーを叩く。だからE2Eだけが「繋がっていない」を見つけられる
- E2Eは高いこと。遅く、壊れやすく、落ちたときに原因の候補が多い。だから「たくさん書く」は最初から間違いで、何をE2Eにするかを選ぶ作業のほうが本体
sleep(waitForTimeout)で待った瞬間に、テストは遅くなり、しかも壊れること。Playwrightはほとんど自動で待つので、待ちを手で書きたくなったら、たいてい書き方のほうが間違っている- 画面の無いVMでも、ヘッドレスならブラウザは動くこと。ただし
--headedと--uiは使えず、失敗を見る手段はトレース・スクリーンショット・動画に変わる - E2Eを増やすと、開発が止まること。1本増やすたびに、毎回の待ち時間と「意味のない失敗」が増える
この記事でやること
- 画面の無いVMに Playwright を入れる(
npm init playwright@latestと、--with-depsが何をしているか) - フロントとAPIを繋ぐ。E2Eの対象がまだ無いので、ログイン画面とAPI呼び出しを最小限だけ足す
- 1本目を書く。ログインして、タスクを追加して、一覧に出るまで。サーバーは Playwright に立てさせる
- わざと不安定にして、直す。
waitForTimeoutを入れてみて、なぜ駄目なのかを出力で確かめる - わざと落として、トレースを見る。ホストのWindowsのブラウザからレポートを開く
- CIに足す。ただし毎回は走らせない書き方も用意する
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| E2E(End to End) | 端から端まで。画面を操作して、サーバーとデータベースまで通して確かめるテスト |
| Playwright | 本物のブラウザを操作してテストする道具。Microsoft 製 |
| ヘッドレス(headless) | 画面を描かずにブラウザを動かすこと。ウィンドウが出ないだけで、中身は同じブラウザ |
| ロケータ(Locator) | 「画面のこの要素」を指す指し示し方。page.getByRole(...) などが返すもの |
| 自動待機(auto-waiting) | クリックする前に、押せる状態になるまで Playwright が勝手に待つ仕組み |
| フレーキー(flaky) | 同じコードなのに、通ったり落ちたりするテストのこと。E2Eの最大の敵 |
| リトライ(retry) | 落ちたテストを、もう一度だけ走らせ直す設定 |
| トレース(trace) | テストの実行中に起きたこと全部の記録。操作・画面・通信・コンソールが時系列で入っている |
webServer | テストを始める前に、Playwright にサーバーを立てさせる設定 |
baseURL | page.goto("/") の「/」がどこを指すかを決める設定 |
| strict モード | 1つの指し示し方が2個以上の要素に当たったら、エラーにするPlaywrightの既定の動作 |
① コンポーネントのテストとE2Eは、何が違うのか
テストの回で書いたテストを、もう一度見てください。
await user.type(screen.getByLabelText("やること"), "牛乳を買う");
await user.click(screen.getByRole("button", { name: "追加" }));
expect(screen.getByText("牛乳を買う")).toBeInTheDocument();
やっていることは、これから書くE2Eとほとんど同じに見えます。入力して、押して、出たか確かめる。
それでも、この2つは別物です。 違いは「規模」ではありません。動いている場所が違います。
| コンポーネントテスト(Vitest + RTL) | E2E(Playwright) | |
|---|---|---|
| ブラウザ | 無い。 jsdom が Node の中にDOMの真似を作る | 本物。Chromium が実際に起動する |
| CSS | ほぼ効かない。 レイアウトの計算をしていない | 効く。 幅も、重なりも、display: none も本物 |
| サーバー | 呼ばない(呼んだら偽物に差し替える) | 本物を叩く。 DBまで届く |
| Cookie・セッション | 無い | 本物のブラウザが本物のCookieを保存する |
| 速さ | 数百ミリ秒 | 数秒〜数十秒 |
| 落ちたときの原因 | だいたいアプリの中 | アプリ / サーバー / DB / 通信 / 待ち方 |
この表の下2行が、E2Eの正体です。
E2Eだけが見つけられるもの
コンポーネントテストが全部通っているのに、開くと動かない。 これは普通に起きます。
- APIのURLを間違えている。 テストでは
fetchを偽物に差し替えているので、URLが何であっても通る - Cookieが送られていない。 認証の回の
sameSiteやsecureの設定ミスは、本物のブラウザでしか出ません - ボタンが他の要素の下に隠れている。
jsdomはレイアウトを計算しないので、重なりを知りません。クリックは成功します - サーバーが起動しない。 テストはサーバーの存在を知らないので、当然通ります
逆に言うと、E2Eをこう使ってはいけません。
「空欄のまま押しても増えない」をE2Eで確かめる。
これは20倍遅く、同じことを確かめているだけです。しかもサーバーもDBも巻き込むので、無関係な理由で落ちます。
② E2Eは高い。だから、何をE2Eにするかを先に決める
「高い」というのは、金額の話ではありません。 払うものは3つです。
| 払うもの | 具体的に |
|---|---|
| 時間 | 1本あたり数秒〜数十秒。10本で数分。CIの待ち時間がそのまま伸びる |
| 壊れやすさ | アプリを直していないのに落ちる日が来る。文言を1文字変えただけ、DBに前回のゴミが残っていただけ |
| 調べる手間 | 落ちたときに画面が見えない。ログだけでは、どこで止まったのか分からない |
だから、判断はこうなります。
「これが壊れていたら、そもそもサービスとして成立しない」流れだけをE2Eにする。
E2Eにするもの / しないもの
| 書く | 書かない |
|---|---|
| ログインできる | ログイン失敗のときの文言 |
| 一番中心の操作が1周する(追加して、一覧に出る) | 追加できるあらゆる条件の組み合わせ |
| お金や取り返しのつかないものが動く(注文、削除の確認) | ボタンの色や配置 |
| 複数のシステムをまたぐ(フロント+API+DB+Cookie) | 関数1つの計算結果 |
右側は「テストしない」ではありません。 右側は、コンポーネントテストとユニットテストでやります。 速くて、原因もすぐ分かるからです。
この記事で書くE2Eは、最終的に1本です。 少なすぎると思うかもしれません。ですが、1本でも「フロントとサーバーが繋がっている」ことは保証されます。 そして、その1本すら無い状態のプロジェクトは、世の中にたくさんあります。
③ 画面の無いVMで、ブラウザは動くのか
ここが最初の関門です。
まず、ヘッドレスが何かをはっきりさせます。
ヘッドレス = 「画面を描く部分だけ使わないブラウザ」
別のソフトではありません。 Chromium そのものです。HTMLを読んで、CSSを計算して、JavaScriptを実行して、レイアウトを決めるところまで全部やります。やらないのは、その結果を画面に出すことだけです。
だから、画面の無いUbuntu Serverでも動きます。 そして、必要なときはスクリーンショットも撮れます(描く先が画面ではなく画像ファイルになるだけです)。
ただし、ブラウザ本体は「単体のexe」ではありません。 フォント、画像のデコーダ、音声、暗号など、大量の共有ライブラリに依存しています。 素のUbuntu Serverには、その多くが入っていません。ここで最初のエラーが出ます。
入れる
VMの中で、~/react-demo/ に入って実行します。
対話で4つ聞かれます。 答えはこれです。
| 質問 | 答え | 理由 |
|---|---|---|
| TypeScript / JavaScript | TypeScript | 前々回で ~/react-demo/ をTypeScriptにしました |
| テストを置くフォルダ名 | e2e | 既定は tests ですが、Vitest のテストと混ざります。分けます |
| GitHub Actions のワークフローを作るか | いいえ(false) | ⑧で、既存の ci.yml に自分で足します |
| ブラウザを入れるか | はい | 本体のダウンロードです |
このあと、もう1つ聞かれることがあります。
Install Playwright operating system dependencies (requires sudo / root) - No
ここは「はい」でも構いませんが、この記事では「いいえ」にして、次で手で入れます。 何が起きているのかを見たいからです。
e2eにした理由をもう少し。 Vitest は既定でプロジェクト全体の*.test.*と*.spec.*を拾い(srcの中だけではありません)、Playwright はtestDirの中を拾います。 フォルダを分けただけでは、npm test(Vitest)がe2e/の Playwright のテストも実行しようとして、意味の分からないエラーで落ちます。 後ろの「つまずいたところ」にあるexclude("**/e2e/**")を、vite.config.tsのtestに先に足しておいてください。@playwright/testのtestは Vitest のtestではありません。
依存ライブラリを入れる
sudo は権限の回でやった「管理者として実行する」やつです。ここで sudo が要るのは、apt でシステム全体にライブラリを入れるからです。
流れる内容を、少し見てください。
Installing dependencies...
Get:1 http://archive.ubuntu.com/ubuntu noble/main amd64 libnss3 amd64 ...
Get:2 ... libnspr4 ... libatk1.0-0t64 ... libcups2t64 ... libxkbcommon0 ...
libnss3(暗号)、libcups(印刷)、libxkbcommon(キーボード配列)。 画面が無いのに印刷とキーボードのライブラリが要るのは、Chromiumがそれらを前提に作られているからです。「ブラウザだけ入れれば動く」ではないのは、こういう理由です。
ブラウザ本体を入れる
ここが、この記事で一番やりがちな事故です。
sudoを付けないでください。 ブラウザ本体は「あなたのホームの下」(~/.cache/ms-playwright/)に入ります。sudoを付けると/root/の下に入り、テストを普通のユーザーで走らせたときに「実行ファイルが無い」と言われます。
まとめると、こうなります。
| コマンド | sudo | 入る場所 |
|---|---|---|
playwright install-deps | 要る | システム全体(apt) |
playwright install | 要らない | 自分のホームの下 |
npx playwright install --with-deps chromium は、この2つをまとめてやってくれます。 便利ですが、中で sudo を呼ぶので、パスワードを聞かれるタイミングが分かりにくいです。最初の1回は、分けたほうが何が起きたか見えます。
入ったか確かめる
Version 1.55.0
172M /home/ubuntu/.cache/ms-playwright/
[スクリーンショット: 01_playwright導入.png] npx playwright --version と du -sh ~/.cache/ms-playwright/ を続けて実行した結果を撮ってください。バージョンと、入ったブラウザの容量が分かる形で。
170MB前後です。 ディスクの余裕を確認しておいてください。
df -h /で見られます。3種類(Chromium / Firefox / WebKit)全部入れると、この3倍近くになります。この記事では Chromium だけにします。
戻し方
やめたくなったら、これで消えます。
apt で入れたライブラリはそのまま残ります。 害はありませんが、気になるなら sudo apt autoremove で不要になったものだけ落ちます。
使えないもの(先に知っておく)
画面が無いので、Playwright の便利機能のうち2つは、このVMでは使えません。
| 使えないもの | 何をするものだったか | 代わりにやること |
|---|---|---|
--headed | ブラウザのウィンドウを出して、動くところを目で見る | トレースと動画(⑦) |
--ui | UIモード。1ステップずつ止めて画面を見る | HTMLレポート(⑦) |
--headed を付けると、こう言われます。
Error: Looks like you launched a headed browser without having a XServer running.
Set either 'headless: true' or use 'xvfb-run <your-playwright-app>' before running Playwright.
「XServer が無い」= 画面を描く相手がいない、という意味です。xvfb-run(画面があるふりをするソフト)を入れれば動きますが、結局それも見られません。 見る手段は⑦で用意します。
④ 繋ぐ — E2Eの対象を、先に作る
②で「複数のシステムをまたぐものを書く」と決めました。 ところが、~/react-demo/ はまだサーバーを1度も呼んでいません。 タスクはブラウザの中だけで生まれて、リロードで消えます。
このままE2Eを書いても、①の表の下2行が空っぽです。 なので、最小限だけ繋ぎます。
これは「フロントとバックを繋ぐ回」ではありません。 E2Eの対象を用意するために、必要な分だけやります。エラー表示も、読み込み中の表示も、最低限です。
1. Vite に「/api は3000番へ回す」と教える
~/react-demo/vite.config.ts の server に、1行足します。
export default defineConfig({
plugins: [react()],
server: {
proxy: {
"/api": "http://localhost:3000",
},
},
test: {
environment: "jsdom",
globals: true,
setupFiles: "./src/setupTests.ts",
},
});
これで、ブラウザから見ると http://localhost:5173/api/tasks が、裏で3000番に転送されます。
なぜこうするのか。理由は Cookie です。
フロント(5173番)から直接 API(3000番)を叩くと、ブラウザから見て「別のサイト」になります。すると、認証の回で入れたセッションCookieが送られません。CORSの設定と sameSite と credentials: "include" を全部正しく揃えれば動きますが、入口としては重すぎます。
プロキシを挟むと、ブラウザから見て全部が「5173番の1つのサイト」になります。 別サイトの問題が、最初から発生しません。
本番でも同じ形にします。 nginxのリバースプロキシの回でやったことと、まったく同じ考え方です。手前に1枚立てて、外からは1つに見せる。
2. ログイン画面を作る
~/react-demo/src/Login.tsx を新しく作ります。
import { useState, type FormEvent } from "react";
export type Me = { id: number; email: string };
export default function Login({ onLogin }: { onLogin: (me: Me) => void }) {
const [email, setEmail] = useState("");
const [password, setPassword] = useState("");
const [error, setError] = useState("");
const submit = async (e: FormEvent) => {
e.preventDefault();
setError("");
const res = await fetch("/api/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email, password }),
});
if (!res.ok) {
setError("メールアドレスかパスワードが違います");
return;
}
onLogin(await res.json());
};
return (
<main>
<h1>ログイン</h1>
<form onSubmit={submit}>
<p>
<label htmlFor="email">メールアドレス</label>
<input
id="email"
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
/>
</p>
<p>
<label htmlFor="password">パスワード</label>
<input
id="password"
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
/>
</p>
<button type="submit">ログイン</button>
</form>
{error && <p role="alert">{error}</p>}
</main>
);
}
<label htmlFor> を付けているのは、アクセシビリティの回でやったからです。そして、これがそのままE2Eで効きます。 ⑤で getByLabel("メールアドレス") と書けるのは、このラベルがあるからです。
入力欄が2つに増えました。 ラベルが無いと、
getByRole("textbox")は「2つ見つかった」で落ちます(strictモード)。 テストの回で「2つに増えた瞬間に落ちる。直すのはテストではなくHTMLのほう」と書いた話が、ここで現物になっています。
3. App から、サーバーのタスクを読む
~/react-demo/src/App.tsx を、こう置き換えます。
import { useEffect, useState } from "react";
import Login, { type Me } from "./Login";
import TaskForm from "./TaskForm";
type Task = { id: number; title: string };
export default function App() {
const [me, setMe] = useState<Me | null>(null);
const [tasks, setTasks] = useState<Task[]>([]);
const loadTasks = async () => {
const res = await fetch("/api/tasks");
if (res.status === 401) {
setMe(null);
return;
}
setTasks(await res.json());
};
useEffect(() => {
if (me) loadTasks();
}, [me]);
const addTask = async (title: string) => {
await fetch("/api/tasks", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ title }),
});
await loadTasks();
};
if (!me) return <Login onLogin={setMe} />;
return (
<main>
<h1>タスク</h1>
<p>ログイン中: {me.email}</p>
<TaskForm onAdd={addTask} />
<ul>
{tasks.map((t) => (
<li key={t.id}>{t.title}</li>
))}
</ul>
</main>
);
}
TaskForm は、これまでのものをそのまま使います。 「入力された文字列を onAdd に渡す」という形が同じなら、中身は変えなくて構いません。
ここで、既存のコンポーネントテストが落ちます。
Appを直接描画しているテストは、fetchを呼ぶようになったからです。これは「テストを壊した」のではなく、「Appの責任が変わった」という意味です。 対処は⑩に書きます。 先に進んで構いません。
4. 手で1回、通しておく
E2Eを書く前に、人間の手で1周してください。 手で通らないものを自動化しても、原因が2つになるだけです。
端末を2つ開きます。 1つめ(API)。
2つめ(フロント)。
テスト用のユーザーを、1人作っておきます(3つめの端末か、フロントを止めてからで構いません)。
ホストのWindowsのブラウザで http://192.168.226.50:5173/(IPは自分の値に)を開いて、
- ログインできる
- タスクを追加すると、一覧に出る
- リロードしても消えない(← ここが今回の変化です。DBに入っています)
3つとも通ったら、次へ進みます。 通らないなら、そこはE2Eの問題ではありません。
⑤ 1本目を書く
Playwright に、サーバーを2つとも立てさせます。 「テストの前に手で2つ起動する」は、忘れる日が来ます。そしてCIには手がありません。
設定
~/react-demo/playwright.config.ts を、こう書き換えます(npm init が作ったものを上書きします)。
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./e2e",
timeout: 30_000,
expect: { timeout: 5_000 },
retries: process.env.CI ? 2 : 0,
workers: 1,
reporter: "html",
use: {
baseURL: "http://localhost:5173",
trace: "on-first-retry",
screenshot: "only-on-failure",
video: "retain-on-failure",
},
projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
webServer: [
{
command: "node index.js",
cwd: "../server",
url: "http://localhost:3000/api/tasks",
reuseExistingServer: !process.env.CI,
timeout: 30_000,
},
{
command: "npm run dev -- --port 5173",
url: "http://localhost:5173",
reuseExistingServer: !process.env.CI,
timeout: 60_000,
},
],
});
大事なところだけ。
| 設定 | 意味 |
|---|---|
testDir: "./e2e" | ここだけを見る。 Vitest のテストは拾わない |
baseURL | page.goto("/") の行き先。 テストにホスト名を書かなくて済む |
webServer | テスト前に立てて、終わったら止める。 配列で2つ書けます |
cwd: "../server" | この設定ファイルから見た相対パス。 ~/server を指しています |
url: | そこが応答するまで待つ。 応答したら「立った」と判断する |
reuseExistingServer | すでに立っていたら、それを使う。 手元で開発しながら回すときに効く |
retries: process.env.CI ? 2 : 0 | CIでだけ2回まで再挑戦。 手元では0(⑨で理由を書きます) |
workers: 1 | 同時に1本ずつ。 同じDBを触るので、並列にすると互いに壊し合います |
url: "http://localhost:3000/api/tasks"は、ログインしていないので 401 を返します。 それでも「立った」と判断されます。 Playwright は 2xx・3xx と、401・403 なども「サーバーは応答している」とみなすからです。 「404 だけは駄目」なので、存在するパスを書いてください。
node index.js の部分は、自分の ~/server の起動コマンドに合わせてください。 npm start を用意してあるなら、そちらでも構いません。
テスト本体
~/react-demo/e2e/task-flow.spec.ts を作ります。
import { test, expect } from "@playwright/test";
const EMAIL = "e2e@example.com";
const PASSWORD = "pass12345";
test.beforeEach(async ({ request }) => {
// すでに居れば 409 が返るが、それで構わない
await request.post("/api/users", {
data: { email: EMAIL, password: PASSWORD },
failOnStatusCode: false,
});
});
test("ログインして、タスクを追加すると、一覧に出る", async ({ page }) => {
const title = `牛乳を買う ${Date.now()}`;
await page.goto("/");
await page.getByLabel("メールアドレス").fill(EMAIL);
await page.getByLabel("パスワード").fill(PASSWORD);
await page.getByRole("button", { name: "ログイン" }).click();
await expect(page.getByText(`ログイン中: ${EMAIL}`)).toBeVisible();
await page.getByLabel("やること").fill(title);
await page.getByRole("button", { name: "追加" }).click();
await expect(page.getByRole("listitem").filter({ hasText: title })).toBeVisible();
});
読み方です。
| 行 | 意味 |
|---|---|
test.beforeEach | 各テストの前に走る準備。ここではテスト用ユーザーを作っています |
request | ブラウザを使わずにHTTPを叩く道具。準備や後片づけに使う。baseURL が効くのでプロキシ経由になります |
failOnStatusCode: false | エラー番号が返ってもテストを止めない。 2回目以降は 409(すでにある)です |
page.goto("/") | baseURL と合わせて http://localhost:5173/ を開く |
getByLabel | <label> の文字で入力欄を探す。 ④で付けたラベルです |
getByRole("button", { name: ... }) | テストの回と同じ考え方。 役割と名前で探す |
Date.now() | ⑨で説明します。 ここが「毎回同じ」だと、2回目から落ちます |
getByLabelgetByRoleは、React Testing Library とほぼ同じ名前です。偶然ではありません。 どちらも「利用者から見える形で探す」という同じ思想で作られています。片方を覚えると、もう片方も読めます。
走らせる
Running 1 test using 1 worker
✓ 1 [chromium] › e2e/task-flow.spec.ts:14:1 › ログインして、タスクを追加すると、一覧に出る (3.4s)
1 passed (12.1s)
[スクリーンショット: 02_e2e成功.png] npx playwright test が通った画面を撮ってください。「1 passed」と、かかった秒数が入る形で。
3.4秒です。 テストの回のコンポーネントテストは、2本で1秒もかかりませんでした。②で「高い」と書いたのは、この差のことです。
⑥ なぜE2Eは不安定になるのか
ここが、この記事で一番大事なところです。
E2Eを書き始めると、必ずこの日が来ます。
昨日は通ったのに、今日は落ちた。何も直していないのに。 もう一度走らせたら、通った。
これがフレーキー(flaky)です。 そして原因のほとんどは、待ち方です。
なぜ待つ必要があるのか
ボタンを押してから、一覧に行が増えるまでの間に、こういうことが起きています。
- ブラウザが
POST /api/tasksを送る - サーバーがDBに書く
- サーバーが応答を返す
- ブラウザが
GET /api/tasksを送る - サーバーがDBから読む
- React が状態を更新する
- React が画面を描き直す
これが「速い日」は30ミリ秒、「遅い日」は800ミリ秒かかります。 DBが混んでいるかもしれないし、VMのCPUを他のプロセスが使っているかもしれません。
人間はこの間、勝手に待ちます。 テストは待ちません。 押した次の行を、0.001秒後に実行します。
だから、これをやりたくなります(やってはいけません)
await page.getByRole("button", { name: "追加" }).click();
await page.waitForTimeout(1000); // ← これ
await expect(page.getByText(title)).toBeVisible();
waitForTimeout は、Playwright 版の sleep です。 1秒、何もせずに止まります。
通ります。 その日は。それでも、これは間違いです。理由は2つあります。
| 問題 | 何が起きるか |
|---|---|
| 遅い | 速い日でも必ず1秒待つ。 30ミリ秒で終わっていたものに、1秒払う。10本書けば10秒 |
| それでも落ちる | 遅い日は1秒で足りない。 CIのマシンが混んでいた日、DBが重かった日に落ちる |
そして、落ちたときの直し方が最悪です。
1秒で落ちた → 2秒にする → また落ちた → 5秒にする
テストは遅くなり続け、それでも落ちる日は来ます。 待ち時間の数字は、増やしても解決しません。
数字で待つのが正しいのは、「必ずこの時間かかる」と分かっているものだけです。 通信もDBも、そうではありません。
Playwrightは、ほとんど自動で待つ
ここが Playwright の一番大きい設計です。
await page.getByRole("button", { name: "追加" }).click();
この1行は、押す前に「押せる状態か」を確かめ続けます。
| 確かめること | 意味 |
|---|---|
| DOMにある | まだ描かれていないなら、出てくるまで待つ |
| 見えている(visible) | display: none や高さ0なら、見えるまで待つ |
| 止まっている(stable) | アニメーションで動いている間は押さない。位置が確定するまで待つ |
| 操作を受け取れる | 他の要素に覆われていないか。 モーダルの裏なら待つ |
| 押せる(enabled) | disabled が外れるまで待つ |
条件が揃わないまま既定の時間(30秒)が過ぎると、初めて失敗します。
expect も同じです。
await expect(page.getByText(title)).toBeVisible();
これは「いま出ているか」ではなく、「出るまで、最大5秒、繰り返し確かめる」です。通信もDBも、この中で待たれます。
だから、⑤のテストには待ちが1行も書いてありません。 書く必要が無いからです。
waitForTimeoutを書きたくなったら、ほぼ確実に、書き方のほうが間違っています。
自動待機でも待てないもの
万能ではありません。 自動待機が効かないのは、「待つ対象を指せていない」ときです。
1つめ。「何も起きないこと」を確かめたいとき。
await page.getByRole("button", { name: "追加" }).click();
await expect(page.getByRole("listitem")).toHaveCount(3); // 増えないはず
これは危険です。 「まだ増えていないだけ」でも通ってしまいます。 何も待つものがないからです。
こういうものは、E2Eではなくコンポーネントテストでやります。 ②の表の右側です。
2つめ。画面に出ないもの(DBに入ったか)を確かめたいとき。
画面に出ないものは、画面を見ても待てません。 通信そのものを待ちます。
const [res] = await Promise.all([
page.waitForResponse(
(r) => r.url().includes("/api/tasks") && r.request().method() === "POST"
),
page.getByRole("button", { name: "追加" }).click(),
]);
expect(res.status()).toBe(201);
Promise.all になっているのは、「クリックしてから待つ」では間に合わないからです。押した瞬間に応答が返ってくると、待ち始める前に終わってしまいます。 先に待ち構えてから、押します。
ただし、これを毎回書かないでください。 画面に結果が出るなら、画面で確かめるほうが良いです。通信の形は実装の都合で、classNameでテストしないのと同じ理由で、変わると落ちます。
3つめ。指し示し方が曖昧なとき。
Error: strict mode violation: getByRole('listitem') resolved to 3 elements
これは待ちの問題に見えて、待ちの問題ではありません。 「どれのことか」が決まっていないだけです。Playwrightは、曖昧なまま先頭を勝手に選ぶことをしません。 .filter({ hasText: ... }) や .first() で絞ります。
⑤で .filter({ hasText: title }) を付けているのは、これが理由です。
⑦ 落ちたときに、何を見るか
画面が無いので、「見て確かめる」ができません。 代わりに、Playwright が3つ残してくれます。
| 残るもの | 何が分かるか | 設定 |
|---|---|---|
| スクリーンショット | 落ちた瞬間の画面1枚 | screenshot: "only-on-failure" |
| 動画 | 最初から最後までの動き | video: "retain-on-failure" |
| トレース | 操作・画面・通信・コンソールの全記録 | trace: "on-first-retry" |
トレースが圧倒的に強いです。1ステップごとの画面と、そのときのHTMLと、飛んだ通信が全部入っています。
わざと落とす
テストの最後の行を、通らない形に変えてください。
await expect(page.getByRole("listitem").filter({ hasText: "存在しない文字" })).toBeVisible();
1) [chromium] › e2e/task-flow.spec.ts:14:1 › ログインして、タスクを追加すると、一覧に出る
Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
Locator: getByRole('listitem').filter({ hasText: '存在しない文字' })
Expected: visible
Received: <element(s) not found>
Call log:
- expect.toBeVisible with timeout 5000ms
- waiting for getByRole('listitem').filter({ hasText: '存在しない文字' })
1 failed
[スクリーンショット: 03_失敗の出力.png] 落ちたときの出力を撮ってください。Timed out 5000ms と Call log が入る形で。
読むところは3つです。
| 行 | 意味 |
|---|---|
Timed out 5000ms | 5秒待って、駄目だった。⑥の expect.timeout です |
Locator: | 何を探していたか。ここが自分の想定とずれていることが、かなり多い |
Call log | その間、何をしていたか |
レポートを、ホストのブラウザから見る
テキストだけでは足りません。 HTMLレポートを開きます。ですが、VMにはブラウザがありません。
Playwright は、レポートを見るためのサーバーを持っています。 それを、ホストから見えるように立てます。
Serving HTML report at http://0.0.0.0:9323. Press Ctrl+C to quit.
| 指定 | 意味 |
|---|---|
--host 0.0.0.0 | VMの外からの接続も受ける。 既定は localhost だけで、ホストからは繋がりません |
--port 9323 | 使う番号(既定も9323) |
ホストのWindowsのブラウザで http://192.168.226.50:9323/(IPは自分の値に)を開いてください。
落ちたテストをクリックすると、エラーの下に「スクリーンショット」「動画」が並んでいます。 トレースは、このままでは記録されません。 設定が trace: "on-first-retry"(再挑戦した1回目だけ記録)で、手元は retries: 0 だからです。手元でトレースを見るときは、npx playwright test --trace on で走らせ直してからレポートを開くと、「トレース」も並びます。
[スクリーンショット: 04_レポートをホストで開く.png] ホストのブラウザで開いたレポートの、落ちたテストを展開した画面を撮ってください。
--host 0.0.0.0は「誰でも見られる状態」です。 ネットワークの回でやったとおりです。 学習用のVMなので構いませんが、見終わったらCtrl+Cで止めて、⑪でポートも閉じます。
トレースを開く
レポートの中の「Trace」をクリックすると、そのままトレースビューアが開きます。 左に操作の一覧、上にそのときの画面、下に通信とコンソールが出ます。
見るのは、この順番です。
- どのステップで止まったか(左の一覧の、最後まで行っていないところ)
- そのときの画面(本当に自分が思っている画面が出ているか。ログインできていないことが、かなり多い)
- Network タブ(401 や 500 が飛んでいないか)
[スクリーンショット: 05_トレース.png] トレースビューアで、止まったステップの画面と、Network タブが見える状態を撮ってください。
レポートを立てずにトレースだけ見たいときは、
test-results/の下にあるtrace.zipをVS Code のリモート接続でホストに落として、https://trace.playwright.dev/にドラッグして開けます。 このページはファイルをアップロードしません(ブラウザの中だけで開きます)が、業務のトレースには画面も通信も入っていることは意識してください。
確かめ終わったら、テストを元に戻してください。
⑧ CIに入れる(ただし、毎回は走らせない)
CI/CDの回で作った ci.yml に足します。
まず、正直な前提から。
E2EをCIで動かすには、DBも要ります。 フロントとAPIだけでは、ログインできません。 これが「E2Eは高い」のもう1つの意味です。用意するものが、いきなり増えます。
GitHub Actions には、そのための仕組みがあります。
e2e:
runs-on: ubuntu-latest
services:
mysql:
image: mysql:8
env:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: taskdb
ports:
- 3306:3306
options: >-
--health-cmd="mysqladmin ping -h 127.0.0.1"
--health-interval=10s
--health-timeout=5s
--health-retries=5
steps:
- name: コードを取得する
uses: actions/checkout@v4
- name: Node.js を用意する
uses: actions/setup-node@v4
with:
node-version: '22'
- name: サーバー側の依存を入れる
run: npm ci
- name: フロント側の依存を入れる
run: npm ci
working-directory: web
- name: ブラウザと依存を入れる
run: npx playwright install --with-deps chromium
working-directory: web
- name: E2Eを走らせる
run: npx playwright test
working-directory: web
- name: レポートを残す
if: ${{ !cancelled() }}
uses: actions/upload-artifact@v4
with:
name: playwright-report
path: web/playwright-report/
retention-days: 7
大事なところ。
| 行 | 意味 |
|---|---|
services: | そのジョブの間だけ、コンテナでMySQLを立てる。Dockerの回で使ったイメージと同じものです |
--health-cmd | 立ち上がるまで待つ。 ⑥と同じ話で、sleep 30 で待たせない |
--with-deps | CIのマシンは毎回まっさらなので、③でやったことを毎回やる。ここは sudo が要らない(rootで動いているため) |
if: ${{ !cancelled() }} | 落ちてもレポートを残す。 「成功したときだけ残す」では、一番見たいときに残りません |
upload-artifact | 実行結果のファイルを持ち帰る。GitHubの実行画面からダウンロードして、⑦と同じように開けます |
~/react-demo/ はまだGitHubに上げていないので、これは「上げたときにこう書く」という形です。 リポジトリを分けるなら、フロント側に e2e.yml を1本置くだけです。その場合、APIを立てる webServer の cwd: "../server" は届かなくなるので、APIもコンテナで立てるか、リポジトリを1つにまとめるかを選ぶことになります。
毎回は走らせない
E2EをCIに入れると、git push のたびに数分待つことになります。 待ち時間が長いCIは、そのうち結果を見なくなります。
選択肢は3つです。
| 書き方 | いつ走るか | 向いている場面 |
|---|---|---|
on: pull_request だけ | プルリクを出したときだけ | これが基本。 作業中のpushでは走らない |
on: schedule(cron) | 1日1回など、決まった時刻 | 遅いテストを、寝ている間に回す |
on: workflow_dispatch | ボタンを押したときだけ | 手元で確認できるなら、これで十分 |
on:
pull_request:
branches: [main]
schedule:
- cron: '0 21 * * *'
workflow_dispatch:
cron: '0 21 * * *'は UTC の21時、つまり日本時間の朝6時です。GitHub Actions の時刻はUTCなので、9時間ずれます。
ユニットとコンポーネントのテストは、いままでどおり毎pushで走らせてください。 速いからです。速いものは全部走らせ、遅いものは回数を絞る。 これが分け方です。
⑨ やりすぎない — E2Eを増やすと、開発が止まる
1本書けると、次を書きたくなります。 そこで止まってください。
E2Eを10本、20本と増やすと、こうなります。
- CIが10分かかるようになる。プルリクを出してから、結果を見るまでコーヒーを淹れに行く
- 文言を1つ変えると、5本落ちる。アプリは正しいのに、テストを5本直す仕事が発生する
- 週に1本、理由の分からない失敗が出る。「もう一回走らせて」が口癖になる
- そして、誰も赤いCIを見なくなる
テストは、開発を速くするために書くものです。 遅くしているなら、それは目的を裏切っています。
増やす前に確かめること
1. そのテスト、コンポーネントテストで足りませんか
「複数のシステムをまたぐか」だけを基準にしてください。画面の中で完結する話なら、E2Eにする理由はありません。
2. そのテストは、単独で走りますか
⑤で Date.now() を付けた理由が、これです。
const title = `牛乳を買う ${Date.now()}`;
毎回同じタイトルにすると、2回目からDBに2件たまります。 すると getByText("牛乳を買う") は2つ見つかって、⑥の strict mode violation で落ちます。
「1回目は通るのに、2回目から落ちる」テストは、フレーキーの入口です。 原因は待ち方ではなく、前の実行の残りかすです。E2Eは本物のDBに書くので、これが必ず起きます。
対処は3つあり、上ほど簡単です。
| やり方 | 内容 |
|---|---|
| 毎回違うデータを使う | Date.now() や乱数を混ぜる。この記事のやり方 |
| テストの終わりに消す | test.afterEach で request.delete(...) を呼ぶ |
| DBごと作り直す | CIならこれが一番きれい。手元では重い |
3. リトライを「解決」だと思っていませんか
retries: 2 は、フレーキーを直しません。隠します。
それでもCIで2にしているのは、「CIのマシンが混んでいた」のような、自分ではどうにもならない揺れがあるからです。手元を 0 にしているのは、隠したくないからです。手元で落ちるなら、それは直すべき何かです。
レポートに「flaky」と出たら、それは「通った」ではありません。 1回目に落ちたという記録です。放置すると、いつか2回とも落ちる日が来ます。
次に増やすとしたら
この記事のあと、増やす価値があるのは、たとえばこの2本くらいです。
- ログインしていない状態でトップを開くと、ログイン画面が出る(守られていることの確認)
- 間違ったパスワードでは入れない(認証が本当に効いていることの確認)
それ以上は、「サービスが成立しない流れ」が増えたときに、増やしてください。
⑩ つまずいたところ
Executable doesn't exist at /root/.cache/ms-playwright/chromium-.../chrome → sudo npx playwright install をやってしまっています。 ③のとおり、ブラウザ本体に sudo は要りません。 sudo 無しで npx playwright install chromium をやり直してください。/root/ の下のものは、sudo rm -rf /root/.cache/ms-playwright で消せます(消さなくても害はありません)。
Host system is missing dependencies to run browsers → install-deps をやっていません。 sudo npx playwright install-deps chromium を実行してください。足りないライブラリ名が一覧で出ているので、それを読むのが一番早いです。
Error: Looks like you launched a headed browser without having a XServer running. → --headed を付けています。 画面の無いVMでは使えません。 外して、⑦のレポートで見てください。
Error: Process from config.webServer exited early. → webServer の command か cwd が違います。 そのコマンドを、自分で手打ちして動くか確かめてください。 ~/server の起動が node index.js ではないかもしれません。DBが止まっていて、APIが起動と同時に落ちていることもあります。
Timed out waiting 30000ms from config.webServer → 立ってはいるが、url: に応答していません。 そのURLに curl -i で叩いて、何が返るか見てください。 404が返っていたら、そのパスは存在しません(⑤の注意)。
strict mode violation: ... resolved to 2 elements → 指し示し方が曖昧です。 待ちの問題ではありません。 .filter({ hasText: ... }) で絞るか、同じ文字が2回出ている理由(前回の残りかす)を疑ってください。⑨です。
ログインの expect で落ちる。トレースを見ると、画面がログイン画面のまま → Cookieが保存されていません。 ④のプロキシ設定が効いていない可能性が高いです。npm run dev を、設定を変えたあとに起動し直しましたか。 vite.config.ts の変更は、動いているサーバーには反映されません。
既存のコンポーネントテスト(Vitest)が落ちるようになった → ④で App が fetch を呼ぶようになったからです。これは想定どおりの結果です。対処は2つ。
Appごと描画するのをやめて、TaskFormだけを描画するテストに切る(おすすめ)fetchを偽物に差し替える
import { vi, beforeEach } from "vitest";
beforeEach(() => {
vi.stubGlobal("fetch", vi.fn(async () => new Response("[]", { status: 200 })));
});
偽物に差し替えると、「本物とずれていても気づかない」という弱点が生まれます。 ①でE2Eが必要だと書いたのは、まさにこの穴を埋めるためです。両方あって、初めて意味があります。
npm test が Playwright のテストを実行しようとして落ちる → testDir を e2e にしていないか、Vitest 側が e2e/ を拾っています。 vite.config.ts の test に、除外を足してください。
test: {
environment: "jsdom",
globals: true,
setupFiles: "./src/setupTests.ts",
exclude: ["**/node_modules/**", "**/e2e/**"],
},
⑪ 後片づけ
開けたポートを閉じます。
溜まった実行結果を消します(次に走らせれば、また作られます)。
.gitignore に入っているか確かめてください。 npm init playwright@latest が足しているはずですが、入っていないと、動画とスクリーンショットをGitHubに上げることになります。
node_modules/
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
DBに溜まったテスト用のタスクは、消しておいて構いません。 ログインして、画面から消すのが一番簡単です。
消さないでください。
~/react-demo/と~/server/— この先も使います~/.cache/ms-playwright/— 消すと、次に走らせるとき170MBを入れ直しになります
Playwright ごとやめたくなったときだけ、これです。
⑫ まとめ
- コンポーネントテストとE2Eは、規模ではなく場所が違う。 前者は偽物のDOMの中、後者は本物のブラウザが本物のサーバーとDBを叩く
- だからE2Eだけが「繋がっていない」を見つけられる。 URLの間違い、Cookieが飛ばない、要素が隠れている。どれも
jsdomでは通ってしまう - E2Eは高い。 遅い・壊れやすい・原因の候補が多い。だから「全部書く」ではなく「何をE2Eにするか選ぶ」が本体
- 選ぶ基準は「複数のシステムをまたぐか」。 画面の中で完結する条件分岐は、コンポーネントテストのほうが速くて原因も分かる
- 画面の無いVMでも、ヘッドレスなら動く。 ヘッドレスは別のソフトではなく、描画だけしないブラウザ
install-depsにはsudoが要り、installには要らない。sudoを付けると/root/に入って、テストから見えなくなるsleep(waitForTimeout)で待たない。 速い日も必ず待たされ、遅い日は結局落ちる。 数字を増やしても解決しない- Playwright は、クリックの前に「押せる状態か」を待ち、
expectは「そうなるまで」繰り返す。 だから待ちを書く必要がない - 自動待機が効かないのは、「待つ対象を指せていない」とき。 「何も起きないこと」と「画面に出ないこと」は、待てない
- 落ちたら、トレースを見る。 止まったステップ / そのときの画面 / Networkタブ の3つを、この順で
- 画面が無くても、レポートは
--host 0.0.0.0でホストから開ける。 見終わったらポートを閉じる - CIでは、DBまで用意することになる。 これも「E2Eは高い」の一部
- 遅いテストを毎pushで走らせない。 プルリクだけ・1日1回・手動ボタンという選択肢がある
- 「1回目は通るのに2回目から落ちる」は、待ちではなく前の実行の残りかす。 毎回違うデータを使う
- リトライはフレーキーを直さない。隠す。 手元は
0にして、隠さない - E2Eを増やすと開発が止まる。 テストは開発を速くするために書くもので、遅くしているなら目的を裏切っている
参考リンク
- roadmap.sh — Frontend(Testing の項目)
- Playwright 公式
- Playwright — Installation
- Playwright — Auto-waiting(Actionability)
- Playwright — Locators
- Playwright — Web server
- Playwright — Trace viewer
- Playwright — Continuous Integration
- トレースビューア(ブラウザ版)
- GitHub Actions — サービスコンテナ
- Vite — server.proxy
次に読む
この記事は 【第4段階】フロントエンド の 13 / 15 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。

コメント