헤드리스 브라우저

헤드리스 브라우저(Headless browser)는 일반 브라우저와 똑같이 페이지를 로드하고, JavaScript를 실행하고, DOM을 만들고, 네트워크 요청을 처리하지만 화면에는 아무것도 그리지 않습니다. 테스트는 화면이 있는(headed) 브라우저와 같은 자동화 프로토콜로 헤드리스 브라우저를 제어합니다. 디스플레이 서버가 필요 없기 때문에 CI 컨테이너와 빌드 에이전트에서 UI 테스트를 실행하는 기본 방식입니다.

예시

Playwright는 기본적으로 헤드리스로 실행됩니다. 디버깅할 때만 창을 띄우도록 선택합니다.

npx playwright test            # headless
npx playwright test --headed   # show the browser
npx playwright test --ui       # interactive UI mode

Selenium 4에서는 브라우저 옵션으로 헤드리스 모드를 요청합니다.

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
WebDriver driver = new ChromeDriver(options);

FirefoxOptions options = new FirefoxOptions();
options.addArguments("-headless");
WebDriver driver = new FirefoxDriver(options);

왜 중요한가

• 어디서나 실행됩니다. 빌드 에이전트와 Docker 컨테이너에는 보통 디스플레이가 없으므로, headed 실행에는 가상 프레임버퍼가 필요합니다.
• 리소스를 덜 씁니다. headed 브라우저보다 가벼워서 같은 머신에서 더 많은 워커를 병렬로 돌릴 수 있습니다.
• 실제 브라우저입니다. 최신 헤드리스 Chrome과 Firefox는 headed 버전과 같은 렌더링 엔진을 사용하므로, 헤드리스로 작성한 테스트는 일반적으로 headed에서도 똑같이 동작합니다.

흔한 함정

• 뷰포트 차이. 헤드리스 브라우저는 데스크톱 브라우저와 다른 기본 창 크기로 시작할 수 있습니다. 반응형 레이아웃이 일관되게 동작하도록 뷰포트를 명시적으로 설정하세요.
• “headed에서는 되고 헤드리스에서는 실패”. 대개 헤드리스 모드 자체가 아니라 타이밍 문제입니다. 헤드리스 실행이 더 빠르거나 느려서 빠진 대기가 드러난 것입니다. CI를 headed로 바꾸지 말고 실패 시 트레이스나 스크린샷을 수집하세요.
• 눈 감고 디버깅하기. 실패한 테스트에 스크린샷, 비디오, 트레이스를 켜서 헤드리스 브라우저가 본 것을 확인할 수 있게 하세요.
• 헤드리스를 “브라우저가 아닌 것”과 혼동하기. JavaScript를 실행하지 않고 HTML만 가져오는 도구는 헤드리스 브라우저가 아니며, 최신 싱글 페이지 앱을 테스트할 수 없습니다.