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가 특히 효과적입니다. 테스트 실행 시의 조작·스크린샷·네트워크 로그·콘솔 로그를 하나의 파일로 기록할 수 있습니다.

※ 아래는 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를 활성화해서 실패 시의 기록을 남기는 체계부터 시작해보세요.