개요

pageLoadStrategy는 WebDriver가 페이지 이동 명령을 언제 완료로 판단할지 결정하는 세션 단위 설정값임. 핵심은 document.readyState 조회 시점을 어떻게 보느냐이며 전략별 대기 조건이 다름. 기본값은 normal이며, 네트워크 리소스가 많아 느린 페이지에서 eager 또는 none으로 바꿔 세션 체감 속도를 높일 수 있음

SPA처럼 자바스크립트가 동적으로 화면을 채우는 사이트에서는 readyState가 complete여도 실제 사용자 관점의 완료와 다를 수 있음. 전략 변경 시 명시적 대기 조합 설계가 필수임

주의할 점은 get 등 URL 기반 내비게이션과 달리, 클릭이나 폼 제출로 발생한 내비게이션에는 동일한 대기 규칙이 그대로 적용되지 않을 수 있음. 이 경우에도 별도의 대기 전략으로 안정성을 확보해야 함

전략별 동작

pageLoadStrategy는 document.readyState 값에 기반하여 다음과 같이 동작함

  • normal → readyState가 complete일 때까지 대기. HTML과 서브리소스 다운로드 완료 시점까지 기다리는 동작에 가까움
  • eager → readyState가 interactive일 때까지 대기. DOM 접근 가능 상태. 이미지 등 일부 리소스는 계속 로드 중일 수 있음
  • none → readyState값과 무관. 내비게이션 명령을 사실상 즉시 반환. 이후 로딩 진행 중 상태에서 테스트 로직이 실행됨

document.readyState는 현재 문서의 로딩 상태를 표현함. complete는 준수한 완료 기준으로 보이지만, 동적 렌더링이 많은 페이지에서는 UI 준비 완료의 보증이 아님

언제 어떤 전략을 쓰나

  • normal
    • 서버 렌더링 중심 페이지. 리소스가 과도하지 않고 완전한 로드가 타당한 기본값
    • 초기 진입 안정성이 최우선일 때 선택
  • eager
    • DOM만 준비되면 바로 상호작용 가능한 플로우. 이미지나 추적 스크립트가 느린 케이스에서 체감 속도 향상
    • DOMContentLoaded 이후 명시적 대기로 특정 요소 조건을 보강하는 패턴과 궁합이 좋음
  • none
    • 초기에 특정 API 응답이나 특정 DOM 스냅샷만 확보하면 되는 플로우
    • 페이지 초기화 로직을 테스트 측에서 주도적으로 동기화할 수 있을 때만 추천. 명시적 대기 없으면 불안정해짐

이 값은 세션 전체에 적용됨. 테스트 케이스별로 상이한 대기 정합이 필요한 경우 드라이버 세션을 분리하는 편이 관리가 쉬움

언어별 설정 예시

필요 최소 설정만 예시로 표기

  • Java
ChromeOptions options = new ChromeOptions();
options.setPageLoadStrategy(PageLoadStrategy.EAGER);
WebDriver driver = new ChromeDriver(options);
  • Python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

opts = Options()
opts.page_load_strategy = 'eager'
driver = webdriver.Chrome(options=opts)

Selenium 4에서는 DesiredCapabilities 사용 대신 각 브라우저 Options를 사용하는 방식 권장. 레거시 코드에서 setCapability(“pageLoadStrategy”, “eager”)를 보게 되더라도 신규 코드는 Options API로 통일하는 편이 좋음

