Playwright Flaky Test完全ガイド｜原因の切り分けとAuto-waiting・Locator・Trace Viewerでの解決策

Playwright は Auto-waiting 機能により Selenium と比べて Flaky Test（不安定なテスト）が起きにくいと言われますが、それでもゼロにはなりません。「ローカルでは通るのにCIだけ落ちる」「たまに失敗するが再実行すると通る」——こうした症状に悩むQAエンジニアは少なくありません。この記事では、Playwright特有のFlaky Testの原因を切り分け、Auto-waiting・Locator設計・Trace Viewerを使った解決策を実務目線で解説します。

Flaky Test を「たまたま」で片付けてリトライだけに頼ると、根本原因が積み重なってテストスイート全体の信頼性が下がっていきます。原因を切り分けて直す習慣が、長期的にはリトライより効果的です。

Playwright は Selenium に比べて Flaky Test が起きにくい設計になっていますが、次のような症状は珍しくありません。

• ローカルでは毎回通るのに、CI環境だけ時々失敗する
• 同じテストを再実行すると通ってしまい、原因を特定できない
• アニメーションが絡む画面でクリックが失敗する
• 並列実行を有効にすると失敗率が上がる

この記事では、これらの症状を引き起こす原因を切り分け、それぞれの解決策を順番に見ていきます。

Flaky Testとは？なぜPlaywrightでも起きるのか

Flaky Testとは、コードやテスト対象の仕様に変更がないにもかかわらず、実行するたびに成功したり失敗したりするテストのことです。

Playwright は Selenium と比較して Auto-waiting（要素が操作可能になるまで自動的に待機する仕組み）が組み込まれているため、明示的な待機処理を書き忘れることによる Flaky Test は大幅に減ります。ただし、これは「待機処理を考えなくていい」という意味ではありません。Auto-waiting がカバーする範囲とカバーしない範囲を理解していないと、依然として Flaky Test は発生します。

Playwright特有のFlaky Test原因 4パターン

実務でよく遭遇する原因を4つに分類しました。まずはどのパターンに該当するかを切り分けることが解決の第一歩です。

① Auto-waitingを正しく理解する

Playwright は要素を操作する前に、以下の Actionability checks（操作可能性チェック）を自動的に行います。

つまり Playwright がカバーしているのは「要素が操作可能な状態になるまで」の待機であり、以下のようなケースは Auto-waiting の範囲外です。

• ボタンをクリックした後、非同期でAPIが呼ばれてデータが反映されるまでの待機
• 要素は表示されているが、内部の値がまだ更新されていない状態の判定
• ページ遷移後、目的の要素が読み込まれるまでの待機（これは通常自動でカバーされるが、SPAの複雑な遷移では注意が必要）

❌ よくある誤り：sleepで無理やり待つ

import time
from playwright.sync_api import Page

def test_add_to_cart_bad(page: Page) -> None:
    page.goto("/products/1")
    page.get_by_role("button", name="カートに追加").click()

    # ❌ 固定時間の sleep はCI環境の遅延に弱く、Flaky Testの温床になる
    time.sleep(2)

    assert page.get_by_text("カートに追加しました").is_visible()

✅ 改善例：expect() の自動リトライアサーションを使う

from playwright.sync_api import Page, expect

def test_add_to_cart_good(page: Page) -> None:
    page.goto("/products/1")
    page.get_by_role("button", name="カートに追加").click()

    # ✅ 条件を満たすまで自動的にリトライしながら確認する
    expect(page.get_by_text("カートに追加しました")).to_be_visible()

② 安定したLocatorを選ぶ

CSS セレクタや XPath は、デザイン変更やクラス名のリファクタリングだけで簡単に壊れます。Playwright は ユーザー視点のLocator（role・label・text）を推奨しており、これらは実装の詳細変更に強い傾向があります。

❌ 不安定な例：CSSクラスに依存

# ❌ CSSクラス名はスタイル変更のたびに壊れるリスクがある
page.locator(".btn.btn-primary.submit-btn-v2").click()

✅ 安定した例：role ベース

# ✅ ユーザーが見る役割・名前に基づくため、内部実装の変更に強い
page.get_by_role("button", name="送信").click()

③ タイムアウト設定を見直す

Playwright には複数の階層のタイムアウトが存在します。それぞれの役割を理解しておくと、原因調査がしやすくなります。

タイムアウトを個別に指定する例

from playwright.sync_api import Page, expect

def test_slow_api_response(page: Page) -> None:
    page.goto("/reports")
    page.get_by_role("button", name="レポート生成").click()

    # API応答が遅いことがわかっている場合、個別にタイムアウトを延長する
    # ms（ミリ秒）指定であることに注意
    expect(page.get_by_text("生成完了")).to_be_visible(timeout=60_000)

④ pytest-rerunfailures でリトライする（応急処置として）

根本原因の特定・修正が理想ですが、リリース直前などですぐに対応しきれない場合、リトライで一時的に緩和する選択肢もあります。ただし、これは pytest 標準機能ではなく pytest-rerunfailures というプラグインに依存する点に注意してください。

インストール

pip install pytest-rerunfailures

使い方

# CLIオプションで全体に適用する場合
# 失敗したテストを最大3回まで再実行し、再実行の間は2秒待機する
pytest --reruns 3 --reruns-delay 2

特定のテストにだけ適用したい場合は、@pytest.mark.flaky をデコレータとして関数に付与します。

import pytest
from playwright.sync_api import Page

@pytest.mark.flaky(reruns=3, reruns_delay=2)
def test_login(page: Page) -> None:
    page.goto("/login")
    # ... テスト処理 ...

⑤ Trace Viewer で原因を特定する

「CIだけ失敗する」「たまに失敗する」といった再現性の低い Flaky Test の原因調査には、Trace Viewer が特に有効です。テスト実行時の操作・スクリーンショット・ネットワークログ・コンソールログを1ファイルにまとめて記録できます。

※ 以下は pytest-playwright プラグインを利用している場合の例です。

失敗時のみTraceを保存する

# 失敗時のみ Trace を保存する（pytest-playwright プラグイン使用時）
pytest --tracing retain-on-failure

# 保存された trace.zip をブラウザで確認する
playwright show-trace trace.zip

Trace Viewer で確認すべきポイント

CI/CD特有の原因と対策

「ローカルでは再現しないがCIだけ失敗する」場合、CI環境特有の要因を疑う必要があります。GitHub Actions の設定自体が原因になっていないかも合わせて確認すると効率的です（詳しくはGitHub Actions で Playwright を CI/CD に組み込むガイドを参照）。

実務でよくある失敗パターン

FAQ

📋 まとめ

Flaky Test は「たまたま」で終わらせず、原因を切り分けて一つずつ潰していくことで、テストスイート全体の信頼性が積み上がっていきます。まずは Trace Viewer を有効にして、失敗時の記録を残す仕組みから始めてみてください。