Playwright
Playwright는 Chromium, Firefox, WebKit을 자동화하는 API와 test runner를 함께 제공합니다. 이 노트는 처음 test를 실행하는 단계에서 시작해 locator, 자동 대기, fixture, 인증, network mocking, trace, 병렬 실행, 시각, 접근성 검증, 대규모 suite 운영까지 이어지는 완결형 학습 가이드입니다.
특정 API를 외우는 것보다 “왜 이 test가 안정적인가”를 설명할 수 있게 만드는 것이 목표입니다. 각 Part와 장은 난이도에 따라 다음 요소를 조합합니다.
- 한눈에 보기 — 먼저 기억할 핵심 규칙
- 개념 — browser와 test runner 내부에서 일어나는 일
- 예제 — 복사해 실행할 수 있는 TypeScript
- 실패 사례 — 흔히 flaky해지는 코드와 원인
- 실습 — 제공된 Todo Lab에서 직접 확인할 과제
- 심화 — CI와 큰 suite에서 생기는 trade-off
3분 요약
- Test마다 새
BrowserContext를 사용해 cookie, local storage, session을 격리합니다. - CSS 구조보다
getByRole,getByLabel처럼 사용자가 인식하는 계약을 locator로 선택합니다. sleep을 넣지 말고 locator actionability와 web-first assertion의 retry를 이용합니다.- Event는 trigger보다 먼저 기다리기 시작합니다.
waitForEvent()promise를 만들고 click한 뒤 await합니다. - API mock은 “무조건 빠르게”가 아니라 test가 책임지는 경계를 명시하기 위해 사용합니다.
- 실패 분석의 기본 단위는 screenshot 한 장이 아니라 trace의 action, DOM, network, console 묶음입니다.
- Retry는 결함을 숨기는 성공 판정이 아니라 flaky test를 분류하고 증거를 남기는 장치입니다.
- 병렬 실행 전에 test data와 account가 worker 사이에서 격리되는지 확인합니다.
- 시각 snapshot은 같은 OS, browser, font 환경에서 만들고 검증합니다.
- CI에는 HTML/blob report, trace, screenshot을 보존하되 token과 개인정보가 포함되지 않게 관리합니다.
난이도별 학습 경로
| 단계 | 먼저 읽을 Part | 도달 목표 |
|---|---|---|
| 입문 | I → II → III | 첫 test를 작성하고 form, popup, file을 안정적으로 다룬다 |
| 중급 | IV → V → VI | fixture, 인증, API mock, trace로 유지 가능한 suite를 만든다 |
| 운영 | VII → VIII | browser matrix, 병렬 실행, CI artifact와 quality gate를 설계한다 |
| 심화 | IX → X | 시간, 시각, 접근성, service worker를 결정적으로 검증하고 architecture를 확장한다 |
| 종합 | XI → XII | capstone을 완성하고 anti-pattern, troubleshooting 기준으로 스스로 리뷰한다 |
전체 차례
- Part I. 시작과 실행 모델 — browser, context, page, 설치, 첫 test
- Part II. Locator와 동기화 — locator, actionability, assertion, frame
- Part III. 사용자 Interaction — form, upload, download, dialog, popup, navigation
- Part IV. 격리와 Test 설계 — context, fixture, test data, page object
- Part V. Network, Auth, API — request 관측, mock, HAR, storage state, API test
- Part VI. Debugging과 Artifact — UI mode, Inspector, trace, flakiness
- Part VII. Browser와 병렬 실행 — project, emulation, worker, shard, web server
- Part VIII. CI와 Suite 운영 — CI, artifact, visual, accessibility, runbook
- Part IX. 결정적 고급 Testing — clock, visual diff, ARIA snapshot, browser API, WebSocket
- Part X. 대규모 Suite Architecture — tag, step, reporter, project dependency, test pyramid
- Part XI. Capstone 실전 프로젝트 — 요구사항에서 release gate까지 하나의 suite 완성
- Part XII. Reference와 문제 해결 — roadmap, CLI, anti-pattern, 진단 flow, 공식 예제 해부
실습 프로젝트
playwright-lab은 문서 예제를 한곳에서 실행하도록 만든 작은 application입니다. Todo, API 응답, login, popup, dialog, upload, download, timer를 외부 서비스 없이 재현합니다.
package.jsonplaywright.config.tsserver.mjspublic/index.htmltests/todo.spec.tstests/network.spec.tstests/interactions.spec.tstests/clock.spec.tstests/visual-accessibility.spec.ts
cd playwright-lab
npm install
npx playwright install chromium
npm test
처음에는 Chromium 하나로 흐름을 익힙니다. 그 뒤 FULL_BROWSERS=1 npm test와 npx playwright install로 Firefox, WebKit까지 확장합니다. CI에서 설치 browser 수를 줄이면 download 시간과 image 크기를 아낄 수 있습니다.
추천 실습 순서
npm test -- todo.spec.ts로 locator와 assertion을 익힙니다.- 의도적으로 accessible name을 바꿔 locator failure message를 읽습니다.
network.spec.ts에서 실제 응답, 완전 mock, 원본 수정의 차이를 비교합니다.interactions.spec.ts로 popup, download, dialog event 대기 순서를 확인합니다.clock.spec.ts에서 5분을 실제로 기다리지 않고 timer를 진행합니다.- 실패 test를 만들어 trace와 HTML report의 DOM, network, attachment를 확인합니다.
- 마지막으로 capstone rubric에 따라 tag, fixture, artifact, CI gate를 적용합니다.
이 문서의 캡처
문서 안의 화면은 외부 문서 이미지를 복사한 것이 아니라 제공된 Lab과 Playwright의 정보 구조를 바탕으로 만든 학습용 재현 캡처입니다. UI version이 바뀌어도 action, timeline, artifact 사이의 관계를 이해하도록 단순화했습니다. 실제 실행 결과는 npx playwright test --ui, npx playwright show-report, npx playwright show-trace에서 확인합니다.
기준과 범위
- 예제 언어: TypeScript +
@playwright/test - browser: Chromium 우선, 필요할 때 Firefox, WebKit project 확장
- 대상: E2E와 browser integration test
- 원칙: 공개 API, 공식 guide 우선, 구현 detail에 의존하지 않기
- 보안: storage state, trace, video, HAR에 credential, 개인정보를 commit하지 않기