파이썬 Selenium 중급 활용 GitHub Actions에서 Headless Xvfb 설정과 캐시 전략

🔗 CI 환경에서 Selenium 실행의 기본 이해

로컬 환경에서는 브라우저를 직접 띄워가며 Selenium 테스트를 실행할 수 있습니다.
하지만 CI 환경은 GUI가 없는 서버 환경이 대부분이기 때문에 동일한 방식으로 실행하면 오류가 발생하곤 합니다.
따라서 headless 모드를 사용하거나, 가상 디스플레이를 만들어주는 Xvfb 같은 도구가 필요합니다.

CI 환경에서 Selenium을 실행할 때 가장 흔히 발생하는 문제는 브라우저 초기화 실패, 디스플레이 세션 부족, 드라이버 버전 불일치 등입니다.
이러한 문제는 CI 서버가 실제 브라우저 렌더링을 위한 환경을 제공하지 않기 때문에 발생합니다.
따라서 GitHub Actions 같은 워크플로우에서는 환경 설정을 꼼꼼히 해주는 것이 필수입니다.

📌 GitHub Actions에서 자주 발생하는 문제

• ⚠️Display 환경 없음 → GUI 기반 테스트 실패
• ⚠️Chrome/Driver 버전 불일치 → 브라우저 실행 불가
• ⚠️의존성 설치 시간 지연 → 워크플로우 실행 속도 저하

📌 Selenium 실행 환경 체크리스트

CI 환경에서 Selenium을 안정적으로 실행하기 위해서는 몇 가지 기본 요소를 반드시 점검해야 합니다.

• 🛠️Python 및 Selenium 버전 확인
• 🛠️Chrome 및 ChromeDriver 설치 여부
• 🛠️Display/Xvfb 설정 적용 여부
• 🛠️의존성 캐시 설정 여부

🛠️ Headless 모드 설정과 ChromeDriver 활용

CI 환경에서는 실제 브라우저 창을 띄울 수 없기 때문에 headless 모드를 반드시 활성화해야 합니다.
최근 Chrome과 Firefox는 headless 옵션을 기본적으로 제공하기 때문에 Selenium에서 손쉽게 사용할 수 있습니다.
특히 최신 Chrome은 headless 실행 시에도 실제 브라우저와 거의 동일한 환경을 제공하여 테스트 신뢰도가 높습니다.

📌 Python에서 Headless 옵션 적용하기

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

options = Options()
options.add_argument("--headless=new")   # 최신 Chrome은 "new" 옵션 권장
options.add_argument("--no-sandbox")
options.add_argument("--disable-dev-shm-usage")

driver = webdriver.Chrome(options=options)
driver.get("https://example.com")
print(driver.title)
driver.quit()

위 코드에서 –headless=new 옵션은 Chrome 109 이상에서 권장되는 방식으로, 기존 headless보다 실제 브라우저 환경과 유사한 결과를 제공합니다.
또한 CI 환경에서는 –no-sandbox, –disable-dev-shm-usage 옵션을 함께 적용하는 것이 안정적입니다.

📌 ChromeDriver 설치와 버전 관리

CI 환경에서는 Chrome과 ChromeDriver의 버전 불일치로 인해 테스트가 실패하는 경우가 많습니다.
이를 해결하기 위해 webdriver-manager 같은 라이브러리를 활용하면 자동으로 최신 버전을 설치할 수 있어 편리합니다.

from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

service = Service(ChromeDriverManager().install())
driver = webdriver.Chrome(service=service)
driver.get("https://example.com")
driver.quit()

⚙️ Xvfb로 가상 디스플레이 환경 구성하기

Selenium 테스트에서 headless 모드만으로 충분하지 않은 경우가 있습니다.
특히 일부 브라우저 기능이나 캡처 기능은 여전히 실제 디스플레이 환경을 필요로 하죠.
이때 활용할 수 있는 것이 바로 Xvfb(X virtual framebuffer)입니다.
이는 실제 화면 없이도 가상의 X 서버를 만들어 브라우저가 실행될 수 있는 환경을 제공합니다.

📌 GitHub Actions에서 Xvfb 설치하기

