최종 업데이트: 2026년 10월 31일.

GitHub Actions에서 다중 리전 Playwright 테스트를 실행하는 방법

이커머스 사이트는 방문자의 연결 위치에 따라 통화, 지역 URL, 시장별 콘텐츠를 다르게 보여줄 수 있습니다. 한 네트워크 위치에서만 테스트하면 이런 지역별 경험이 어떻게 동작하는지 파악하기 어렵습니다.

이 가이드에서는 Python, Playwright, Pytest, GitHub Actions, 국가별 주거용 프록시를 사용해 동일한 GeoIP 테스트를 미국, 영국, 독일에서 실행합니다.

테스트 대상은 Geolizr Shopify 데모 스토어 이며, 테스트 스크립트는 KindProxy GeoIP Benchmark 저장소 의 tests/test_geolizr_geoip.py 입니다.

이 글은 해당 Geolizr 단일 테스트 스크립트를 사용합니다. 리전 스케줄링은 GitHub Actions가 담당하고, 브라우저 검증은 Python 테스트가 담당합니다. 별도의 범용 test_region.py나 두 번째 다중 사이트 테스트 구현은 만들지 않습니다.

목차

• 워크플로가 하는 일
• 프로젝트 가져오기
• 테스트 환경 이해하기
• 로컬에 의존성 설치하기
• GitHub에서 프록시 자격 증명 구성하기
• GitHub Actions 워크플로 추가하기
• CI 활성화 전에 로컬에서 테스트 실행하기
• GitHub Actions에서 결과 검토하기
• 흔한 GitHub Actions 문제
• 자격 증명 보호 및 불필요한 트래픽 줄이기
• FAQ
• 결론
• 나만의 다중 리전 프록시 테스트 실행하기

워크플로가 하는 일

워크플로는 구성된 리전마다 하나의 작업을 실행합니다.

각 작업은 다음을 수행합니다.

1. 동일한 GitHub 저장소를 체크아웃합니다.
2. Python 의존성과 Chromium을 설치합니다.
3. 해당 리전의 프록시 자격 증명을 GitHub Secrets에서 불러옵니다.
4. tests/test_geolizr_geoip.py를 실행합니다.
5. 작업 종료 후 검토할 수 있도록 Pytest 결과 파일을 업로드합니다.

테스트는 프록시에서 관측된 출구 국가와 웹사이트의 현지화 동작을 따로 확인합니다. 이 구분은 중요합니다. 브라우저 로케일을 바꿔도 공인 IP는 바뀌지 않으며, IP 조회만으로는 사이트가 예상 시장 콘텐츠를 표시했는지 증명할 수 없습니다.

1. 프로젝트 가져오기

저장소를 클론합니다.

git clone https://github.com/kindproxy/kindproxy-geoip-benchmark.git
cd kindproxy-geoip-benchmark

관련 테스트 파일은 다음과 같습니다.

tests/test_geolizr_geoip.py

저장소에는 의존성 목록, Pytest 구성, 예제 환경 설정도 포함되어 있습니다. 테스트의 두 번째 복사본을 만들지 말고, 저장소의 현재 파일을 기준으로 삼으세요.

2. 테스트 환경 이해하기

테스트는 동일한 Geolizr 데모 스토어에 대해 세 개의 주거용 프록시 위치를 비교합니다.

브라우저 컨텍스트는 프록시 연결과 별도로 구성됩니다. 프록시는 네트워크 경로와 공인 출구 IP를 결정합니다. Playwright 브라우저 컨텍스트는 로케일, 타임존 같은 브라우저 설정을 제어합니다.

의미 있는 비교를 위해 리전 실행 간에 브라우저 설정을 동일하게 유지하세요. 로케일이나 타임존이 리전마다 달라지면, 차이가 프록시 위치 때문인지 브라우저 구성 때문인지 구분하기 어렵습니다.

또한 이 테스트는 실행마다 새 브라우저 컨텍스트를 사용해, 저장된 쿠키나 로컬 스토리지가 결과에 영향을 줄 가능성을 줄입니다.

3. 로컬에 의존성 설치하기

Python 가상 환경을 만들고 활성화합니다.

python -m venv .venv

macOS 또는 Linux:

source .venv/bin/activate

Windows PowerShell:

.venv\Scripts\Activate.ps1

의존성과 Chromium을 설치합니다.

python -m pip install -r requirements.txt
python -m playwright install chromium

새로 설치한 Linux 머신에서는 Chromium에 OS 패키지도 필요할 수 있습니다. 브라우저가 시작되지 않으면 Playwright Python 설치 문서 에 따라 필요한 브라우저 의존성을 설치하세요.

