Playwright 입문｜Python으로 브라우저 자동화를 시작하는 방법을 초보자를 위해 해설

Playwright는 Microsoft가 개발한 브라우저 자동화 라이브러리입니다. Selenium에 비해 설정이 적고 자동 대기가 표준 내장되어 있으며 모던한 작성법을 사용할 수 있습니다. 이 글에서는 설치부터 첫 번째 테스트 실행까지, 명령어 하나씩 차근차근 해설합니다.

📌 이 글의 대상 독자

📖 이 글을 읽으면 할 수 있는 것

필자는 여러 프로젝트에서 Playwright를 사용한 E2E 테스트를 실천해 왔습니다.
Selenium에서 Playwright로 마이그레이션한 프로젝트도 있어 양측의 차이를 실무 관점에서 비교할 수 있습니다.
이 글은 “첫날에 동작하는 테스트 작성”을 목표로 막히기 쉬운 포인트를 미리 짚어서 해설합니다.

Playwright란? Selenium과의 차이

Playwright가 급속히 보급된 이유

2020년 이후 Playwright는 E2E 테스트 툴로서 급속히 보급됐습니다. 그 배경에는 다음과 같은 이유가 있습니다.

① 설치하기

먼저 Python 환경이 준비되어 있는지 확인하세요 (Python 환경 구축 가이드).
venv를 활성화한 상태에서 설치합니다.

# Playwright 본체와 pytest 플러그인 설치
pip install playwright pytest-playwright

# 브라우저 본체 설치 (Chromium·Firefox·WebKit)
playwright install

설치 확인:

playwright --version
# Playwright 1.x.x 라고 표시되면 OK

② 우선 실행해보기 (스크립트 형식)

pytest를 사용하기 전에 먼저 간단한 스크립트로 Playwright의 동작을 확인합니다.

# first_playwright.py
from playwright.sync_api import sync_playwright


def main() -> None:
    with sync_playwright() as p:
        # 브라우저 실행 (headless=False로 브라우저 창 표시)
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()

        # 페이지 열기
        page.goto("https://example.com")  # 샘플 URL

        # 타이틀 확인
        print(page.title())

        # 스크린샷 찍기
        page.screenshot(path="screenshot.png")

        browser.close()


if __name__ == "__main__":
    main()

python first_playwright.py

브라우저가 열리고 페이지가 표시되면 성공입니다. screenshot.png도 저장됩니다.

③ pytest로 테스트 작성하기

실무에서는 pytest와 조합해서 테스트를 관리합니다. pytest-playwright를 설치했다면 page fixture를 자동으로 사용할 수 있습니다.

첫 번째 테스트 파일

# test_first.py
from playwright.sync_api import Page, expect


def test_page_title(page: Page) -> None:
    page.goto("https://example.com")  # 샘플 URL
    assert "Example" in page.title()
    # Playwright다운 작성법은 expect를 사용하는 방법도 있다
    # expect(page).to_have_title("Example Domain")


def test_heading_visible(page: Page) -> None:
    page.goto("https://example.com")  # 샘플 URL
    heading = page.get_by_role("heading", name="Example Domain")
    expect(heading).to_be_visible()  # Playwright다운 어서션

pytest test_first.py -v

정상 출력 예시:

========================= test session starts ==========================
collected 2 items

test_first.py::test_page_title    PASSED    [ 50%]
test_first.py::test_heading_visible PASSED  [100%]

========================== 2 passed in 2.34s ==========================

로그인 폼 테스트 (실전 예시)

# test_login.py
from playwright.sync_api import Page, expect


def test_login_success(page: Page) -> None:
    page.goto("https://example.com/login")  # 샘플 URL

    # 이메일 주소 입력
    page.get_by_label("이메일 주소").fill("user@example.com")

    # 비밀번호 입력
    page.get_by_label("비밀번호").fill("password123")

    # 로그인 버튼 클릭
    page.get_by_role("button", name="로그인").click()

    # 대시보드로 전환됐는지 확인
    expect(page).to_have_url("https://example.com/dashboard")  # 샘플 URL