GitHub Actions 워크플로우에서는 리눅스 환경에서 간단히 apt-get을 통해 Xvfb를 설치할 수 있습니다.

- name: Install Xvfb
  run: sudo apt-get install -y xvfb

설치 후에는 테스트 실행 시 Xvfb-run 명령어를 이용해 가상 디스플레이 환경에서 브라우저를 실행할 수 있습니다.

- name: Run Selenium tests with Xvfb
  run: xvfb-run --server-args="-screen 0 1920x1080x24" pytest tests/

📌 언제 Xvfb를 선택해야 할까?

일반적인 크롤링이나 단순 동작 테스트라면 headless 모드만으로 충분합니다.
그러나 다음과 같은 상황에서는 Xvfb 설정이 필요합니다.

• 🖼️브라우저 스크린샷 캡처가 필요한 경우
• 🎬동영상 녹화를 통한 테스트 리포트가 필요한 경우
• 🧪브라우저 API 동작이 headless 모드에서 다르게 작동하는 경우

🔌 GitHub Actions 워크플로우에 Selenium 통합

CI에서 Selenium 테스트를 실행하기 위해서는 GitHub Actions 워크플로우 파일(.github/workflows/ci.yml)에 필요한 단계들을 정의해야 합니다.
Python 환경 설정, 브라우저 설치, 드라이버 세팅, 그리고 실제 테스트 실행까지 순서대로 지정하면 됩니다.

📌 기본 워크플로우 예시

name: Selenium Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Install Chrome
        run: sudo apt-get install -y chromium-browser

      - name: Run tests
        run: pytest tests/

위 예시는 기본적인 구조로, Python 환경 설정 → 브라우저 설치 → 테스트 실행 흐름을 따릅니다.
하지만 안정성과 속도를 위해 추가 설정이 필요합니다.

📌 Headless 모드 및 Xvfb 통합

GitHub Actions에서 안정적으로 실행하기 위해서는 headless 모드와 Xvfb를 함께 적용하는 것이 유용합니다.
아래는 이를 반영한 실행 예시입니다.

- name: Install Xvfb
  run: sudo apt-get install -y xvfb

- name: Run Selenium tests with Xvfb
  run: xvfb-run --server-args="-screen 0 1920x1080x24" pytest tests/

📌 실패를 줄이는 전략

• 🔄테스트 재시도를 허용해 일시적 오류를 보완
• 🧩환경별 driver 버전 고정으로 호환성 확보
• ⚡pytest 병렬 실행으로 테스트 속도 향상

💡 실행 속도를 높이는 캐시 전략

GitHub Actions와 같은 CI 환경은 매 빌드마다 새로운 인스턴스를 생성하기 때문에, 의존성을 매번 설치하면 상당한 시간이 소요됩니다.
이를 줄이려면 패키지 캐시 전략을 적절히 활용해야 합니다.
pip, webdriver, npm 등 다양한 의존성을 캐싱하면 빌드 속도가 크게 단축되고, 네트워크 트래픽도 절감할 수 있습니다.

📌 pip 캐시 설정

Python 패키지는 actions/cache를 이용해 쉽게 캐시할 수 있습니다.
requirements.txt가 변경되지 않았다면 설치 시간을 절약할 수 있습니다.

- name: Cache pip
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-

📌 WebDriver 캐시 전략

Selenium 테스트에서 자주 발생하는 문제는 ChromeDriver 다운로드입니다.
매번 설치하면 시간이 오래 걸리므로, webdriver-manager가 설치한 드라이버를 캐시하는 것도 좋은 방법입니다.

- name: Cache ChromeDriver
  uses: actions/cache@v3
  with:
    path: ~/.wdm
    key: ${{ runner.os }}-chromedriver

📌 캐시 전략 적용 시 주의사항

• 🔑키 관리가 중요합니다. requirements.txt가 변경되면 새로운 키가 생성되어야 합니다.
• ⚡불필요한 캐시 누적을 방지하기 위해 정기적으로 워크플로우를 점검하세요.
• 🧹버전 호환성 문제가 생기면 캐시를 무효화하고 새로 설치해야 합니다.

❓ 자주 묻는 질문 (FAQ)