Playwright CLI란?
Playwright CLI는 Microsoft가 만든 오픈소스 브라우저 자동화 프레임워크 Playwright의 커맨드라인 인터페이스(CLI) 도구입니다.
브라우저를 코드 없이 터미널 명령어 하나로 조작할 수 있게 해주며, 다음과 같은 기능을 제공합니다.
| 기능 | 설명 |
|---|---|
playwright screenshot | 특정 URL의 화면을 PNG/JPEG로 캡처 |
playwright pdf | 웹 페이지를 PDF로 저장 |
playwright codegen | 브라우저 조작을 자동으로 테스트 코드로 변환 |
playwright test | E2E 테스트 실행 |
playwright show-trace | 테스트 실행 기록(트레이스)을 시각적으로 확인 |
Claude Code 내장 Playwright CLI
Claude Code는 Playwright CLI를 내장하고 있어, AI가 직접 브라우저를 열고 UI를 확인하고 테스트를 실행하는 것이 가능합니다. 사람이 브라우저를 수동으로 열어 확인하지 않아도 되는 완전 자동화 개발 루프를 구현할 수 있습니다.
왜 프론트엔드 개발에 유용한가?
기존 프론트엔드 개발 흐름은 다음과 같습니다.
코드 작성 → 브라우저 열기 → 새로고침 → 눈으로 확인 → 버그 발견 → 수정 → 반복Claude Code + Playwright CLI를 사용하면 이렇게 바뀝니다.
코드 작성 → Claude가 자동 캡처·확인·테스트·수정 → 완료사람이 개입하는 단계가 대폭 줄어들고, 개발 속도와 품질이 동시에 올라갑니다.
워크플로우
1단계 — 개발: UI 컴포넌트 작성 + 즉시 확인
Claude Code 안에서 컴포넌트를 작성한 뒤, playwright screenshot으로 브라우저 없이 화면을 캡처해 Claude에게 보여줍니다.
# Claude Code가 내부적으로 실행하는 방식
npx playwright screenshot --browser chromium http://localhost:3000 screenshot.pngClaude는 캡처된 이미지를 보고 레이아웃, 여백, 색상, 정렬 문제를 즉시 감지하고 피드백합니다.
playwright-cli 스크린샷으로 할 수 있는 것들:
- UI 버그 확인: 레이아웃 깨짐, 겹침, 정렬 문제 시각적 확인
- 작업 전/후 비교: 코드 변경 전후 화면 차이 비교
- 특정 요소 캡처: 페이지 전체가 아닌 특정 컴포넌트만 찍기 (playwright-cli
screenshot e5) - 자동화 테스트 증적: 버그 리포트용 화면 캡처
- 디자인 검토: 실제 렌더링된 결과를 Figma 디자인과 비교
Tip: "지금 화면 캡처해줘"를 개발 중 자주 활용하세요. 코드만 보는 것보다 UI 버그를 훨씬 빠르게 발견할 수 있습니다.
2단계 — 검증: E2E 테스트 자동화
Claude가 테스트 케이스를 작성하고 playwright test를 실행해 결과를 분석합니다.
npx playwright test --reporter=listClaude는 단순히 실행 결과를 보여주는 것을 넘어, 실패 원인을 해석하고 다음 액션을 제안합니다.
Tip: "이 컴포넌트의 Playwright 테스트 먼저 만들어줘, 그 다음 구현해줘" 방식을 사용하면 TDD(테스트 주도 개발)와 자연스럽게 맞물려 더 일관된 코드가 나옵니다.
3단계 — 디버그: 트레이스 + 로그 캡처
테스트가 실패하면 playwright trace로 클릭 경로, 네트워크 요청, 스크린샷 시퀀스를 모두 기록합니다.
# 트레이스와 함께 테스트 실행
npx playwright test --trace on
# 트레이스 파일 확인
npx playwright show-trace trace.zipClaude가 트레이스 파일을 분석해 어떤 요소가 왜 깨졌는지 정확히 특정해줍니다.
브라우저 콘솔 로그와 네트워크 요청도 함께 캡처해서 원인을 다각도로 분석합니다.
4단계 — 수정: 자동 패치 + 재검증
원인이 특정되면 Claude가 직접 코드를 수정하고, 바로 테스트를 재실행해 통과 여부를 확인합니다.
- 사람이 브라우저를 열어 확인하는 과정 없이 루프가 자동으로 돌아갑니다
- 통과하면 머지, 실패하면 다시 디버그 단계로 돌아갑니다
전체 워크플로우 요약
UI 컴포넌트 작성
↓
Dev server 실행 (npm run dev)
↓
playwright screenshot → Claude 시각적 검토
↓
playwright test → 결과 분석
↓ (실패 시)
playwright trace → 콘솔·네트워크 캡처 → 원인 특정
↓
Claude 코드 수정 → 재검증
↓
통과 → 머지 / 실패 → 반복핵심 명령어 정리
# 화면 캡처
npx playwright screenshot --browser chromium http://localhost:3000 out.png
# 테스트 실행
npx playwright test
npx playwright test --reporter=list # 상세 출력
npx playwright test --trace on # 트레이스 포함
# 테스트 코드 자동 생성 (브라우저에서 직접 클릭 → 코드로 변환)
npx playwright codegen http://localhost:3000
# 트레이스 확인
npx playwright show-trace trace.zip
# 특정 브라우저 지정
npx playwright test --browser firefox
npx playwright test --browser webkit실전 팁
playwright codegen 활용하기
브라우저에서 직접 클릭하면 테스트 코드를 자동으로 생성합니다. 이 코드를 Claude Code에 붙여넣으면 Claude가 정리·최적화해줍니다.
npx playwright codegen http://localhost:3000CI 파이프라인 연동
Claude Code가 생성한 테스트를 GitHub Actions에 그대로 붙여 넣으면 PR마다 자동으로 검증되는 파이프라인이 완성됩니다.
# .github/workflows/e2e.yml
name: Playwright E2E Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test멀티 브라우저 동시 검증
Playwright는 Chromium, Firefox, WebKit을 동시에 실행할 수 있습니다. Claude Code에게 "세 브라우저에서 동시에 테스트해줘"라고 하면 됩니다.
npx playwright test --browser all정리
| 단계 | 도구 | Claude의 역할 |
|---|---|---|
| 개발 | playwright screenshot | 화면을 보고 UI 이상 감지 |
| 검증 | playwright test | 테스트 작성 + 결과 해석 |
| 디버그 | playwright trace | 원인 특정 |
| 수정 | 코드 에디터 | 자동 패치 + 재검증 |
Claude Code + Playwright CLI의 핵심은 사람이 브라우저를 열지 않아도 되는 완전 자동화 루프입니다. AI가 눈이 되고, 손이 되어 개발 사이클 전체를 처리하는 것이 목표입니다.
