Selenium WebDriverWait完全ガイド｜待機処理を正しく理解してFlaky Testを解消する

Selenium で「要素が見つからない」「クリックできない」というエラーが頻発する原因の多くは、待機処理の問題です。time.sleep() で誤魔化していると Flaky Test になりがちです。WebDriverWait と expected_conditions を正しく使えば、安定したテストが書けます。

📌 この記事の対象読者

📖 この記事を読むとできること

筆者は複数のプロジェクトで Selenium を使ったブラウザ自動化テストを実践してきました。
待機処理の問題は Flaky Test の原因として最も多く遭遇するケースの一つです。
本記事はその経験をもとに、実務で使える待機処理パターンを体系的にまとめたものです。

なぜ Selenium で待機処理が必要なのか

現代の Web アプリケーションは非同期処理（Ajax・JavaScript）で動いています。ページを開いた瞬間には要素がまだ存在しないことがほとんどです。

これらのエラーを回避するために「要素が準備できるまで待つ」処理が必要です。

time.sleep() がダメな理由

import time
from selenium import webdriver
from selenium.webdriver.common.by import By

driver = webdriver.Chrome()
driver.get("https://example.com/login")  # サンプルURL
time.sleep(3)  # ← これがダメ
driver.find_element(By.ID, "email").send_keys("user@example.com")

Selenium の3種類の待機方法

明示的待機（WebDriverWait）の使い方

明示的待機は特定の条件が満たされるまで最大○秒待つという書き方です。条件が満たされれば即座に処理を続けるため、無駄な待機が発生しません。

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

driver = webdriver.Chrome()
driver.get("https://example.com/login")  # サンプルURL

# WebDriverWait の基本形
# WebDriverWait(driver, タイムアウト秒数).until(条件)
wait = WebDriverWait(driver, 10)  # 最大10秒待つ

# 要素が表示されるまで待つ（入力欄など）
email_input = wait.until(
    EC.visibility_of_element_located((By.ID, "email"))
)
email_input.send_keys("user@example.com")

# 要素が表示されてクリック可能になるまで待つ
submit_btn = wait.until(
    EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='login-button']"))
)
submit_btn.click()

expected_conditions の主要メソッド一覧

場面別のコード例

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

wait = WebDriverWait(driver, 10)

# ① ボタンをクリックする（最もよく使う）
btn = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='submit-btn']")))
btn.click()

# ② ローディングスピナーが消えるのを待つ
wait.until(EC.invisibility_of_element_located((By.CSS_SELECTOR, ".loading-spinner")))

# ③ 完了メッセージが表示されるのを待つ
wait.until(EC.text_to_be_present_in_element(
    (By.CSS_SELECTOR, "[data-testid='status-message']"),
    "保存しました"
))

# ④ ページ遷移を待つ
wait.until(EC.url_contains("/dashboard"))

# ⑤ リストが読み込まれるのを待つ（1件以上）
items = wait.until(
    EC.presence_of_all_elements_located((By.CSS_SELECTOR, ".item-list li"))
)
assert len(items) > 0

# ⑥ アラートを処理する
wait.until(EC.alert_is_present())
alert = driver.switch_to.alert
alert.accept()

暗黙的待機（implicitly_wait）とその注意点

暗黙的待機はすべての find_element にグローバルなタイムアウトを設定します。一度設定すれば全操作に自動で適用されます。

driver = webdriver.Chrome()
driver.implicitly_wait(10)  # 全 find_element で最大10秒待つ
driver.get("https://example.com/login")  # サンプルURL

# これ以降の find_element は最大10秒待つ
email_input = driver.find_element(By.ID, "email")

WebDriverWait の詳細設定（いわゆる Fluent Wait 的な使い方）

Fluent Wait は WebDriverWait の詳細設定版で、ポーリング間隔と無視する例外を細かく指定できます。
なお、Selenium Python には Java のような独立した FluentWait クラスはなく、WebDriverWait の timeout・poll_frequency・ignored_exceptions を調整することでいわゆる Fluent Wait 的な動作を実現します。

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By
from selenium.common.exceptions import NoSuchElementException, StaleElementReferenceException

# Fluent Wait の設定
wait = WebDriverWait(
    driver,
    timeout=15,             # 最大待機時間（秒）
    poll_frequency=0.5,     # チェック間隔（秒）。デフォルトは0.5秒
    ignored_exceptions=[    # 無視する例外（この例外が出ても待ち続ける）
        NoSuchElementException,
        StaleElementReferenceException,
    ]
)

element = wait.until(
    EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='dynamic-btn']"))
)
element.click()

カスタム待機条件を作る

expected_conditions にない条件を待ちたいときは、カスタム条件を関数またはクラスで定義できます。

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.common.by import By

# ① lambda を使ったシンプルな書き方
wait = WebDriverWait(driver, 10)

# 要素の属性値が変わるのを待つ
wait.until(lambda d: d.find_element(By.ID, "status").get_attribute("data-state") == "loaded")

# ② クラスを使った再利用可能な書き方
class element_has_class:
    """指定した要素が特定の CSS クラスを持つまで待つ"""
    def __init__(self, locator: tuple, css_class: str) -> None:
        self.locator = locator
        self.css_class = css_class

    def __call__(self, driver):
        element = driver.find_element(*self.locator)
        return self.css_class in element.get_attribute("class")


# 使用例：ボタンが "active" クラスを持つまで待つ
wait.until(element_has_class(
    (By.CSS_SELECTOR, "[data-testid='submit-btn']"),
    "active"
))

pytest fixture との組み合わせ

実務では WebDriverWait を pytest fixture に組み込むことで、テストコードをシンプルに保てます。

# conftest.py
import pytest
from selenium import webdriver
from selenium.webdriver.support.ui import WebDriverWait


@pytest.fixture
def driver():
    d = webdriver.Chrome()
    d.implicitly_wait(0)   # 暗黙的待機は無効化しておく
    yield d
    d.quit()


@pytest.fixture
def wait(driver):
    return WebDriverWait(driver, 10)

# test_login.py
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC


def test_login_success(driver, wait) -> None:
    driver.get("https://example.com/login")  # サンプルURL

    wait.until(EC.visibility_of_element_located((By.ID, "email"))).send_keys("user@example.com")
    wait.until(EC.visibility_of_element_located((By.ID, "password"))).send_keys("password123")
    wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='login-btn']"))).click()

    wait.until(EC.url_contains("/dashboard"))
    assert "/dashboard" in driver.current_url

待機処理ではまりやすいポイント 7選

よくある質問（FAQ）

まとめ

待機処理を正しく書くことは、Selenium テストの安定性を上げる最も効果的な方法の一つです。
まず手持ちのテストコードで time.sleep() を検索し、element_to_be_clickable や visibility_of_element_located に置き換えるところから始めてみましょう。

Selenium vs Playwright：待機処理の考え方の違い