Skip to content

Playwright 자동 대기 (Auto-waiting)

개요

E2E 테스트가 쉽게 깨지는 가장 큰 이유는 타이밍이에요. 페이지가 아직 안 떴는데 클릭해서 실패하거나, 버튼이 비활성 상태일 때 눌러서 실패하는 경우죠. Playwright는 이런 문제를 해결하기 위해 액션을 수행하기 전에 요소가 "실제로 동작 가능한 상태"인지를 일련의 검사로 확인해요. 이걸 자동 대기(auto-waiting) 라고 해요. 필요하다면 그 검사가 통과할 때까지 기다렸다가, 정해진 타임아웃 안에 통과하지 못하면 TimeoutError로 실패해요. sleep() 같은 임의 대기를 코드에 박지 않아도 되는 이유가 여기 있어요.

핵심 개념

액션 수행 전 확인하는 것들

locator.click()처럼 액션을 수행하기 전에, Playwright는 요소가 다음 조건을 충족하는지 확인해요. 이 조건들을 공식 문서는 actionability checks라고 불러요.

  • 유일한 요소(resolves to exactly one element) — 셀렉터가 정확히 하나의 요소로 이어져야 해요.
  • 보임(Visible) — 비어 있지 않은 경계 상자(bounding box)를 갖고 visibility:hidden 계산 스타일이 아니어야 해요. display:none이나 크기가 0인 요소는 보이지 않는 것으로 보는데, opacity:0은 보이는 것으로 취급해요.
  • 안정(Stable) — 최소 두 번의 애니메이션 프레임 동안 같은 경계 상자를 유지해야 해요. 애니메이션 중이면 아직 안정적이지 않다고 보죠.
  • 이벤트 수신(Receives Events) — 클릭 지점에서 다른 요소(예: 오버레이)가 그 클릭을 가로채지 않아야 해요.
  • 활성(Enabled) — disabled 속성이나 aria-disabled=true에 걸리지 않아야 해요.

액션마다 검사하는 항목이 조금씩 달라요. 예를 들어 click은 보임·안정·이벤트 수신·활성을 모두 확인하지만, fill은 보임·활성·편집 가능(editable)만 확인해요. press, focus 같은 동작은 검사를 아예 하지 않죠.

force 옵션

일부 액션은 force 옵션을 지원해요. click에 force: true를 주면 필수 아닌 actionability 검사를 건너뜁니다. 예를 들어 대상 요소가 실제로 클릭 이벤트를 받는지 확인하지 않아요. 다만 이건 "내가 지금은 검사 없이 강제로 누를게"라는 명시적 선택이므로, 정말로 다른 방법이 없을 때만 써야 해요.

자동 재시도 assertion

액션이 아니라 검증(assertion) 쪽에도 자동 대기가 적용돼요. Playwright의 assertion은 조건이 충족될 때까지 자동으로 재시도하도록 만들어서, 페이지가 아직 반영되기 전에 검증이 실패하는 플레이키(flicker)를 줄여줘요. 예를 들어 "서버 확인 후 Sign Up 버튼이 활성화되는" 시나리오에서, 버튼이 비활성 상태로 시작해도 재시도하는 assertion은 그 버튼이 활성화되어 클릭 가능한 시점을 기다렸다가 확인합니다.

실제 동작 흐름

공식 문서 예시가 이걸 잘 보여줘요. "사용자 이름이 유일한지 서버가 확인 중이라 Sign Up 버튼이 disabled 상태였다가, 확인이 끝나면 enabled 버튼으로 교체되는" 화면이 있다고 해볼게요. click은 버튼이 활성화되어 클릭 가능해질 때까지 기다렸다가 동작하므로, 타이밍을 코드에서 맞출 필요가 없어요.

실제 적용 (데이터스케쳐스)

웹빌더의 문서 변환·저장 흐름은 비동기가 많아요. HWP·PDF를 웹으로 변환하면 결과가 뜨기까지 시간이 걸리고, "저장 중" 버튼이 잠시 비활성이 됐다 풀리기도 하죠. 이럴 때 waitForTimeout 같은 임의 대기를 박는 건 최악의 선택이에요 — 느린 환경에서는 깨지고, 빠른 환경에서는 쓸데없이 대기하니까요. 자동 대기와 재시도 assertion이 이 타이밍 문제를 코드 대신 다뤄줘요.

다만 자동 대기는 "요소가 동작 가능해질 때까지"만 기다려요. "변환이 끝나서 결과가 화면에 실제로 떴다"를 확인하는 건 별도의 assertion으로 명시해야 해요. 자동 대기가 언제까지 기다리는지(타임아웃), 어떤 요소를 찾아야 하는지를 정하는 셀렉터 설계는 셀렉터에서, 모바일·네트워크 조건은 에뮬레이션에서 이어져요.

더 알아보기