4. GitHub에서 프록시 자격 증명 구성하기

워크플로에는 리전별 프록시 게이트웨이와 자격 증명이 필요합니다. GitHub 저장소에, 가능하면 전용 GitHub Environment에 추가하세요.

예를 들어 Settings → Environments에서 geo-tests라는 Environment를 만듭니다. 워크플로가 참조하는 이름으로 시크릿을 추가합니다.

명확한 이름 규칙 예시는 다음과 같습니다.

KP_PROXY_USERNAME_US
KP_PROXY_PASSWORD_US
KP_PROXY_USERNAME_UK
KP_PROXY_PASSWORD_UK
KP_PROXY_USERNAME_DE
KP_PROXY_PASSWORD_DE

공유 프록시 게이트웨이는 Environment 변수로 추가합니다.

KP_PROXY_SERVER

프록시 제공자가 안내한 게이트웨이 호스트 이름, 포트, 프로토콜, 국가 타기팅 자격 증명을 그대로 사용하세요. 사용자 이름 형식과 국가 선택 구문은 제공자마다 다를 수 있습니다.

다중 리전 테스트용 주거용 프록시가 필요하신가요?

여러 위치에서 웹사이트가 어떻게 동작하는지 테스트하려면, 안정적인 국가 타기팅이 가능한 주거용 프록시 연결이 필요합니다.

KindProxy 주거용 프록시는 국가 타기팅이 가능한 HTTP/HTTPS 주거용 엔드포인트를 제공하므로, Playwright·Selenium 같은 브라우저 자동화를 서로 다른 네트워크 위치에서 실행할 수 있습니다. 대시보드에서 게이트웨이, 사용자 이름, 비밀번호를 구성한 뒤, 그 값을 로컬 .env 파일이나 GitHub Secrets에 전달하세요.

KindProxy 주거용 프록시 살펴보기

저장소의 현재 .env.example나 테스트 스크립트가 다른 환경 변수 이름을 쓴다면, 테스트 스크립트·로컬 구성·워크플로에서 그 이름을 일치시키세요. 한곳에만 이름을 바꾸지 마세요.

실제 프록시 자격 증명을 워크플로 YAML, 소스 코드, README, 스크린샷, 테스트 출력에 넣지 마세요. 로컬 .env 파일은 Git에 포함하지 말고, .gitignore가 제외하는지 확인하세요.

GitHub 문서:

• Using secrets in GitHub Actions
• Using environments for deployment

5. GitHub Actions 워크플로 추가하기

저장소에 다음 워크플로 파일을 만듭니다.

.github/workflows/geo-playwright.yml

아래 워크플로는 매트릭스 구조와 리전별 시크릿 매핑을 보여 줍니다. 사용하기 전에 env 섹션의 환경 변수 이름을 tests/test_geolizr_geoip.py가 실제로 읽고 저장소 .env.example에 문서화된 이름과 맞추세요. 워크플로는 테스트가 기대하는 구성을 전달해야 하며, 두 번째 구성 인터페이스를 만들지 마세요.

name: Multi-region Geolizr Playwright tests

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  geolizr-geo-test:
    name: Geolizr GeoIP test (${{ matrix.region }})
    runs-on: ubuntu-latest
    environment: geo-tests
    timeout-minutes: 15

    strategy:
      fail-fast: false
      max-parallel: 3
      matrix:
        include:
          - region: US
            username_secret: KP_PROXY_USERNAME_US
            password_secret: KP_PROXY_PASSWORD_US
          - region: UK
            username_secret: KP_PROXY_USERNAME_UK
            password_secret: KP_PROXY_PASSWORD_UK
          - region: DE
            username_secret: KP_PROXY_USERNAME_DE
            password_secret: KP_PROXY_PASSWORD_DE

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          python -m playwright install --with-deps chromium

      - name: Run Geolizr test
        env:
          TEST_REGION: ${{ matrix.region }}
          PROXY_SERVER: ${{ vars.KP_PROXY_SERVER }}
          PROXY_USERNAME: ${{ secrets[matrix.username_secret] }}
          PROXY_PASSWORD: ${{ secrets[matrix.password_secret] }}
        run: |
          pytest -v tests/test_geolizr_geoip.py \
            --junitxml="test-results-${TEST_REGION}.xml"

      - name: Upload test result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: geolizr-result-${{ matrix.region }}
          path: test-results-${{ matrix.region }}.xml
          if-no-files-found: ignore

