E2E テストの設計と安定化

E2E（End to End）テストは、ブラウザやアプリを実際に操作して、利用者の流れを通しで確かめるテストです。Web では Playwright や Cypress、Selenium などを使います。最も利用者に近い確かめ方ですが、遅くて不安定になりやすいので、設計の工夫が欠かせません。

E2E で確かめるのは、ログイン・検索・購入のような主要な流れに絞ります。入力のパターンの違いなど細かい確認は、API や単体のテストに任せます。

Page Object は、画面ごとに「どこに何があるか」と「できる操作」をまとめたクラスを作る設計です。テスト本体は「何を確かめるか」だけを書き、画面が変わったときは Page Object の1か所を直せば済みます。

// pages/login.ts
export class LoginPage {
  constructor(private page: Page) {}
  async login(email: string, password: string) {
    await this.page.getByLabel('メールアドレス').fill(email);
    await this.page.getByLabel('パスワード').fill(password);
    await this.page.getByRole('button', { name: 'ログイン' }).click();
  }
}

// tests/login.spec.ts
test('正しいパスワードでログインできる', async ({ page }) => {
  await page.goto('/login');
  await new LoginPage(page).login('qa1@example.com', 'correct-pass');
  await expect(page.getByRole('heading', { name: 'マイページ' })).toBeVisible();
});

Page Object には「確認」を書かず、操作と要素の場所だけを持たせるのが一般的です。確認はテスト本体に書くと、何を確かめているかが読みやすくなります。

要素は、見た目や構造で変わりやすい CSS のクラス名より、役割と名前（getByRole・getByLabel）や、テスト用の目印（data-testid）で探すと壊れにくくなります。

役割と名前で探せないときは、アクセシビリティの問題（ボタンに名前がない）であることも多いです。テストを書きながら、そうした問題も報告できます。

E2E が不安定になる一番の原因は待ち方です。表示や通信が終わる前に操作・確認すると、速い日は通り、遅い日は落ちます。固定の時間を待つ sleep ではなく、条件がそろうまで待つようにします。

// 悪い例：3 秒待ってから確かめる
await page.waitForTimeout(3000);
expect(await page.textContent('.msg')).toBe('保存しました');

// 良い例：表示されるまで再試行しながら待つ
await expect(page.getByText('保存しました')).toBeVisible();

Playwright は、クリックなどの操作の前に、要素が表示され操作できる状態になるまで自動で待ちます（自動待機）。expect の確認も、条件を満たすまで一定時間くり返し試します。この仕組みに任せて、自分で sleep を書かないのが基本です。

コードを変えていないのに、通ったり落ちたりするテストを flaky（フレーキー）と呼びます。放っておくと「どうせまた落ちただけ」と本物の不具合まで見逃すので、原因を分類して直します。

失敗したときのスクリーンショット・動画・トレース（Playwright の Trace Viewer）を残すと原因を探しやすくなります。自動の再実行（Playwright の retries。既定は 0 回）は CI だけで1〜2回までにとどめることが多く、「再実行で通ったテスト」は一覧にして直す対象にします。直せないものは一時的に外し（隔離）、期限を決めて直します。

すべてのテストで画面からログインすると、時間がかかり、ログイン画面の不具合で全部のテストが落ちます。ログインは最初に1回だけ行い、その状態を使い回します。

Playwright では、準備用のプロジェクトでログインし、Cookie などの状態（storageState）をファイルに保存して、各テストはそのファイルを読み込んで始められます。ログイン画面そのもののテストは、別に数本だけ書きます。

確かめたいこと以外は画面を通さない、が E2E を速く安定させるこつです。

「サーバーが 500 を返したときの表示」「0 件のときの表示」を本物の環境で作るのは大変です。E2E の道具の機能で、ブラウザの通信を途中で差し替えて偽の応答を返すと、簡単に再現できます。

test('注文の API が失敗したらエラーを表示する', async ({ page }) => {
  await page.route('**/api/orders', (route) =>
    route.fulfill({ status: 500, body: '{}' }));
  await page.goto('/cart');
  await page.getByRole('button', { name: '注文する' }).click();
  await expect(page.getByText('時間をおいて再度お試しください')).toBeVisible();
});

エラー・空・遅い応答など、画面の異常系の表示をまとめて確かめられます。ただし、差し替えたテストは本物の API の不具合は見つけられないので、主要な流れは本物とつないだ E2E でも確かめます。

ビジュアル回帰テストは、画面のスクリーンショットを前回の基準の画像と比べ、見た目が意図せず変わっていないかを確かめるテストです。CSS の変更で別の画面が崩れた、のような、機能のテストでは見つからない不具合に向きます。

Playwright では await expect(page).toHaveScreenshot(); で比べられ、意図した変更のときは --update-snapshots を付けて流すと基準の画像を更新できます。