E2Eはsleepで待たない — Playwrightで1本目

PlaywrightでE2Eテスト。ブラウザの画面と操作カーソル、順に並ぶチェック付きのテストカード。

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本増やすたびに、毎回の待ち時間と「意味のない失敗」が増える

この記事でやること

  1. 画面の無いVMに Playwright を入れる(npm init playwright@latest と、--with-deps が何をしているか)
  2. フロントとAPIを繋ぐ。E2Eの対象がまだ無いので、ログイン画面とAPI呼び出しを最小限だけ足す
  3. 1本目を書く。ログインして、タスクを追加して、一覧に出るまで。サーバーは Playwright に立てさせる
  4. わざと不安定にして、直す。waitForTimeout を入れてみて、なぜ駄目なのかを出力で確かめる
  5. わざと落として、トレースを見る。ホストのWindowsのブラウザからレポートを開く
  6. CIに足す。ただし毎回は走らせない書き方も用意する

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
E2E(End to End)端から端まで。画面を操作して、サーバーとデータベースまで通して確かめるテスト
Playwright本物のブラウザを操作してテストする道具。Microsoft 製
ヘッドレス(headless)画面を描かずにブラウザを動かすこと。ウィンドウが出ないだけで、中身は同じブラウザ
ロケータ(Locator)「画面のこの要素」を指す指し示し方。page.getByRole(...) などが返すもの
自動待機(auto-waiting)クリックする前に、押せる状態になるまで Playwright が勝手に待つ仕組み
フレーキー(flaky)同じコードなのに、通ったり落ちたりするテストのこと。E2Eの最大の敵
リトライ(retry)落ちたテストを、もう一度だけ走らせ直す設定
トレース(trace)テストの実行中に起きたこと全部の記録。操作・画面・通信・コンソールが時系列で入っている
webServerテストを始める前に、Playwright にサーバーを立てさせる設定
baseURLpage.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/ に入って実行します。

bash
$ cd ~/react-demo
$ npm init playwright@latest

対話で4つ聞かれます。 答えはこれです。

質問答え理由
TypeScript / JavaScriptTypeScript前々回で ~/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 ではありません。

依存ライブラリを入れる

bash
$ sudo npx playwright install-deps chromium

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がそれらを前提に作られているからです。「ブラウザだけ入れれば動く」ではないのは、こういう理由です。

ブラウザ本体を入れる

ここが、この記事で一番やりがちな事故です。

bash
$ npx playwright install chromium

sudo を付けないでください。 ブラウザ本体は「あなたのホームの下」(~/.cache/ms-playwright/)に入ります。 sudo を付けると /root/ の下に入り、テストを普通のユーザーで走らせたときに「実行ファイルが無い」と言われます。

まとめると、こうなります。

コマンドsudo入る場所
playwright install-deps要るシステム全体(apt)
playwright install要らない自分のホームの下

npx playwright install --with-deps chromium は、この2つをまとめてやってくれます。 便利ですが、中で sudo を呼ぶので、パスワードを聞かれるタイミングが分かりにくいです。最初の1回は、分けたほうが何が起きたか見えます。

入ったか確かめる

bash
$ npx playwright --version
$ du -sh ~/.cache/ms-playwright/
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 だけにします。

戻し方

やめたくなったら、これで消えます。

bash
$ npx playwright uninstall --all

apt で入れたライブラリはそのまま残ります。 害はありませんが、気になるなら sudo apt autoremove で不要になったものだけ落ちます。

使えないもの(先に知っておく)

画面が無いので、Playwright の便利機能のうち2つは、このVMでは使えません。

使えないもの何をするものだったか代わりにやること
--headedブラウザのウィンドウを出して、動くところを目で見るトレースと動画(⑦)
--uiUIモード。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)。

bash
$ cd ~/server
$ node index.js

2つめ(フロント)。

bash
$ cd ~/react-demo
$ npm run dev -- --host 0.0.0.0

テスト用のユーザーを、1人作っておきます(3つめの端末か、フロントを止めてからで構いません)。

bash
$ curl -s -X POST http://localhost:3000/api/users \
    -H "Content-Type: application/json" \
    -d '{"email":"e2e@example.com","password":"pass12345"}'

