Playwright Autopilot

Selenium, Cypress 또는 WebDriverIO를 사용 중이신가요? E2Epilot은 Selenium Java, SeleniumBase 등을 포함한 6개의 프레임워크에 동일한 AI 트리아지 엔진을 제공합니다. 웹사이트: e2epilot.com | npm: @e2epilot/cli

Playwright E2E 테스트를 자율적으로 디버깅하고 수정하는 Claude Code 플러그인입니다. 전체 액션 캡처(DOM 스냅샷, 네트워크 요청, 콘솔 출력, 스크린샷)와 함께 테스트를 실행한 다음, 시니어 QA 엔지니어처럼 실패 원인을 조사하고 수정 사항을 적용합니다.

https://github.com/user-attachments/assets/26f734a5-d05e-41c9-bc3f-2b58561c2ce0

빠른 시작

# Add the marketplace
/plugin marketplace add kaizen-yutani/playwright-autopilot

# Install the plugin
/plugin install kaizen-yutani/playwright-autopilot

그런 다음 Claude에게 실패한 테스트를 수정하거나 전체 스위트를 트리아지하도록 요청하세요:

/playwright-autopilot:fix-e2e tests/checkout.spec.ts
/playwright-autopilot:triage-e2e e2e

또는 필요한 작업을 설명하기만 하면 Claude가 MCP 도구를 자동으로 사용합니다:

Fix all failing e2e tests in the "e2e" project

Related MCP server: Browser Testing MCP Server

주요 기능

테스트 실행 중 모든 브라우저 액션은 다음 정보와 함께 캡처됩니다:

• 전/후 DOM 스냅샷 — 각 클릭, 입력, 탐색 전후 페이지의 aria 트리

• 네트워크 요청 — URL, 메서드, 상태, 타이밍, 요청/응답 본문

• 콘솔 출력 — 해당 액션과 관련된 오류, 경고, 로그

• 스크린샷 — 실패 시점의 화면

테스트가 실패하면 Claude는 추측하지 않습니다. 실제 페이지 상태를 읽고, 실패한 API 호출을 확인하며, 액션 타임라인을 통해 근본 원인을 추적합니다.

작동 원리

1. 캡처 훅

경량 CJS 훅(captureHook.cjs)이 NODE_OPTIONS --require를 통해 Playwright의 테스트 워커 프로세스에 주입됩니다. 이 훅은 BrowserContext._initialize를 몽키 패치하여 모든 브라우저 액션을 전체 컨텍스트와 함께 캡처하는 계측 리스너를 추가합니다. Playwright 소스 코드를 수정할 필요가 없으며, 모든 Playwright 설치 환경에서 작동합니다.

2. MCP 도구

이 플러그인은 Claude가 필요할 때 호출할 수 있는 37개의 도구를 Model Context Protocol을 통해 제공합니다. 이는 토큰 효율성을 고려하여 설계되었습니다. 전체 트레이스를 컨텍스트에 덤프하는 대신, Claude는 필요한 정보만 가져옵니다:

테스트 실행 및 디버깅:

대화형 브라우저 탐색:

browser_* 도구는 실제 Chrome 인스턴스를 실행하여 Claude가 애플리케이션을 대화형으로 탐색할 수 있게 합니다. 페이지 탐색, 요소 클릭, 폼 작성, ARIA 스냅샷을 통한 페이지 상태 관찰이 가능합니다. 각 상호작용은 타이밍, 네트워크 요청, DOM 변경 사항 및 업데이트된 스냅샷을 반환합니다. 이를 사용하여 테스트를 작성하기 전에 앱을 이해하거나, UI 문제를 시각적으로 디버깅하거나, 수정 사항을 검증하세요.

3. 흐름 메모리

테스트를 수정(또는 검증)한 후, 플러그인은 확인된 애플리케이션 흐름(성공적인 경로를 구성하는 사용자 상호작용 시퀀스)을 저장합니다. 이러한 흐름은 .e2e-flows.json에 유지되며 세션 전반에 걸쳐 누적됩니다.

다음에 해당 테스트가 실패하면, Claude는 이미 의도된 사용자 여정을 알고 있으므로 무엇이 변경되었는지 즉시 파악합니다. 에이전트는 시간이 지날수록 더 똑똑해집니다.

4. 불안정성(Flaky) 감지

불안정한 테스트를 식별하기 위한 두 가지 보완 모드:

retries: N — 별도의 Playwright 프로세스에서 테스트를 N+1번 실행합니다. 각 실행은 전체 액션 캡처와 함께 고유한 runId를 가집니다. FLAKY, CONSISTENT PASS, CONSISTENT FAIL 중 하나를 판정합니다. 2-3회 재시도 디버깅에 가장 적합합니다.

e2e_run_test(location: "tests/checkout.spec.ts:15", retries: 2)

repeatEach: N — 네이티브 Playwright --repeat-each를 사용합니다. 모든 반복이 하나의 프로세스에서 실행됩니다. 불안정성을 확인하기 위한 빠른 스트레스 테스트입니다. 신뢰도를 위해 30-100회를 권장합니다.

