Selenium WebDriverWait 완벽 가이드 | 올바른 대기 처리로 Flaky Test 해결하기

Selenium에서 “요소를 찾을 수 없다”, “클릭할 수 없다”는 에러가 빈발하는 원인의 많은 부분은 대기 처리 문제입니다. time.sleep()으로 임시방편을 쓰면 Flaky Test가 되기 쉽습니다. WebDriverWait와 expected_conditions를 올바르게 사용하면 안정적인 테스트를 작성할 수 있습니다.

📌 이 글의 대상 독자

📖 이 글을 읽으면 할 수 있는 것

필자는 여러 프로젝트에서 Selenium을 사용한 브라우저 자동화 테스트를 실천해 왔습니다.
대기 처리 문제는 Flaky Test의 원인으로 가장 자주 마주치는 케이스 중 하나입니다.
이 글은 그 경험을 토대로 실무에서 사용할 수 있는 대기 처리 패턴을 체계적으로 정리한 것입니다.

왜 Selenium에서 대기 처리가 필요한가

현대의 웹 애플리케이션은 비동기 처리(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적 사용법)

폴링 간격과 무시할 예외를 세밀하게 지정할 수 있는 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

# WebDriverWait 상세 설정
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: 대기 처리 사상의 차이