E2EのフロントテストでPlaywrightを使うことを決めた話 #7. 安定化テクニックを早期に吸収する

Playwrightは、GUIも含めて環境設定ができたら、どんどん使い進めていくことができます。 でも、最初はどうやるか悩み込んでしまうこともあり、実際にセットをしても安定的に動作しない・・・なんてことも起こりがちです。 と言うことで、今回は安定化をするテクニックと、早い段階でそれを習得する理由を解説したいと思います。

安定化テクニックを早期に吸収する理由

テストが安定しない最大の原因は「待ち」の理解不足と言うのがあります。 Playwright は“自動待機”が強力だが、全部任せると不安定になることがあるんですよね。 UI特有の「描画が遅い」「アニメーション中」「XHR のタイミングずれ」により、テストが落ちるのは、経験者であれば誰もが体験ずみだと思います。 初期段階で「待つべきポイント」を理解しておくと、後々大規模化しても壊れにくくなるハズです。

早期に身につけるべき「安定化テクニック」

以下のポイントを覚えておくと、使いはじめの早期の段階で、テスト実行が安定するでしょう。

明示的に特定要素を wait

await page.waitForSelector('css') // ロケーターベースなら await locator.waitFor() 自動待機は便利なんだけど“待つタイミングを宣言しておく”と言うのが一番安定化につながります。

APIレスポンス待ち (waitForResponse / expect API)

SPA では UI変化より先に"APIの完了"を待つほうが安定します。 await page.waitForResponse(res => res.url().includes('/api/submit') && res.ok());

URL遷移を待つ（期待するURLを明示）

await expect(page).toHaveURL(/dashboard/) goto → click → 移動 の順のシーケンスで、URLチェックの安定度を稼ぐ鉄板の手段です。

Locator を使って「意図した要素だけ」を掴む

CSS だけに依存すると要素がずれて誤クリックすることがあリマス。 getByRole, getByText, getByLabel, getByPlaceholder などの、意味的な掴み方を優先すると、多少のDOMが変更されてもテストを継続することができます。

timeout の調整とデフォルト依存しない

デフォルト 30 秒は長すぎ／短すぎになる場合があります。 テストごとに適切な timeoutを設定すると安定しや少なるんです。 test.setTimeout(10_000); await page.getByRole('button', { name: '保存' }).click({ timeout: 5000 });

モーダル・アニメーション対策

モーダル表示/非表示で落ちるなら「表示されるまで待つ」「消えるまで待つ」を明示すると安定します。 const modal = page.getByRole('dialog'); await expect(modal).toBeVisible(); await expect(modal).not.toBeVisible();

テストデータは“状態固定”にする

前回の実行のゴミデータで、UIが変わって落ちることがあります。 テスト開始前に"DBリセット" または "fixturesを再投入する"と言う構造にすると安定します。

あとがき

早期に安定テクニックを覚えることができたら、初期の頃の書き方が全テストのテンプレになります。 逆に言うと、安定しないコードを書いてしまうと、その後の修正作業はかなりの地獄になりかねません。 テストコードの書き直しって、書き直すよりも、新しく作り直すほうが早いと思われてしまうんですよね。 今回の安定化テクニックは、要するに「待ち」を理解するという事に尽きると言ってもいいかもしれません。 安定する待ちスキルを習得して、安定テストを学習早期の段階で習得しましょう！