Playwright Pro
AI 코딩 에이전트를 위한 프로덕션 등급 Playwright 테스팅 툴킷입니다.
사용 가능한 명령어
Claude Code 플러그인으로 설치된 경우 다음 명령어를 /pw: 명령어로 사용할 수 있습니다:
| 명령어 | 기능 |
|---|---|
/pw:init | Playwright 설정 — 프레임워크 감지, 설정 생성, CI, 첫 번째 테스트 |
/pw:generate <spec> | 사용자 스토리, URL, 또는 컴포넌트에서 테스트 생성 |
/pw:review | 테스트 검토 — 안티패턴 및 커버리지 갭 확인 |
/pw:fix <test> | 실패하거나 불안정한 테스트 진단 및 수정 |
/pw:migrate | Cypress 또는 Selenium에서 Playwright로 마이그레이션 |
/pw:coverage | 테스트된 부분과 누락된 부분 분석 |
/pw:testrail | TestRail과 동기화 — 케이스 읽기, 결과 푸시 |
/pw:browserstack | BrowserStack에서 실행, 크로스 브라우저 보고서 가져오기 |
/pw:report | 선호하는 형식으로 테스트 보고서 생성 |
빠른 시작 워크플로우
대부분의 프로젝트에 권장되는 순서:
1. /pw:init → 구성, CI 파이프라인 및 첫 번째 스모크 테스트 스캐폴딩
2. /pw:generate → 사양 또는 URL에서 테스트 생성
3. /pw:review → 품질 검증 및 안티패턴 플래그 지정 ← 생성 후 항상 실행
4. /pw:fix <test> → 실패/불안정한 테스트 진단 및 복구 ← CI가 빨간색일 때 실행
검증 체크포인트:
/pw:generate후 — 커밋 전에 항상/pw:review실행; 로케이터 안티패턴과 누락된 어설션을 자동으로 잡아냅니다./pw:fix후 — 전체 스위트를 로컬에서 다시 실행(npx playwright test)하여 수정이 회귀를 초래하지 않는지 확인합니다./pw:migrate후 —/pw:coverage를 실행하여 이전 스위트와의 동등성을 확인한 후 Cypress/Selenium 테스트를 폐기합니다.
예제: 생성 → 검토 → 수정
# 1. 사용자 스토리에서 테스트 생성
/pw:generate "사용자는 이메일과 비밀번호로 로그인할 수 있습니다"
# 생성됨: tests/auth/login.spec.ts
# → Playwright Pro가 인증 템플릿을 사용하여 파일을 생성합니다.
# 2. 생성된 테스트 검토
/pw:review tests/auth/login.spec.ts
# → 플래그: 한 테스트가 page.locator('input[type=password]')를 사용함 — getByLabel('Password') 제안
# → 수정이 자동으로 적용됩니다.
# 3. 로컬에서 확인 실행
npx playwright test tests/auth/login.spec.ts --headed
# 4. CI에서 테스트가 불안정한 경우 진단
/pw:fix tests/auth/login.spec.ts
# → 누락된 웹 우선 어설션 식별; waitForTimeout(2000)을 expect(locator).toBeVisible()로 대체
황금 규칙
- CSS/XPath보다
getByRole()— 마크업 변경에 강함 - 절대
page.waitForTimeout()사용 금지 — 웹 우선 어설션 사용 expect(locator)는 자동 재시도;expect(await locator.textContent())는 재시도하지 않음- 모든 테스트 격리 — 테스트 간 상태 공유 금지
- 설정에
baseURL— 하드코딩된 URL 없음 - 재시도: CI에서
2, 로컬에서0 - 트레이스:
'on-first-retry'— 속도 저하 없이 풍부한 디버깅 - 전역보다 픽스처 —
test.extend()로 상태 공유 - 테스트당 하나의 동작 — 여러 관련 어설션은 허용
- 외부 서비스만 모킹 — 자체 앱은 모킹 금지
로케이터 우선순위
1. getByRole() — 버튼, 링크, 제목, 양식 요소
2. getByLabel() — 레이블이 있는 양식 필드
3. getByText() — 상호작용하지 않는 텍스트
4. getByPlaceholder() — 플레이스홀더가 있는 입력
5. getByTestId() — 의미론적 옵션이 없을 때
6. page.locator() — 최후의 수단으로 CSS/XPath
포함된 내용
- 9가지 스킬 — 상세한 단계별 지침 포함
- 3가지 특화 에이전트: 테스트 아키텍트, 테스트 디버거, 마이그레이션 플래너
- 55개 테스트 템플릿: 인증, CRUD, 체크아웃, 검색, 양식, 대시보드, 설정, 온보딩, 알림, API, 접근성
- 2개의 MCP 서버 (TypeScript): TestRail 및 BrowserStack 통합
- 스마트 훅: 테스트 품질 자동 검증, Playwright 프로젝트 자동 감지
- 6개 참조 문서: 황금 규칙, 로케이터, 어설션, 픽스처, 함정, 불안정한 테스트
- 마이그레이션 가이드: Cypress 및 Selenium 매핑 테이블
통합 설정
TestRail (선택 사항)
export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="[email protected]"
export TESTRAIL_API_KEY="your-api-key"
BrowserStack (선택 사항)
export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"
빠른 참조
reference/ 디렉토리 참조:
golden-rules.md— 10가지 불가침 규칙locators.md— 치트 시트가 포함된 완전한 로케이터 우선순위assertions.md— 웹 우선 어설션 참조fixtures.md— 사용자 정의 픽스처 및 storageState 패턴common-pitfalls.md— 상위 10가지 실수와 수정flaky-tests.md— 진단 명령어 및 빠른 수정
templates/README.md에서 전체 템플릿 인덱스를 확인하세요.
사용 시기
Playwright-pro에 대한 안내나 자동화가 필요할 때 이 스킬을 사용하세요.