중요: 워크플로를 실제 테스트 스크립트에 맞추기

위 매트릭스는 리전별 자격 증명을 선택하는 방법을 보여 줍니다. 테스트 스크립트가 리전 설정을 받고, 프록시 서버·사용자 이름·비밀번호를 환경 변수에서 읽는다는 가정을 둡니다.

워크플로를 커밋하기 전에 실제 test_geolizr_geoip.py를 확인하세요.

• 스크립트가 이미 리전 변수를 읽는다면, 그 정확한 변수 이름으로 매트릭스 값을 전달합니다.
• 리전별 별도 환경 변수를 기대한다면, 워크플로에서 그 정확한 변수를 매핑합니다.
• Pytest 매개변수나 명령줄 옵션으로 리전을 선택한다면, 기존 인터페이스를 사용합니다.
• Python 스크립트가 실제로 읽지 않는 한 워크플로에 TEST_REGION, PROXY_SERVER 같은 이름을 추가하지 마세요.

워크플로와 테스트 스크립트는 구성 계약이 일치해야 합니다. 저장소의 테스트 파일이 기준입니다.

fail-fast: false는 한 리전이 실패해도 다른 리전 작업을 끝낼 수 있게 합니다. max-parallel: 3은 구성된 세 작업의 동시 실행을 허용합니다. timeout-minutes는 멈춘 테스트가 러너를 무기한 점유하지 않게 합니다.

6. CI 활성화 전에 로컬에서 테스트 실행하기

GitHub Actions에 의존하기 전에 기존 테스트가 로컬에서 동작하는지 확인하세요.

저장소 .env.example과 README의 변수 이름 및 구성 형식을 따른 뒤 다음을 실행합니다.

pytest -v tests/test_geolizr_geoip.py

한 번에 한 리전만 테스트하려면 테스트 스크립트에 이미 구현된 리전 선택 방식을 사용하세요. 코드에 없는 변수나 명령줄 옵션을 가정하지 마세요.

로컬 실행이 성공하면 테스트 코드·프록시 구성 문제와 GitHub Actions 구성 문제를 분리하기 쉽습니다.

7. GitHub Actions에서 결과 검토하기

저장소의 Actions 탭을 열고 워크플로 실행을 선택합니다.

3리전 매트릭스에서는 다음 별도 작업이 보여야 합니다.

• Geolizr GeoIP test (US)
• Geolizr GeoIP test (UK)
• Geolizr GeoIP test (DE)

각 작업을 열어 Pytest 출력을 확인하세요. 테스트가 결과 파일을 만들면 워크플로는 리전마다 JUnit XML 아티팩트도 업로드합니다.

아래 터미널 스타일 결과 이미지는 Geolizr 테스트 실행의 리전별 관측을 보여 줍니다. 테스트 출력 요약이며 GitHub Actions 인터페이스 스크린샷이 아닙니다.

미국

영국

독일

Pytest 케이스가 통과했다는 것은 스크립트가 정의한 어서션이 성공했다는 뜻입니다. 페이지의 모든 통화 신호가 동일하다거나 최종 결제 금액까지 검증했다는 뜻은 아닙니다. 특히 테스트 상태만으로 판단하지 말고 상세 관측 결과를 검토하세요.

여러 국가에서 웹사이트 테스트하기

이 결과는 하나 이상의 네트워크 위치에서 테스트하는 이유를 보여 줍니다. 웹사이트는 요청에 사용한 주거용 IP 위치에 따라 방문자를 다르게 식별할 수 있습니다.

자체 GeoIP 확인, 현지화 QA, 리전별 브라우저 워크플로에 주거용 IP가 필요하다면, KindProxy는 여러 국가의 주거용 프록시 액세스를 제공합니다. 동일한 KindProxy GeoIP Benchmark 테스트 패턴을 자신의 자격 증명으로 재사용할 수 있습니다.

KindProxy 시작하기

8. 흔한 GitHub Actions 문제

어서션 실패가 곧바로 프록시 결함을 의미하지는 않습니다. GeoIP 데이터베이스는 서로 다를 수 있고, 웹사이트의 현지화 로직은 바뀔 수 있으며, 데모 스토어의 스토어프론트 동작도 업데이트될 수 있습니다.

9. 자격 증명 보호 및 불필요한 트래픽 줄이기

프록시 인증 브라우저 테스트를 실행할 때 다음 관행을 지키세요.