e2e_run_test(location: "tests/checkout.spec.ts:15", repeatEach: 40)

5. 증거 번들

e2e_get_evidence_bundle은 오류, 재현 단계, 액션 타임라인, 실패한 네트워크 요청 및 본문, 콘솔 오류, DOM 스냅샷, 스크린샷 등 모든 실패 증거를 단일 응답으로 패키징합니다. 6개 이상의 도구를 별도로 호출할 필요가 없습니다.

outputFile: true를 전달하면 Jira 첨부 파일을 위해 test-reports/에 마크다운 파일을 작성합니다.

6. HTML 보고서

배치 실행(location 없음)은 자동으로 독립형 HTML 보고서를 생성합니다:

• 상태 배지가 포함된 통과/실패 요약

• 테스트별 접기 가능한 섹션

• 액션 타임라인, 실패한 네트워크 요청, 콘솔 오류

• 실패 지점의 DOM 스냅샷

• 인라인 base64 이미지로 포함된 스크린샷

보고서는 test-reports/report-<runId>.html에 작성됩니다. 언제든지 e2e_generate_report를 수동으로 호출할 수도 있습니다.

7. 스위트 트리아지 및 상태 추적

전체 스위트를 실행하고 모든 실패를 분류하여 관리자용 보고서를 생성합니다:

/playwright-autopilot:triage-e2e e2e

Claude는 각 실패를 알려진 문제(Known Issue), 앱 버그(App Bug), 테스트 업데이트(Test Update), 불안정(Flaky), 또는 **새로운 실패(New Failure)**로 분류합니다. 기존 티켓에 대해 Jira를 상호 참조하고, 앱 버그에 대해서는 증거 번들을 포함한 새 티켓을 생성하며, 추세 추적을 위해 트리아지 실행 결과를 저장합니다.

e2e_get_stats는 테스트를 다시 실행하지 않고도 로컬 기록을 기반으로 통과율 추세, 점수별 불안정 테스트 순위, 실패 카테고리 분석 등 스위트 상태 대시보드를 제공합니다.

9. 커버리지 분석

e2e_suggest_tests는 전체 프로젝트를 스캔하여 커버리지 격차를 찾습니다:

1. 테스트되지 않은 페이지 객체 메서드 — 스펙에서 호출하지 않는 .page.ts / .service.ts 파일 내 메서드

2. 누락된 흐름 변형 — 연속 변형이 없는 사전 조건(예: "초안 없음")이 있는 흐름

3. 커버되지 않은 흐름 단계 — 스펙에서 실행하지 않는 확인된 흐름에 나열된 액션

10. 아키텍처 인식

수정 사항을 작성하기 전에 플러그인은 프로젝트의 페이지 객체, 서비스 계층 및 테스트 픽스처를 스캔합니다. 기존 패턴을 따릅니다:

• 원시 Playwright 호출 대신 페이지 객체 모델(Page Object Model) 메서드 사용

• 비즈니스/서비스 계층 분리 존중

• getByRole(), getByTestId(), 웹 우선 어설션 사용

• 최소한의 diff 생성 — 일반적으로 한두 줄 추가

디버깅 철학

이 플러그인은 엄격한 진단 방법론을 따릅니다:

셀렉터가 아닌 사용자 흐름으로 생각합니다. 코드를 수정하기 전에 의도된 사용자 여정을 매핑합니다. 드롭다운이 선택되지 않거나 필수 필드가 채워지지 않는 등 단계가 누락된 경우, 기존 페이지 객체 메서드를 찾아 호출을 추가합니다.

4가지 근본 원인 카테고리:

1. 테스트 단계 누락 — 앱이 요구하는 UI 상호작용을 테스트가 건너뜀

2. 테스트 코드 버그 — 잘못된 셀렉터, 오래된 어설션, 잘못된 테스트 데이터

3. 애플리케이션 버그 — 앱 자체가 고장남 (우회하지 않고 보고됨)

4. 더러운 상태 — 이전 테스트 실행의 잔여물이 간섭함

핵(Hack)을 사용하지 않습니다. 플러그인은 실패한 테스트를 우회하기 위해 page.evaluate(), page.route(), page.addInitScript() 또는 기타 JavaScript 주입을 절대 사용하지 않습니다. 수정에 그러한 방법이 필요하다면, 그것은 잘못된 문제를 해결하고 있는 것입니다.

설정

다중 프로젝트 설정

Playwright 프로젝트가 Claude Code가 실행되는 디렉토리와 다른 곳에 있다면, .mcp.json에서 PW_PROJECT_DIR 환경 변수를 설정하세요:

{
  "mcpServers": {
    "playwright-autopilot": {
      "command": "node",
      "args": ["path/to/plugin/server/mcp-server.js"],
      "env": {
        "PW_PROJECT_DIR": "/path/to/your/playwright/project"
      }
    }
  }
}

요구 사항

• Claude Code CLI

• Playwright 테스트 프로젝트

• Node.js 20+

라이선스

MIT