Flakyテスト地獄から脱出する方法｜原因5分類・診断から再発防止まで解説

「テストが落ちても本当のバグかどうかわからない」「CIが赤くても誰も気にしなくなった」——そのFlakyテスト地獄から脱出する方法を、原因分類・診断・対策・再発防止まで実務経験をもとに解説します。Wait設計・環境差異・データ競合・外部依存など、Flakyの種類別に優先順位付きで対策を紹介します。

Flakyテストの本当の怖さは「テストが落ちること」ではなく、「テスト結果を誰も信頼しなくなること」です。

「またFlakyか」——その一言が日常になったとき、テスト自動化は機能を失っています。CIが赤くても「どうせFlakyだろう」とリランするだけ。本当のバグを見逃すリスクが高まり、やがて誰もテスト結果を信頼しなくなります。

この記事ではFlakyテストを「なんとなく直す」のではなく、原因を種類ごとに分類して体系的に脱出する方法を解説します。

Flakyテストとは何か？なぜ危険なのか

Flakyテスト（Flaky Test）とは、「同じコードで同じ環境のはずなのに、実行するたびに合否が変わる不安定なテスト」のことです。

Flakyが危険なのは、テストが落ちること自体よりも「テスト結果への信頼が失われること」にあります。

Flakyテストの種類と根本原因とは？5分類

Flakyテストを「なんとなく不安定」で片付けると永遠に直りません。まずどの種類のFlakyかを特定することが根本解決の第一歩です。

まずここを確認：症状からFlakyの種類を診断するとは？

「うちのFlakyはどの種類？」——この表で症状から診断してください。原因の種類が分かれば、対策のSTEPに直接ジャンプできます。

STEP 1：まずFlakyを計測・可視化するとは？

「直す前にまず数える」——これが地獄脱出の最初のステップです。感覚ではなくデータとして把握することで、どこから手をつけるかの優先順位が決まります。

計測すべき3つの指標

# pytest-repeat を使って同じテストを複数回実行し、Flaky率を計測する
# ⚠️ pytest標準機能ではありません。事前にプラグインのインストールが必要です
# pip install pytest-repeat

# 5回繰り返し実行（Flakyなら数回に1回失敗する）
# ※ CI組み込み時は実行時間が増えるため、Flaky調査用途での限定使用を推奨
pytest tests/test_login.py --count=5

# 結果例：5回中2回失敗 → Flaky率40%（要対処）
# PASSED（3回）FAILED（2回）

# GitHub Actions のCI結果を集計してFlaky率を可視化する場合
# pytest --junitxml=results.xml で結果を保存
# Datadog / Grafana / Allure Report / ReportPortal などに取り込むと長期トレンドが見やすい

STEP 2：① Wait系Flakyの対策とは？

最も多く、比較的直しやすいFlakyです（SPAやvirtual DOM環境では難化する場合もあります）。「要素が見つからない」「クリックできない」は、要素の表示・操作可能状態を正しく待てていないことが原因です。

Selenium の場合

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

# 注：以下のコード例は driver が初期化済みであることを前提にしています
# 実際のテストでは pytest fixture（driver引数）またはsetUp()で生成してください

# ❌ Flakyになりやすい：time.sleepは固定待機
import time
time.sleep(3)
driver.find_element(By.ID, "submit").click()

# ❌ Flakyになりやすい：implicitly_waitとWebDriverWaitの混在
driver.implicitly_wait(10)  # グローバル設定
wait = WebDriverWait(driver, 5)  # 個別設定との干渉で予測不能に

# ✅ 推奨：WebDriverWaitで「クリック可能になるまで」明示的に待つ
wait = WebDriverWait(driver, 10)
element = wait.until(EC.element_to_be_clickable((By.ID, "submit")))
element.click()

# ✅ 非同期でdisabled→enabledになるボタンへの対処
# ※ 以下は上記の wait = WebDriverWait(driver, 10) が定義済みであることが前提です
wait.until(lambda d: not d.find_element(By.ID, "submit").get_attribute("disabled"))