ホストのWindowsのブラウザで http://192.168.226.50:5173/(IPは自分の値に)を開いて、

  1. ログインできる
  2. タスクを追加すると、一覧に出る
  3. リロードしても消えない(← ここが今回の変化です。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 のテストは拾わない
baseURLpage.goto("/") の行き先。 テストにホスト名を書かなくて済む
webServerテスト前に立てて、終わったら止める。 配列で2つ書けます
cwd: "../server"この設定ファイルから見た相対パス。 ~/server を指しています
url:そこが応答するまで待つ。 応答したら「立った」と判断する
reuseExistingServerすでに立っていたら、それを使う。 手元で開発しながら回すときに効く
retries: process.env.CI ? 2 : 0CIでだけ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回目から落ちます

getByLabel getByRole は、React Testing Library とほぼ同じ名前です。偶然ではありません。 どちらも「利用者から見える形で探す」という同じ思想で作られています。片方を覚えると、もう片方も読めます。

走らせる

bash
$ cd ~/react-demo
$ npx playwright test
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)です。 そして原因のほとんどは、待ち方です。

なぜ待つ必要があるのか

ボタンを押してから、一覧に行が増えるまでの間に、こういうことが起きています。

  1. ブラウザが POST /api/tasks を送る
  2. サーバーがDBに書く
  3. サーバーが応答を返す
  4. ブラウザが GET /api/tasks を送る
  5. サーバーがDBから読む
  6. React が状態を更新する
  7. 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();
bash
$ npx playwright test
  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 5000ms5秒待って、駄目だった。⑥の expect.timeout です
Locator:何を探していたか。ここが自分の想定とずれていることが、かなり多い
Call logその間、何をしていたか

レポートを、ホストのブラウザから見る

テキストだけでは足りません。 HTMLレポートを開きます。ですが、VMにはブラウザがありません。

Playwright は、レポートを見るためのサーバーを持っています。 それを、ホストから見えるように立てます。

bash
$ sudo ufw allow 9323/tcp
$ npx playwright show-report --host 0.0.0.0 --port 9323
  Serving HTML report at http://0.0.0.0:9323. Press Ctrl+C to quit.
指定意味
--host 0.0.0.0VMの外からの接続も受ける。 既定は 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」をクリックすると、そのままトレースビューアが開きます。 左に操作の一覧、上にそのときの画面、下に通信とコンソールが出ます。

見るのは、この順番です。

  1. どのステップで止まったか(左の一覧の、最後まで行っていないところ)
  2. そのときの画面(本当に自分が思っている画面が出ているか。ログインできていないことが、かなり多い)
  3. 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-depsCIのマシンは毎回まっさらなので、③でやったことを毎回やる。ここは 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/**"],
},

⑪ 後片づけ

開けたポートを閉じます。

bash
$ sudo ufw delete allow 9323/tcp
$ sudo ufw status

溜まった実行結果を消します(次に走らせれば、また作られます)。

bash
$ cd ~/react-demo
$ rm -rf test-results playwright-report

.gitignore に入っているか確かめてください。 npm init playwright@latest が足しているはずですが、入っていないと、動画とスクリーンショットをGitHubに上げることになります。

bash
$ cat ~/react-demo/.gitignore
node_modules/
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/

DBに溜まったテスト用のタスクは、消しておいて構いません。 ログインして、画面から消すのが一番簡単です。

消さないでください。

  • ~/react-demo/ と ~/server/ — この先も使います
  • ~/.cache/ms-playwright/ — 消すと、次に走らせるとき170MBを入れ直しになります

Playwright ごとやめたくなったときだけ、これです。

bash
$ npx playwright uninstall --all
$ npm uninstall @playwright/test

⑫ まとめ

  • コンポーネントテストと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を増やすと開発が止まる。 テストは開発を速くするために書くもので、遅くしているなら目的を裏切っている

参考リンク


次に読む

この記事は 【第4段階】フロントエンド の 13 / 15 本目です。

記事
← 前の記事node_modulesが重い理由 — pnpmとBunを測る
→ 次の記事curlで取ると中身が空 — SSRとNext.js

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Frontend›Testing
  • Playwright
  • E2E テスト
  • 待ち方(自動待機)

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次