• 자격 증명은 GitHub Secrets 또는 보호된 Environment에 저장합니다.
• 신뢰할 수 없는 풀 리퀘스트 코드에 프록시 자격 증명을 노출하지 않습니다.
• 자격 증명이 필요한 테스트는 신뢰할 수 있는 브랜치 또는 수동 승인 워크플로에서만 실행합니다.
• 리전 실행마다 새 브라우저 컨텍스트를 사용합니다.
• 병렬 작업 수와 요청 빈도를 합리적으로 유지합니다.
• 소유하거나 접근 권한이 있는 웹사이트만 테스트합니다.
• 전체 프록시 자격 증명, 인증 헤더, 쿠키, 기타 민감 데이터를 CI 로그에 출력하지 않습니다.

예제 워크플로는 main으로의 push와 수동 디스패치를 사용합니다. 신뢰할 수 없는 코드가 시크릿을 노출하려 할 수 있는 pull_request 이벤트에서는 자격 증명 테스트를 실행하지 않습니다.

FAQ

GitHub Actions에서 주거용 프록시를 통해 Playwright 테스트를 실행할 수 있나요?

네. GitHub Actions 작업은 환경 변수 또는 GitHub Secrets를 통해 프록시 게이트웨이와 자격 증명을 Playwright에 전달할 수 있습니다. 워크플로와 Python 테스트는 정확히 같은 환경 변수 이름을 사용해야 합니다.

여러 국가를 병렬로 테스트할 수 있나요?

네. GitHub Actions 매트릭스로 미국, 영국, 독일에 대한 별도 작업을 만들 수 있습니다. 각 작업은 같은 테스트 스크립트를 실행하면서 국가별 프록시 자격 증명을 사용할 수 있습니다.

Playwright 로케일을 바꾸면 프록시 국가도 바뀌나요?

아니요. 프록시가 네트워크 경로와 공인 출구 IP를 제어합니다. Playwright의 로케일과 타임존은 브라우저 환경 설정을 구성하며 네트워크 위치는 바꾸지 않습니다.

감지된 국가가 틀리면 무엇을 확인해야 하나요?

먼저 프록시 게이트웨이, 자격 증명, 국가 타기팅 설정을 확인하세요. 그다음 관측된 공인 출구 IP를 확인하고 다른 GeoIP 조회 소스와 비교하세요. GeoIP 데이터베이스마다 결과가 다를 수 있습니다.

GitHub Actions에서 프록시 자격 증명을 어떻게 보호해야 하나요?

자격 증명은 GitHub Secrets 또는 보호된 GitHub Environment에 저장하세요. 신뢰할 수 없는 풀 리퀘스트 코드에 노출하거나, 워크플로 YAML에 직접 넣거나, CI 로그에 출력하지 마세요.

결론

GitHub Actions는 매트릭스를 사용해 동일한 Playwright 테스트를 여러 리전 프록시 구성에서 실행할 수 있습니다. 이 프로젝트에서는 각 매트릭스 작업이 기존 tests/test_geolizr_geoip.py를 서로 다른 주거용 프록시 위치를 통해 Geolizr Shopify 데모 스토어에 대해 실행합니다.

이렇게 하면 초점이 유지됩니다. 테스트 스크립트 하나, 대상 웹사이트 하나, 미국·영국·독일 CI 작업은 별도. GitHub Actions 자동화를 위해 범용 리전 테스트를 복제할 필요는 없습니다.

테스트 코드와 프로젝트 구성은 KindProxy GeoIP Benchmark 저장소 에서 확인할 수 있습니다.

스토어프론트에서 테스트가 무엇을 관측했는지 알고 싶다면 관련 보고서를 참고하세요. 주거용 프록시는 이커머스 가격과 통화를 바꾸나? Playwright GeoIP 테스트 .

나만의 다중 리전 프록시 테스트 실행하기

여러 국가에서 웹사이트를 테스트할 준비가 되셨나요?

GitHub Actions 워크플로는 이 가이드를, Playwright 테스트 스크립트는 KindProxy GeoIP Benchmark 프로젝트를 클론하고, 국가 타기팅 주거용 IP가 필요한 실행에는 KindProxy 주거용 프록시를 사용하세요.

주거용 프록시 요금제 살펴보기

더 읽을거리

• Playwright에서 주거용 프록시를 사용하는 방법
• Playwright 프록시 인증: 흔한 연결 오류와 해결 방법
• 주거용 프록시는 이커머스 가격과 통화를 바꾸나? Playwright GeoIP 테스트
• GitHub의 KindProxy GeoIP Benchmark
• Playwright Python 문서
• GitHub Actions 워크플로 구문