Playwright の場合

from playwright.sync_api import expect

# Playwrightは click() 実行前に visible / stable / enabled などを自動確認する
# auto-waiting 機能を持っています。ただしこれは「その瞬間の状態チェック」であり
# 「非同期状態変化を待つ」機能ではないため、expect()との併用が推奨されます

# ❌ auto-waitingに頼りすぎてFlakyになるケース
# （非同期でdisabled→enabledになるボタンはタイミング次第で落ちる）
page.locator("#submit").click()

# ✅ expect()で「enabled状態」を確認してからクリック
expect(page.locator("#submit")).to_be_enabled()
page.locator("#submit").click()

# ✅ APIレスポンス待ちが必要なコンテンツ
expect(page.locator(".search-results")).to_be_visible()
# → APIレスポンスが返ってリストが表示されるまで待つ

STEP 3：② 環境依存系Flakyの対策とは？

「ローカルは通るがCIで落ちる」——viewportサイズ・CPU速度・タイムゾーン・ヘッドレスモード差異など、実行環境の違いが原因のFlakyです。

主な環境依存の原因と対策

# ✅ Seleniumのヘッドレス設定（環境差異を最小化）
from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--headless")
options.add_argument("--window-size=1920,1080")  # viewport固定
options.add_argument("--disable-gpu")
options.add_argument("--no-sandbox")             # Linux CI環境での安定化
options.add_argument("--disable-dev-shm-usage")  # メモリ不足対策
driver = webdriver.Chrome(options=options)

# ✅ GitHub ActionsでのCIタイムアウト設定
# playwright.config.ts または pytest.ini で
# timeout = 30000  # ローカルより大きめに設定（ミリ秒）

STEP 4：③ データ競合系Flakyの対策とは？

「並列実行時だけ落ちる」「テストの順序を変えると落ちる」——これはテスト間でデータや状態を共有していることが原因です。修正難易度は高いですが、根本解決しないと永遠に再発します。

import pytest
import uuid

# ❌ Flakyになりやすい：テストデータを共有している
# test_A.py
def test_create_user():
    create_user("test@example.com")  # 固定のテストデータ

# test_B.py（並列実行するとtest_Aと競合する）
def test_delete_user():
    delete_user("test@example.com")  # test_Aと同じデータを操作

# ✅ 対策：テストごとにユニークなデータを生成する
@pytest.fixture
def unique_user():
    """テストごとにユニークなユーザーを作成し、テスト後に削除"""
    email = f"test_{uuid.uuid4().hex[:8]}@example.com"
    user = create_user(email)
    yield user
    # テスト後に必ずクリーンアップ
    try:
        delete_user(user.id)
    except Exception as e:
        # cleanup失敗はテスト本体の結果に影響させない
        # 実務では logger.warning(f"cleanup failed: {e}") などで記録することを推奨
        # ※ cleanup専用の簡略化例。通常のテストロジックでは広すぎるException捕捉は避ける
        pass

def test_update_user(unique_user):
    # ユニークなユーザーだけを操作するのでテスト間の競合なし
    update_user(unique_user.id, name="Updated")

STEP 5：④ 外部依存系Flakyの対策とは？

外部APIのレスポンスが遅い・ネットワークが不安定・外部サービスがメンテナンス中——自分たちのコードではどうにもできない外部要因が原因のFlakyです。

import pytest
import requests
from unittest.mock import patch, MagicMock

# ❌ Flakyになりやすい：外部APIをそのまま叩く
def test_user_profile():
    response = requests.get("https://api.example.com/users/1")
    # 外部APIが遅い・落ちているとFlakyになる
    assert response.status_code == 200

# ✅ 対策①：外部APIをモック化する
@patch("requests.get")
def test_user_profile_mocked(mock_get):
    mock_get.return_value = MagicMock(
        status_code=200,
        json=lambda: {"id": 1, "name": "Test User"}
    )
    response = requests.get("https://api.example.com/users/1")
    assert response.status_code == 200
    # 外部APIに依存しないため安定

