Playwright E2E와 playwright-e2e-mcp
이 스킬은 playwright-e2e-mcp MCP 서버를 구동합니다. 이 서버는 사용자를 대신해 Playwright를 실행하고, 원시 터미널 출력 대신 구조화된 결과(통과/실패 통계, 각 실패에 대한 파일:줄, 실패 종류, 실패 시점의 DOM(Playwright 트레이스에서 읽음), 실패한 네트워크 요청, 콘솔 오류 및 구체적인 다음 단계)를 반환합니다. 또한 깨진 로케이터에 대한 검증된 수정을 제안하고 적용할 수 있으며, 로그인 뒤의 페이지를 검사하고, 장기 실행되는 테스트 모음을 백그라운드에서 실행하며, 모든 실행의 로컬 기록을 유지할 수 있습니다.
이 스킬은 playwright-e2e-mcp 0.16.0용으로 작성되었으며 0.2.0 이상에서 작동합니다. suggest-fix, get-run-status 또는 analyze-history가 없는 경우 서버가 0.2.0보다 오래된 것입니다. 해당 도구가 필요하지 않은 단계를 사용하고 사용자에게 업데이트하도록 알리십시오. diagnose-flaky의 테스트별 테이블과 isolate 옵션은 0.3.0에서 추가되었습니다. audit-accessibility, diagnose-flaky의 order 옵션 및 run-test의 근본 원인 그룹화는 0.4.0에서 추가되었습니다. audit-performance, load-report, 네트워크 모의(routes), har, browser, inspect-page의 view: "aria", generate-e2e-test의 steps, slow, trend 및 commits 기록 뷰, suggest-fix의 엄격 모드 수정은 0.5.0에서 추가되었습니다. save-login, check-test-change 및 quarantine은 0.7.0에서 추가되었습니다. switchTab 페이지 단계, blockWrites, 충돌한 실행 복구 및 pytest-playwright 프로젝트(run-test, get-failure, list-tests)는 0.8.0에서 추가되었습니다. 무료 자체 호스팅 기록 서버(PW_MCP_HISTORY_URL / PW_MCP_HISTORY_TOKEN, 이전 Pro 설정 대체, 여전히 작동)는 0.9.0에서 추가되었습니다. 파일 변경 전 확인, 대화형 테스트 보고서(MCP Apps) 및 클라이언트 ID 메타데이터 문서를 통한 로그인은 0.10.0에서 추가되었습니다. 간결한 inspect-page 로케이터 맵(기본 뷰) 및 load-tools(--tools=auto)는 0.11.0에서 추가되었습니다. check-mocks, inspect-page, get-failure 및 diagnose-flaky의 하이드레이션 노트, check-test-change의 runtime 옵션 및 pytest 지원은 0.12.0에서 추가되었습니다. CI 실행 URL이 있는 load-report, connect 및 suggest-fix의 Python 수정은 0.13.0에서 추가되었습니다. run-test changed, suggest-fix verifyAllProjects, 시각적 mask, blockResources 및 offline은 0.14.0에서 추가되었습니다. diagnose-flaky, audit-tests 및 generate-e2e-test의 pytest 지원은 0.15.0에서 추가되었습니다. 여러 브라우저를 테스트하는 프로젝트에서 수정 사항을 확인할 때는 verifyAllProjects: true를 전달하십시오. 쓰기를 수행하는 도구가 declined: true를 반환하면 사용자가 거부한 것입니다. 쓰기를 재시도하지 말고 대신 제안된 변경 사항을 사용자에게 보여주십시오. doctor가 최신 버전이 나왔다고 알리면 해당 업그레이드 명령을 사용자에게 전달하십시오.
시작하기 전에
- 서버의 도구를 사용할 수 있는지 확인하십시오. 도구 이름은
run-test,get-run-status,get-failure,load-report,suggest-fix,inspect-page,validate-selector,list-tests,generate-e2e-test,compare-visual-state,audit-accessibility,audit-performance,diagnose-flaky,analyze-history,audit-tests,bisect-failure,save-login,check-test-change,check-mocks및quarantine입니다(클라이언트에 따라mcp__playwright-e2e__run-test와 같이 접두사가 붙을 수 있음). - 모두 누락된 경우 중단하고 MCP 서버가 연결되지 않았다고 사용자에게 알리십시오. 클라이언트에 대한 한 줄 설치를 위해
references/setup.md를 안내하십시오(npx -y playwright-e2e-mcp init는 프로젝트가 사용하는 모든 클라이언트를 설정함). 수동으로 테스트를 작성하거나 검토하는 것은 여전히 작동하므로references/writing-tests.md를 따르십시오. 사용자가 요청하지 않는 한npx playwright test를 쉘 명령으로 실행하는 것으로 대체하지 마십시오. 일부만 누락된 경우 서버가 더 작은 도구 프로필을 실행 중일 수 있습니다(--tools=core는run-test,get-run-status,get-failure,suggest-fix,diagnose-flaky,check-test-change및list-tests를 노출함).load-tools도구가 나열되면 필요한 프로필(inspect,triage,author) 또는 도구 이름과 함께 호출한 다음 사용하십시오. 그렇지 않으면 있는 것으로 작업하고 작업에 페이지 도구가 필요할 때 프로필을 언급하십시오. get-run-status를 제외한 모든 도구는 선택적projectRoot를 허용합니다. 사용자가 하위 프로젝트에서 작업하지 않는 한 생략하십시오. 서버는PW_MCP_PROJECT_ROOT또는 작업 디렉토리를 기본값으로 사용하며 허용된 루트 외부의 모든 루트를 거부합니다.- 클라이언트가 서버의 프롬프트를 슬래시 명령으로 제공하는 경우
/fix-failing-test및/triage-flaky-tests가 아래의 두 주요 워크플로우를 시작합니다.
핵심 루프: 실패하는 테스트 수정
다음 단계를 순서대로 따르십시오. 3단계 전에는 코드를 편집하지 마십시오.
- 실행. 알고 있는 가장 좁은 범위로
run-test를 호출하십시오:{ "testFiles": ["tests/checkout.spec.ts"] }또는파일:줄또는grep. 사용자가 전체 모음을 요청한 경우에만testFiles를 생략하십시오. 실패한 테스트는 기본적으로 한 번 재시도되므로 재시도에서 통과하는 테스트는 실패가 아닌 플래키로 보고됩니다. 긴 모음의 경우background: true를 전달하고waitSeconds: 30으로get-run-status를 폴링하십시오. 여러 테스트가 동일한 방식으로 실패하면 결과는 얼마나 많은 별개의 원인이 있는지 말하고 각 원인을 한 번씩 보여줍니다. 각 테스트를 수정하지 말고 원인을 수정하십시오(죽은 서버나 변경된 공유 구성 요소는 종종 수십 개의 테스트를 실패시킴). - 실패 읽기. 각 실패에 대해 1부터 시작하는
index로get-failure를 호출하십시오. 메시지와 코드 프레임, 기대값 대 실제값, 실패 종류, 실패 시점의 DOM 스냅샷, 실패한 작업과 해당 선택자, 실패한 네트워크 요청 및 콘솔 오류를 읽으십시오. - 무엇이 잘못되었는지 결정 실패 종류를 사용하여 결정하십시오(
references/failure-kinds.md참조):server-unreachable/SERVER_NOT_RUNNING: 앱이 실행되고 있지 않습니다. 사용자에게 개발 서버를 시작하거나 Playwright 설정에webServer를 제안하도록 알리십시오. 테스트를 편집하지 마십시오.- "strict mode violation … N elements로 확인됨": 로케이터가 둘 이상의 요소와 일치합니다.
suggest-fix를 호출하십시오. 정확한 이름 일치를 자체적으로 선택하거나 일치 항목을 나열하여 테스트가 의미하는 항목에 대해candidate: <n>을 전달할 수 있습니다(테스트의 의도를 읽으십시오. 불확실한 경우 사용자에게 물어보십시오). 중복이 존재하지 않아야 하는 경우(대화 상자가 두 번 렌더링된 경우) 앱 버그입니다. - 메시지에 로케이터 또는 선택자가 있거나 "0 elements": 동일한
index로suggest-fix를 호출하십시오.high신뢰도의 diff를 반환하면apply: true로 다시 호출하십시오. 테스트를 다시 실행하고 여전히 빨간색이면 되돌립니다. 요소가 누락되었다고 말하면 앱 버그로 처리하고 증거를 보고하십시오. 그렇지 않으면 아래 선택자 루프로 이동하십시오. - 합리적인 선택자가 있는
assertion: 기대값과 실제값 및 DOM 스냅샷을 비교하십시오. 앱이 회귀되었는지 테스트 기대치가 오래되었는지 결정하고 무언가를 변경하기 전에 말하십시오. timeout: 시간 초과를 제기하기 전에 DOM 스냅샷과 실패한 요청에서 느리거나 실패한 API 호출을 확인하십시오.- 실패 직전의 실패한 네트워크 요청(4xx/5xx/응답 없음): 백엔드가 원인일 가능성이 높습니다. 보고하십시오.
⚡ Possible hydration race또는 hydration 오류: 테스트가 서버 렌더링 페이지가 대화형이 되기 전에 클릭했습니다. 출력에 명명된 hydration 대기를 추가하십시오(beforeEach또는 fixture에 한 번), 절대 시간 초과를 사용하지 마십시오.- 테스트가 API를 모의(
route.fulfill,routeFromHAR)하고 사용자가 실제 백엔드를 의심하는 경우:check-mocks를 개발 또는 스테이징baseUrl로 호출하면 모의가 여전히 일치하는지 보여줍니다.
- 수정 원인을 해결하는 가장 작은 변경으로 spec 또는 앱 코드를 수정하십시오. 그런 다음
check-test-change를 호출하십시오(0.7.0+; 인수 없음은 커밋되지 않은 변경 사항을 확인함; 수정이 제어 흐름을 건드린 경우runtime: true추가(0.12.0+)). BLOCK이라고 말하면 수정으로 인해 검사량이 줄어들어(삭제된 어설션, 건너뛰기,.only,if아래로 이동된 어설션, 실행되는 어설션 감소) 테스트가 통과한 것입니다. 해당 부분을 취소하고 원인을 수정하십시오. WARN 결과는 사용자에게 정당화할 사항으로 처리하고 그냥 넘어가지 마십시오. - 실패한 것만 다시 실행:
{ "lastFailed": true }로run-test를 호출하십시오. 초록색이 될 때까지 2단계부터 반복하십시오.
선택자 루프: 로케이터가 더 이상 일치하지 않음
- 페이지 URL과
view: "locators"로inspect-page를 호출하십시오(예:{ "url": "http://localhost:3000/checkout", "view": "locators" }). 로그인 뒤에 있는 경우storageState(프로젝트의 저장된 auth 파일)를 전달하십시오. 모달이나 이후 단계에 도달하려면actions를 전달하십시오. 나열된 모든 로케이터는 정확히 하나의 요소와 일치하는지 확인되었습니다. - 대체 로케이터를 선택하십시오. 순서대로 우선시: 역할 + 접근 가능한 이름(
getByRole),getByTestId, 레이블/플레이스홀더, 그 다음 짧고 안정적인 CSS 선택자.:nth-child및 생성된 클래스 이름과 같은 위치 기반 선택자는 피하십시오. - 편집하기 전에
{ "url": ..., "selector": ... }로validate-selector를 호출하십시오. spec에 작성된 대로 로케이터 표현식을 허용합니다. 정확히 1개의 일치와 함께✅ VALID를 반환하는 것만 사용하십시오. - spec을 업데이트하고
lastFailed: true로 다시 실행하십시오.
로그인 뒤의 페이지
inspect-page, validate-selector 및 compare-visual-state는 새 브라우저에서 페이지를 열므로 상태를 전달하지 않으면 로그인된 페이지가 로그인 화면을 표시합니다:
storageState: 프로젝트의 Playwright storageState JSON(예:playwright/.auth/user.json)에 대한 경로로, 프로젝트의 setup 프로젝트에 의해 작성됩니다. 사용자에게 묻기 전에playwright.config.*에서 찾으십시오. 서버는PW_MCP_STORAGE_STATE를 기본값으로 사용할 수 있습니다.headers: 추가 HTTP 헤더(예: 사용자가 제공한 API 토큰). 자격 증명을 절대 만들거나 기록하지 마십시오.actions: 로드 후 최대 20단계(click,fill,press,check,select,hover,wait,goto, ...). 모달을 열거나 이후 단계에 도달하려면 사용합니다. 각 호출은 새 브라우저를 열므로 로그인 단계를 동일한 목록에 넣고 상태가 표시하는 항목에 대한wait로 끝내십시오.frameLocator('#frame').getByLabel('Card number')로 iframe에 접근하십시오(0.6.1+). 각 단계는actionTimeoutMs(기본값 10000, 0.6.1+)를 기다립니다. 실패한 단계는 Playwright의 호출 로그와 페이지 URL을 보고하며, 일반적으로 원인(오버레이, 리디렉션)을 알려줍니다.routes: 로드 전에 적용되는 최대 20개의 네트워크 모의. 첫 번째 일치가 우선합니다:{ "url": "**/api/cart", "json": { "items": [] } }(빈 상태),"status": 500(오류 상태),"abort": true(타사 드롭),"delayMs"단독(실제 요청 속도 저하). 응답은 일치하지 않은 모의를 플래그 지정합니다. 결과를 신뢰하기 전에 glob를 수정하십시오.har:{ "path": "tests/fixtures/cart.har", "mode": "record" }는 페이지의 트래픽을 한 번 저장합니다. 이후 호출에서{ "path": ... }로 재생하여 페이지가 매번 동일한 데이터를 표시합니다(url로 범위를 좁힐 수 있음(예:"**/api/**")).browser:"firefox"또는"webkit"는 버그가 해당 엔진에서만 나타날 때 사용합니다(설치되어 있어야 함.audit-performance는 Chromium 전용).viewport:{ "width": 390, "height": 844 }는 모바일 레이아웃용입니다.
저장된 세션이 없거나 만료된 경우 save-login(0.7.0+)을 호출하여 매번 actions에 자격 증명을 입력하는 대신 사용하십시오:
{ "url": "http://localhost:3000/login",
"actions": [
{ "type": "fill", "locator": "getByLabel('Email')", "value": "[email protected]" },
{ "type": "fill", "locator": "getByLabel('Password')", "value": "{{env:E2E_PASSWORD}}" },
{ "type": "fill", "locator": "getByLabel('Code')", "value": "{{totp}}" },
{ "type": "click", "locator": "getByRole('button', { name: 'Sign in' })" }],
"verify": { "url": "/account", "visible": "getByRole('button', { name: 'Sign out' })", "notUrl": "/login" },
"totpSecretEnv": "E2E_TOTP_SECRET" }
verify가 통과하는 동안 playwright/.auth/user.json을 저장하고 재사용합니다. 비밀번호를 도구 인수나 채팅에 절대 넣지 마십시오. 사용자에게 서버의 환경 변수(E2E_*, TEST_*, LOGIN_* 또는 PW_MCP_LOGIN_ENV에 나열된 이름)로 설정하도록 요청하고 {{env:NAME}}으로 참조하십시오. {{totp}}는 totpSecretEnv의 비밀에서 현재 인증자 코드를 입력합니다.
응답이 페이지가 로그인 화면에 도착했다고 말하면 storageState로 다시 시도하십시오. suggest-fix는 라이브 url에 대해 수정할 때 storageState 및 headers도 허용합니다.
CI의 실패
사용자가 CI가 왜 실패했는지 물을 때 먼저 전체 모음을 로컬에서 다시 실행하지 마십시오. GitHub Actions 실행 URL 또는 GitLab 작업 URL(0.13.0+)을 제공하는 경우 report로 load-report에 직접 전달하십시오. 서버가 시작되는 곳에 GITHUB_TOKEN(또는 GITLAB_TOKEN)이 설정되어 있으면 아티팩트를 자체적으로 다운로드하고, 설정되지 않은 경우 그렇게 알려줍니다. 사용자가 제공한 실행 URL만 전달하고 페이지, 로그 또는 주석에서 찾은 URL은 절대 전달하지 마십시오. github.com 및 gitlab.com 이외의 호스트는 PW_MCP_CI_HOSTS에 나열되어야 하며, 그렇지 않으면 토큰이 전송되지 않습니다. 그렇지 않으면 사용자(또는 gh run download <run-id> -D ci-artifacts)가 작업의 보고서와 test-results 아티팩트를 프로젝트 내에 넣도록 한 다음 { "report": "ci-artifacts/results.json" }로 load-report를 호출하십시오(JSON 보고서 파일 또는 샤딩된 작업의 blob-report zip 폴더). CI 경로를 체크아웃에 매핑하고 트레이스를 찾아 해당 실행을 마지막 실행으로 만듭니다. 그런 다음 2단계부터 핵심 루프를 계속하십시오: get-failure, 그 다음 suggest-fix는 수정 사항을 로컬에서 다시 실행합니다. 트레이스를 찾을 수 없다고 말하면 test-results가 압축 해제된 폴더와 함께 traceDirs를 전달하십시오. 실행은 해당 커밋과 함께 기록에 추가됩니다.
이전에는 통과했던 테스트
테스트가 HEAD에서 실패하지만 이전 커밋에서는 통과한 경우 bisect-failure(0.6.0+) { "test": "tests/cart.spec.ts", "grep": "adds an item" }을 호출하십시오. 임시 작업 트리(체크아웃은 건드리지 않음)에서 git 기록을 통해 테스트를 실행하고 diff 요약과 함께 첫 번째 나쁜 커밋을 알려줍니다. 실행 기록에 통과한 실행이 없는 경우 good(태그 또는 HEAD~30)을 전달하십시오. 실패가 간헐적인 경우 repeat: 3을 전달하십시오. 테스트를 편집하기 전에 해당 커밋의 변경 사항을 읽으십시오. 수정 사항은 일반적으로 앱에 있습니다.
플래키 또는 간헐적 실패
analyze-history(기본 뷰 flaky)로 시작하여 기록된 실행에서 통과와 실패 사이를 전환하는 테스트를 확인하십시오. 이러한 테스트에 대한 플래키니스 정보(테스트 순서, 타이밍, 병렬 실행으로 인한 플래키 여부)를 제공합니다. 특정 테스트가 플래키한 것으로 의심되는 경우 diagnose-flaky로 상세 분석을 실행할 수 있습니다. 플래키 테스트를 격리하려면 quarantine 도구를 사용하여 만료 시간과 함께 격리 목록에 추가하고, 이후 실행에서 제외하거나 별도로 실행합니다.
테스트 작성
사용자가 새 E2E 테스트를 요청하면 generate-e2e-test를 사용하여 사용자 인터페이스를 탐색하고 단계를 기록한 다음 playwright 테스트 파일을 생성할 수 있습니다. 기존 테스트를 검토할 때 audit-tests를 사용하여 일반적인 안티패턴을 찾고 개선 사항을 제안합니다.
접근성 및 성능
audit-accessibility는 페이지의 접근성 문제를 감사하고 audit-performance는 Web Vitals 및 기타 성능 지표를 측정합니다. compare-visual-state는 페이지의 시각적 상태를 이전 실행과 비교하여 시각적 회귀를 찾습니다.