Flaky 테스트 지옥에서 탈출하는 방법｜원인 5분류·진단부터 재발 방지까지 해설

「테스트가 실패해도 진짜 버그인지 알 수 없다」「CI가 빨간색이어도 아무도 신경 쓰지 않게 됐다」——그 Flaky 테스트 지옥에서 탈출하는 방법을 원인 분류·진단·대책·재발 방지까지 실무 경험을 바탕으로 해설합니다. Wait 설계·환경 차이·데이터 경합·외부 의존 등, Flaky의 종류별로 우선순위를 두고 대책을 소개합니다.

Flaky 테스트의 진짜 두려움은 「테스트가 실패한다」는 것이 아니라, 「테스트 결과를 아무도 신뢰하지 않게 된다」는 것입니다.

「또 Flaky야」——그 한마디가 일상이 됐을 때, 테스트 자동화는 기능을 잃었습니다. CI가 빨간색이어도 「어차피 Flaky겠지」라고 재실행할 뿐. 진짜 버그를 놓칠 위험이 높아지고, 결국 아무도 테스트 결과를 신뢰하지 않게 됩니다.

이 기사에서는 Flaky 테스트를 「대충 고치는」것이 아니라, 원인을 종류별로 분류하여 체계적으로 탈출하는 방법을 해설합니다.

Flaky 테스트란 무엇인가？왜 위험한가

Flaky 테스트（Flaky Test）란, 「같은 코드로 같은 환경일 텐데, 실행할 때마다 합격/불합격이 바뀌는 불안정한 테스트」를 말합니다.

Flaky 테스트의 종류와 근본 원인이란？5분류

먼저 확인：증상에서 Flaky 종류를 진단한다면？

STEP 1：먼저 Flaky를 계측·가시화한다란？

「고치기 전에 먼저 세어본다」——이것이 지옥 탈출의 첫 번째 단계입니다. 감각이 아닌 데이터로 파악함으로써 어디서부터 손을 댈지 우선순위가 정해집니다.

# ⚠️ pytest 표준 기능이 아닙니다. 사전 설치 필요：pip install pytest-repeat
# ※ CI 편입 시에는 실행 시간 증가 → Flaky 조사 용도로만 사용 권장
pytest tests/test_login.py --count=5

# pytest --junitxml=results.xml 로 결과 저장
# Datadog / Grafana / Allure Report / ReportPortal 등에서 장기 트렌드 확인

STEP 2：① Wait 계 Flaky의 대책이란？

가장 많고 비교적 고치기 쉬운 Flaky입니다（SPA나 virtual DOM 환경에서는 난이도가 올라가는 경우도 있습니다）.

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 또는 setUp()으로 생성）

# ❌ Flaky：time.sleep 고정 대기
import time
time.sleep(3)
driver.find_element(By.ID, "submit").click()

# ✅ 권장：WebDriverWait로 명시적 대기
wait = WebDriverWait(driver, 10)
element = wait.until(EC.element_to_be_clickable((By.ID, "submit")))
element.click()

# ✅ 비동기로 disabled→enabled가 되는 버튼（위의 wait 정의 필요）
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()와의 병용이 필요합니다

# ✅ expect()로 enabled 상태를 확인하고 나서 클릭
expect(page.locator("#submit")).to_be_enabled()
page.locator("#submit").click()

# ✅ API 응답 후에 표시되는 콘텐츠
expect(page.locator(".search-results")).to_be_visible()

STEP 3：② 환경 의존 계 Flaky의 대책이란？

STEP 4：③ 데이터 경합 계 Flaky의 대책이란？

import pytest
import uuid

# ✅ 대책：테스트마다 유니크한 데이터를 생성한다
@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}") 으로 기록 권장
        pass

def test_update_user(unique_user):
    update_user(unique_user.id, name="Updated")

STEP 5：④ 외부 의존 계 Flaky의 대책이란？

from unittest.mock import patch, MagicMock

# ✅ 대책①：외부 API를 목업화한다
@patch("requests.get")
def test_user_profile_mocked(mock_get):
    mock_get.return_value = MagicMock(status_code=200, json=lambda: {"id": 1})
    response = requests.get("https://api.example.com/users/1")
    assert response.status_code == 200

# ✅ 대책②：리트라이（외부 의존이 피할 수 없는 경우만）
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의 대책이란？

import pytest

# ❌ 설계 기인 Flaky：상태 변경을 수반하는 scope="session"（scope="session" 자체가 나쁜 것은 아님）
# 읽기 전용 데이터·immutable한 설정값에서는 안전하게 사용 가능
@pytest.fixture(scope="session")
def logged_in_driver(driver):
    driver.get("/login")
    driver.find_element(By.ID, "submit").click()
    yield driver
    # 로그아웃 없음 → 다음 테스트에 상태가 남는다

# ✅ 대책：테스트마다 셋업·클린업을 완결시킨다
@pytest.fixture
def logged_in_driver(driver):
    driver.get("/login")
    driver.find_element(By.ID, "submit").click()
    yield driver
    driver.get("/logout")  # ← 매번 클린업

STEP 7：고칠 수 없는 Flaky는 격리·삭제를 검토한다란？

삭제에 의해 커버리지가 저하되고 리그레션 검지가 약해지는 트레이드오프가 있습니다. 삭제하는 경우는 대상 시나리오를 다른 수단（수동 테스트·단위 테스트）으로 담보하는 것이 조건입니다.

import pytest

# ✅ 방법①：일시적 격리（이유·날짜·이슈 링크를 반드시 기록）
@pytest.mark.skip(reason="Flaky: 원인 조사 중 (2026-05-01 by Yoshi) #issue-123")
def test_payment_flow():
    pass

# ✅ 방법②：실패 예정 마크
@pytest.mark.xfail(reason="외부 결제 API 불안정 - #issue-456", strict=False)
def test_external_payment():
    pass

# ✅ 방법③：flaky 전용 mark로 메인 CI에서 제외
# pytest.ini: markers = flaky: 불안정한 테스트
@pytest.mark.flaky
def test_unstable_feature():
    pass
# pytest -m "not flaky"  # 메인 CI
# pytest -m "flaky"      # 별도 감시 잡

Flaky 테스트의 재발 방지：설계 단계에서 할 것

FAQ

먼저 계측하여 가시화하고, 종류를 특정하여 우선순위를 두고 대처한다——이 순서로 진행하는 것이 지옥에서 영속적으로 탈출하기 위한 가장 효율적인 방법입니다.