동작 맥락과 주의 사항

  • 반환 시점의 범위

    • pageLoadStrategy는 세션의 내비게이션 명령 반환 시점을 정의. 일반적으로 driver.get과 같은 직접 URL 이동에 명확히 적용됨
    • 유저 인터랙션 기반 내비게이션은 드라이버 구현 및 브라우저별 차이가 있을 수 있으므로, 클릭 후 특정 상태를 명시적 대기로 보강하는 습관 필요

  • eager와 none 사용 시 동기화 전략

    • eager는 DOM 접근이 가능하지만 이미지나 비필수 리소스가 진행 중일 수 있음. CSS 지연으로 레이아웃 셰이크가 발생할 수 있어 요소 가시성, 크기 안정성 등의 조건으로 명시적 대기 설계 권장
    • none은 초기 HTML 수신 직후 로직이 이어지므로, 네비게이션 완료를 자체 조건으로 정의해야 함. 예를 들어 특정 루트 컨테이너 존재, 핵심 API 응답 반영 여부, 스피너 소멸 여부 등을 WebDriverWait으로 보장

  • 브라우저별 구현 차

    • 전략 개념은 W3C WebDriver 스펙에 정의되어 있으나 드라이버 구현 및 버전에 따라 세부 타이밍이 다를 수 있음
    • ChromeDriver는 77 버전대부터 eager를 정식 지원. 현재는 주요 드라이버에서 normal, eager, none 모두 사용 가능. 환경 차에 따른 타이밍 변동에 대비해 대기 조건을 결과 중심으로 설계 권장

  • 암묵적 대기와의 상호작용

    • 암묵적 대기(implicit wait)는 요소 탐색에만 영향을 주며 페이지 로드 완료와는 별개. pageLoadStrategy 조정 시에는 명시적 대기(explicit wait)를 우선 적용 권장

  • 성능과 안정성의 트레이드오프

    • eager와 none은 테스트 체감 속도를 높일 수 있으나, 준비되지 않은 DOM 또는 스타일 상태에서 상호작용하려다 실패할 수 있음
    • 정상 케이스와 실패 케이스 모두에서 동일하게 안정 동작하는 대기 조건을 최소 세트로 유지하는 것이 중요함

베스트 프랙티스

  • 기본값은 normal로 시작하고 병목이 명확할 때 eager로 전환. none은 명시적 동기화 설계가 준비된 경우에만 사용
  • 대기 조건은 UI 최종 상태보다 테스트 목적에 직접 연관된 불변 조건으로 작성. 예) 핵심 컨테이너 존재, 특정 데이터 렌더 수량 충족, 로딩 스피너 제거 등
  • 테스트 중간 단계에서 네비게이션을 야기하는 액션에는 항상 후속 명시적 대기를 배치. 클릭 성공만으로 페이지 준비 완료를 가정하지 않음
  • 세션 전역 설정이므로 케이스마다 요구 조건이 다르면 드라이버 세션을 분리하거나, 공통 초기화 훅에서 옵션을 명시적으로 주입
  • 불안정 징후가 보이면 브라우저별 드라이버 버전을 고정하고, 로컬과 CI의 네트워크/CPU 자원 차이에 따른 타이밍 편차를 모니터링

간단 체크리스트

  • 현재 케이스에서 완전한 페이지 로드가 진짜 필요한가
  • 동적 로딩이 많은가. 필요 DOM만 확보되면 충분한가
  • eager 또는 none 사용 시 명시적 대기 조건이 정의되어 있는가
  • 클릭 기반 네비게이션 이후의 동기화 전략이 있는가
  • 로컬과 CI 환경에서 동일하게 재현 가능한가

참고

  • normal은 완전 로드를 보장하는 진실의 순간이 아님. complete 이후에도 SPA는 데이터를 비동기로 적재함
  • eager는 DOMContentLoaded를 기준으로 빠르게 반환. 이미지 등은 지연될 수 있음
  • none은 드라이버 차단을 최소화하지만 모든 동기화를 테스트 코드가 책임짐

마무리

pageLoadStrategy는 테스트 속도와 안정성의 균형을 조절하는 레버임. normal로 시작해 병목과 목적을 기준으로 eager 또는 none을 선택하고, 명시적 대기로 관찰 가능한 완료 조건을 고정하면 플래키니스를 줄이면서 실행 시간을 단축할 수 있음. 드라이버와 브라우저 버전에 따른 미세한 차이를 흡수하도록 결과 중심의 대기를 설계하는 것이 핵심임

참고자료