# ✅ 対策②：リトライを設定する（外部依存が避けられない場合）
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=4))
def call_external_api():
    return requests.get("https://api.example.com/users/1", timeout=(3, 10))

STEP 6：⑤ 設計起因系Flakyの対策とは？

「テスト順序を変えると落ちる」「特定のテストの後でだけ落ちる」——これはテスト設計に問題があるFlakyです。修正難易度は最も高く、設計の見直しが必要になります。

設計起因Flakyの主なパターン

• テスト間の暗黙の前提条件依存：「テストAが実行された後の状態」を前提にテストBが書かれている
• グローバルなfixture/状態の共有：状態変更を伴う scope="session" のfixtureは、意図せずテスト間で状態共有が発生しやすい（読み取り専用データやimmutableな設定値では安全に使えます）
• 過度に長いE2Eテスト：「ログイン→検索→購入→決済」を1テストに詰め込みすぎて途中の失敗が他に波及

import pytest

# ❌ 設計起因Flaky：状態変更を伴うscope="session"で状態が引き継がれるケース
# ※ scope="session"自体が悪いのではなく、「状態変更を行うfixtureで使う」ことが問題
# （読み取り専用データ・immutableな設定値・ブラウザバイナリキャッシュ等では安全に使える）
@pytest.fixture(scope="session")
def logged_in_driver(driver):
    driver.get("/login")
    driver.find_element(By.ID, "email").send_keys("admin@example.com")
    driver.find_element(By.ID, "submit").click()
    yield driver
    # ログアウト処理なし → 次のテストに状態が残る

# ✅ 対策：テストごとにセットアップ・クリーンアップを完結させる
@pytest.fixture
def logged_in_driver(driver):
    """各テストで独立してログイン・ログアウトを行う"""
    driver.get("/login")
    driver.find_element(By.ID, "email").send_keys("admin@example.com")
    driver.find_element(By.ID, "submit").click()
    yield driver
    driver.get("/logout")  # ← 毎回クリーンアップ

STEP 7：直らないFlakyは隔離・削除を検討するとは？

「どうしても直らない」「直すコストが対策コストを大幅に上回る」Flakyは、隔離またはテスト自体の削除が正解のことがあります。「削除も正解」という判断ができるかどうかが、テストスイートを健全に保つカギです。なお削除によってカバレッジが低下し、そのシナリオのリグレッション検知が弱まるトレードオフがあります。削除する場合は、対象シナリオを別の手段（手動テスト・より小さな単体テスト）で担保することが条件です。

import pytest

# ✅ 方法①：@pytest.mark.skip で一時的に隔離
@pytest.mark.skip(reason="Flaky: 原因調査中 (2026-05-01 by Yoshi) #issue-123")
def test_payment_flow():
    pass

# ✅ 方法②：@pytest.mark.xfail で「失敗が期待される」マークをつける
@pytest.mark.xfail(reason="外部決済API不安定のため - #issue-456", strict=False)
def test_external_payment():
    pass

# ✅ 方法③：Flakyテスト専用のmarkを作り別CIステージで実行
# pytest.ini
# [pytest]
# markers =
#     flaky: 不安定なテスト（メインCIから除外）

@pytest.mark.flaky
def test_unstable_feature():
    pass

# メインCIでは除外して実行
# pytest -m "not flaky"
# 別ジョブで定期実行・監視
# pytest -m "flaky"

Flakyテストの再発防止：設計段階でやること

Flakyを直すだけでは不十分です。設計段階で再発を防ぐことが長期的に地獄から脱出し続けるための条件です。

FAQ

Flakyテスト地獄は「直し続ける体制」より「再発させない設計」の方が長期的なコストが低くなります。まず計測して可視化し、種類を特定して優先順位をつけて対処する——この順番で進めることが、地獄から永続的に脱出するための最短ルートです。