liminfoPlaywright Reference
Playwright 브라우저 테스트 레퍼런스
Playwright Reference 소개
Playwright 레퍼런스는 Microsoft Playwright를 사용한 엔드투엔드 테스트를 위한 포괄적인 치트 시트입니다. 8가지 주요 영역을 다룹니다: 시맨틱 로케이터(getByRole, getByText, getByLabel, getByPlaceholder, getByTestId, CSS/XPath를 사용한 locator, filter, nth), 상호작용 액션(goto, click, fill, type, press, check, selectOption, hover, dblclick), expect 기반 어설션(toBeVisible, toHaveText, toHaveValue, toHaveCount, toBeEnabled, toHaveClass, toHaveURL, toHaveTitle), 페이지 생명주기 메서드(waitForSelector, waitForURL, waitForLoadState, evaluate, reload, goBack), 네트워크 가로채기(route, abort, waitForResponse, waitForRequest, 헤더 수정을 포함한 continue), 스크린샷 및 비주얼 회귀 테스트(페이지/요소 스크린샷, 비주얼 diff를 위한 toHaveScreenshot, PDF 생성), 설정(playwright.config.ts, 멀티 브라우저용 projects, globalSetup), CLI 명령어.
이 레퍼런스는 Playwright 테스트를 작성하는 프론트엔드 개발자와 QA 엔지니어, Playwright의 로케이터 API를 익혀야 하는 Selenium이나 Cypress에서 마이그레이션하는 팀, 정확한 어설션 메서드 이름이나 테스트에서 API 호출을 가로채는 방법을 빠르게 찾아야 하는 개발자에게 가장 유용합니다. Playwright의 현대적인 로케이터 API는 취약한 CSS 선택자 대신 접근성 시맨틱(역할, 라벨, 텍스트)을 사용하여 테스트 유지보수성을 높입니다.
레퍼런스는 일반적인 테스트 작성 워크플로를 따라 구성됩니다: 시맨틱 로케이터로 요소를 찾고, 액션으로 상호작용하고, expect()로 예상 결과를 어설션하고, Playwright의 내장 자동 대기로 비동기 동작을 처리합니다. route.fulfill()을 사용한 네트워크 모킹이나 toHaveScreenshot()를 사용한 비주얼 회귀 같은 고급 패턴은 쉽게 찾을 수 있도록 전용 섹션에 그룹화되어 있습니다.
주요 기능
- 시맨틱 로케이터: getByRole, getByText, getByLabel, getByPlaceholder, getByTestId
- locator()를 사용한 CSS/XPath 로케이터, 체이닝을 위한 locator.filter(), N번째 요소를 위한 locator.nth()
- 상호작용 액션: goto, click, 지연이 있는 type, press, check, selectOption, hover, dblclick
- Expect 어설션: toBeVisible, toHaveText, toHaveValue, toHaveCount, toBeEnabled, toHaveClass
- 내비게이션 검증을 위한 페이지 레벨 어설션: toHaveURL, toHaveTitle
- 네트워크 가로채기: API 모킹을 위한 route.fulfill(), 요청 차단을 위한 route.abort(), 헤더 수정을 위한 route.continue()
- toHaveScreenshot()을 사용한 비주얼 회귀 테스트, 요소 스크린샷, PDF 생성
- CLI 명령어: npx playwright test, --ui 모드, codegen 레코더, show-report, --debug 모드
자주 묻는 질문
Playwright에서 getByRole과 locator의 차이점은?
`getByRole()`은 ARIA 역할과 접근 가능한 이름으로 요소를 찾아 DOM 구조 변경에 강하고 접근성 표준에 맞습니다. 예를 들어 `getByRole("button", { name: "Submit" })`은 CSS 클래스나 위치에 관계없이 버튼을 찾습니다. `locator()`는 CSS 선택자와 XPath 표현식을 지원하며 복잡한 DOM 쿼리에 더 강력하지만 더 취약합니다. 가능하면 CSS 선택자 대신 `getByRole`, `getByText`, `getByLabel`을 선호하세요.
Playwright의 자동 대기는 어떻게 작동하며 waitForSelector가 필요한 경우는?
Playwright는 상호작용을 수행하기 전에 요소가 액션 가능한 상태가 될 때까지 자동으로 대기합니다 — 요소가 보이고, 비활성화되지 않고, 다른 요소에 가려지지 않을 때까지 기다립니다. 이는 대부분의 테스트에 명시적인 대기 호출이 필요 없음을 의미합니다. 어설션 전에 로딩 스피너가 사라지기를 기다리는 것처럼 액션의 일부가 아닌 특정 조건을 기다려야 할 때 `page.waitForSelector()`나 `page.waitForURL()`을 사용하세요.
Playwright 테스트에서 API 응답을 모킹하는 방법은?
`page.route(패턴, 핸들러)`를 사용해 URL 패턴과 일치하는 요청을 가로챕니다. 핸들러에서 `route.fulfill({ status: 200, body: JSON.stringify(데이터) })`를 호출해 모의 응답을 반환합니다. `route.abort()`로 요청을 차단합니다(예: 테스트 속도를 높이기 위해 이미지 로드 차단). `route.continue({ headers: { ...route.request().headers(), "X-Test": "true" } })`로 전달 전에 요청 헤더를 수정합니다.
locator.fill()과 locator.type()의 차이점은?
`locator.fill()`은 입력 필드를 지우고 전체 값을 한 번에 설정합니다 — 빠르며 폼 입력을 채우는 권장 방법입니다. `locator.type()`은 키스트로크 단위로 실제 키보드 입력을 시뮬레이션하며 선택적으로 키스트로크 사이에 `delay`를 줄 수 있어, 개별 키 이벤트를 수신하는 typeahead나 자동완성 컴포넌트를 테스트할 때 유용합니다. 대부분의 폼 채우기에는 속도를 위해 `fill()`을 사용하세요.
여러 브라우저에서 Playwright 테스트를 실행하는 방법은?
`playwright.config.ts`의 `projects`에 브라우저 대상을 지정합니다: `{ name: "chromium", use: { ...devices["Desktop Chrome"] } }`. Firefox와 Safari에 대한 별도 프로젝트 항목을 추가할 수 있습니다. `npx playwright test`로 모든 브라우저를 실행하거나, `npx playwright test --project=chromium`으로 특정 프로젝트를 대상으로 합니다. `@playwright/test`의 `devices` 맵은 데스크톱과 모바일 기기 모두에 대한 실제적인 뷰포트와 사용자 에이전트 설정을 제공합니다.
toHaveScreenshot()을 사용한 비주얼 회귀 테스트는 어떻게 작동하나요?
`await expect(page).toHaveScreenshot("homepage.png")`는 스크린샷을 캡처하고 저장된 기준 이미지와 비교합니다. 첫 실행 시 기준이 생성됩니다. 이후 실행에서 구성 가능한 임계값을 초과하는 픽셀 차이가 있으면 테스트가 실패합니다. `npx playwright test --update-snapshots`으로 기준을 업데이트합니다. 컴포넌트 레벨의 비주얼 회귀를 위해 개별 요소도 스냅샷할 수 있습니다: `await expect(page.locator(".header")).toHaveScreenshot()`.
Playwright Codegen으로 테스트를 녹화하는 방법은?
`npx playwright codegen https://example.com`을 실행해 녹화 패널이 있는 브라우저를 엽니다. 수행하는 모든 상호작용(클릭, 폼 입력, 내비게이션)이 실시간으로 Playwright 테스트 코드로 자동 변환됩니다. 생성된 코드는 권장 로케이터 API를 사용합니다. 쿠키와 localStorage를 저장하기 위해 `--save-storage=auth.json`을 전달해 인증된 세션을 녹화할 수도 있으며, 이를 테스트에서 로드할 수 있습니다.
실패하는 Playwright 테스트를 디버깅하는 방법은?
`npx playwright test --debug tests/login.spec.ts`를 실행해 Playwright Inspector를 열면 각 액션 전에 일시 중지하고 테스트를 단계별로 실행할 수 있습니다. 테스트의 어떤 지점에서든 `await page.pause()`를 추가해 실행을 일시 중지할 수 있습니다. `--ui` 플래그는 타임라인, 네트워크 로그, 스냅샷 뷰어가 있는 전체 Playwright UI를 엽니다. CI 실패의 경우 catch 블록에서 `page.screenshot()`을 사용하고 `npx playwright show-report`로 트레이스가 포함된 HTML 리포트를 확인하세요.