def test_login_invalid_password(page: Page) -> None:
    page.goto("https://example.com/login")  # 샘플 URL

    page.get_by_label("이메일 주소").fill("user@example.com")
    page.get_by_label("비밀번호").fill("wrong-password")
    page.get_by_role("button", name="로그인").click()

    # 에러 메시지가 표시되는지 확인
    expect(page.get_by_test_id("error-message")).to_be_visible()
    expect(page.get_by_test_id("error-message")).to_contain_text("비밀번호가 올바르지 않습니다")

④ expect로 어서션 작성하기

Playwright의 expect는 웹 페이지 전용 어서션으로 조건이 충족될 때까지 자동으로 재시도합니다.

⑤ conftest.py로 테스트 정리하기

베이스 URL이나 브라우저 설정은 conftest.py에 모아두면 테스트 파일을 간결하게 유지할 수 있습니다.

# conftest.py
import pytest
from playwright.sync_api import Page


BASE_URL = "https://example.com"  # 샘플 URL


@pytest.fixture
def logged_in_page(page: Page) -> Page:
    """로그인된 상태로 page를 반환하는 fixture"""
    page.goto(f"{BASE_URL}/login")
    page.get_by_label("이메일 주소").fill("user@example.com")
    page.get_by_label("비밀번호").fill("password123")
    page.get_by_role("button", name="로그인").click()
    page.wait_for_url(f"{BASE_URL}/dashboard")
    return page

# test_dashboard.py
from playwright.sync_api import Page, expect


def test_dashboard_shows_username(logged_in_page: Page) -> None:
    expect(logged_in_page.get_by_test_id("user-name")).to_contain_text("테스트 사용자")

pytest.ini로 브라우저·헤드리스 모드 설정하기

# pytest.ini
[pytest]
addopts =
    --browser chromium
    --headed

# 커맨드라인에서도 지정할 수 있다
pytest --browser chromium              # Chromium 사용
pytest --browser firefox               # Firefox 사용
pytest --headed                        # 브라우저 창 표시
pytest --headless                      # 헤드리스 모드 (CI용)
pytest --slowmo 500                    # 조작을 500ms 느리게 해서 디버깅하기 쉽게

⑥ Codegen으로 테스트 코드 자동 생성하기

Codegen은 브라우저를 조작하면서 그 조작을 자동으로 테스트 코드로 변환하는 툴입니다. 로케이터 작성법을 모를 때의 출발점으로 사용할 수 있습니다.

# Codegen 실행 (URL은 테스트 대상 페이지에 맞게)
playwright codegen https://example.com  # 샘플 URL

브라우저가 열리고 조작하면 옆 창에 코드가 생성됩니다.

⑦ 스크린샷과 Trace Viewer

스크린샷

# 페이지 전체 스크린샷
page.screenshot(path="screenshots/result.png", full_page=True)

# 특정 요소만 캡처
page.get_by_test_id("error-message").screenshot(path="screenshots/error.png")

Trace Viewer (테스트 실패 상세 확인)

Trace Viewer는 테스트 실행 과정을 단계별로 녹화할 수 있는 툴입니다. 테스트가 실패했을 때 “어떤 조작에서 어떤 상태였는지”를 시각적으로 확인할 수 있습니다.

# 테스트 실패 시 자동으로 트레이스 저장
pytest --tracing=retain-on-failure

# 트레이스를 열어서 확인
playwright show-trace trace.zip

Playwright 입문에서 막히기 쉬운 포인트 7가지

자주 묻는 질문 (FAQ)

정리

Playwright는 자동 대기·Trace Viewer·Codegen이 표준 탑재되어 있어 Selenium보다 설정이 적고 처음 브라우저 자동화를 배우는 분에게도 임하기 쉬운 툴입니다.
우선 playwright codegen으로 어떤 코드가 생성되는지 시험해보는 것만으로도 전체 모습을 파악할 수 있습니다.

다음 단계로 테스트가 늘어나면 Page Object Model(POM)으로 코드를 정리하거나, GitHub Actions로 CI에 내장하는 방법으로 나아갑시다.