🎭 Playwright의 Auto-Waiting은 어떻게 동작할까?

먼저, Playright는 무엇일까?

Playwright는 Microsoft에서 만든 오픈소스 E2E(End-to-End) 테스트 프레임워크로, 실제 브라우저 환경에서 사용자의 행동을 그대로 시뮬레이션하는 데 초점을 맞추고 있다. Chromium, Firefox, WebKit 등 주요 렌더링 엔진을 모두 지원하며, 멀티 브라우저 테스트를 단일 코드베이스로 수행할 수 있다는 장점이 있다.

🎯 다른 테스트 도구보다도 Playwright가 뛰어난 이유?

비교 항목	Playwright	Cypress	Selenium
멀티 브라우저 지원	✅ Chromium, Firefox, WebKit	🚫 Chrome 중심	✅ 모든 브라우저
멀티 탭/창 제어	✅ 가능	🚫 불가능	✅ 가능
네트워크 요청 가로채기	✅ 쉬움	🔸 제한적	🔸 번거로움
자동 대기(Auto-Wait)	✅ 기본 내장	🚫 직접 처리	🚫 직접 처리
속도	⚡ 빠름	⚡ 빠름	🐢 상대적으로 느림
설치/셋업	⚡ 간편	⚡ 간편	😵 복잡할 수 있음

멀티 브라우저 지원에도 강력한 강점을 가지고 있지만, 위에서 처럼 Playwright만이 가지고 있는 Auto-wait 기능에 대해서 알아보고자 한다. 테스트 도중 흔히 겪는 타이밍 문제를 줄여주며, 안정적이고 신뢰도 높은 테스트 작성이 가능하다.

⏳ Auto-Waiting

Playwright의 핵심 기능 중 하나인 Auto-Waiting은 사용자의 명령 (click, fill, goto 등)을 실행할 때, DOM 상태가 안전하고 실행 가능한 상태가 될 때까지 자동으로 기다려주는 기능이다. 즉, 사용자가 별도로 waitFor 함수를 작성하지 않아도, Playwright는 적절한 타이밍을 스스로 판단해준다.

🧠 “Actionability” 모델

Playwright가 어떤 element를 클릭하거나 입력하기 전에 확인하는 조건들이 있다. 바로 Actionability checks라고 불리는 것들이다. 이게 바로 Auto-Waiting의 핵심이다.

🎯 예를 들어 page.click(selector) 호출 시, Playwright는 다음을 확인한다.

• Element가 DOM에 존재하는가? (attached)
• 보이는가? (visible)
• 쓸 수 있는 (활성화) 상태인가? (enabled)
• 스크롤이 필요한가? (in viewport)
• 다른 요소에 안 가려졌는가? (not obscured)

이 모든 조건을 만족할 때까지, Playwright는 기다린다. 그리고 만족되는 순간, click 이벤트를 보낸다.

이걸 Actionability model이라고 부른다.

🕵️‍♀️ 내부 메커니즘, 어떻게 기다릴 수 있을까?

Playwright는 내부적으로 WebSocket을 통해 브라우저와 실시간으로 연결된 상태에서 명령을 주고받는다. 이 연결을 통해 DOM 상태를 지속적으로 모니터링하고, 변화가 감지될 때까지 기다린다.

page.click() 같은 명령은 내부적으로 JavaScript Promise로 구현되어 있으며, actionability 조건이 충족되기 전까지 resolve되지 않는다.

조건을 체크하기 위해 브라우저 내에서 아래와 같이 DOM 변화 감지를 하여 조건이 충족되는지 판단한다고 한다.

• MutationObserver: DOM 구조 변화 감지
• IntersectionObserver: 요소의 화면 내 노출 여부 확인
• 주기적 polling: 조건 충족 여부 점검

예를 들어, page.click('#submit')는 다음과 같은 흐름을 따른다.

await page.waitForSelector('#submit'); // 존재 확인
await ensureActionable('#submit');     // visibility, enabled 등 체크
await scrollIntoView('#submit');       // 스크롤 조정
await page.click('#submit');           // 실제 클릭 실행
}

Playwright는 이런 식으로, wait → check → 실행 패턴을 자동화해놓았다.
단순히 click()을 호출핬을 뿐인데, 이 모든 과정을 명시적으로 작성하지 않아도 Playwright가 자동으로 기다리고 판단한다.

🧪 그럼 이게 왜 대단한가?

1. Flaky Test 감소

E2E 테스트의 가장 큰 적은 Flaky Test, 즉 간헐적 실패라고 한다. 이는 대부분 DOM이 아직 준비되지 않았는데 동작을 시도하면서 발생한다.
Playwright는 이런 타이밍 이슈를 방지해 테스트의 신뢰도와 안정성을 높여준다.

2. 테스트 코드 간결화

기존에는 waitForSelector, waitForTimeout 등을 수동으로 작성해야 했지만, Playwright는 이 과정을 내부적으로 처리해준다.
→ 더 적은 코드로 더 많은 안정성을 확보할 수 있다.

⚠️ 그런데 무조건 다 기다려주진 않는다.

Playwright의 Auto-Waiting은 다음과 같은 기본적인 상호작용 동작에 대해서만 동작한다고 한다.

• click, dblclick
• fill, type, press
• check, uncheck
• hover
• selectOption
• setInputFiles
• goto, waitForNavigation, reload

❌ 하지만, 다음과 같은 경우에는 수동 대기 처리가 필요하다.

상황	대기 함수 예시
데이터 로딩 완료 확인	page.waitForResponse()
특정 텍스트 렌더링 대기	page.waitForSelector('text=완료')
애니메이션 종료 확인	page.waitForFunction(() => !isAnimating)
API 응답 완료	page.waitForResponse(res => res.url().includes('/api') && res.status() === 200)

이럴 땐 여전히 page.waitForFunction(), page.waitForResponse(), page.waitForSelector() 같은 수동 대기가 필요하다. 에러가 발생했다면 Auto-waiting이 지원되지 않는 경우일 수 있으니, 공식 문서를 꼼꼼히 확인하자.

---

✨ 마무리하며

Playwright의 Auto-Waiting은 단순히 “기다리는 기능”을 넘어서, 사용자의 실제 행동 흐름을 정확히 이해하고 실행 가능한 시점을 판단하여 자동으로 동작하는 똑똑한 기능인 것 같다.

나는 평소에 단위 및 통합 테스트를 위한 Jest만 알고 있었는데, (사용해본 적은 없고..) Playwright를 통해 브라우저 상에서 전체 사용자 플로우를 자동으로 테스트할 수 있다는 점이 신기하고 매력적이었다.

기존에는 매번 입력 값을 직접 넣어 유효성 검사 또는 등록이 제대로 동작하는지 확인해야 했었는데, Playwright를 통해 자동화해 놓으니 정말 편리한 것 같다.

수동으로 테스트 하는 시간이 은근 많이 소요되고 귀찮은 일이였는데, 기존 프로젝트에도 도입하면 개발자 경험이 매우 향상될 것 같다 :)

---

참고 문헌

https://playwright.dev/