프론트엔드 테스트 디버깅은(는) 무엇을 하나요?

호출 계약

이 스킬은 일반 사용자 프롬프트로 작동해야 합니다. 사용자가 브라우저 라우팅, 스크린샷, 보고서 형식 또는 대체 정책을 구체적으로 설명하도록 요구하지 마십시오.

사용자가 Build Web Apps 플러그인, 웹 개발 플러그인, 프론트엔드 개발 플러그인 또는 렌더링된 프론트엔드 변경, 테스트, 버그 조사를 위한 프론트엔드 테스트/디버깅 스킬을 사용하도록 요청할 때 이 스킬을 사용하십시오.

이 전체 워크플로우를 트리거해야 하는 예시:

웹 대시보드 거래 검색 영역을 개선해 주세요. 웹 개발 플러그인을 사용해 주세요.
프론트엔드 개발 플러그인을 사용하여 이 대시보드를 다듬어 주세요.
Build Web Apps 플러그인으로 이 UI를 디버깅해 주세요.
이 localhost 앱을 테스트하고 깨진 상호작용을 수정해 주세요.

간단한 프롬프트에서 리포지토리, 현재 열려 있는 앱/브라우저 URL, 주변 파일 또는 실행 중인 개발 서버로부터 대상 표면을 유추하십시오. 대상 URL이 불명확하면 사용자에게 묻기 전에 리포지토리 스크립트와 실행 중인 로컬 포트를 검사하십시오.

렌더링된 프론트엔드 표면에 대한 코드 변경이 있는 경우, 기본적으로 다음 검증 루프를 수행하십시오:

대상 흐름을 식별합니다.
아래 브라우저 경로를 선택합니다.
가장 작은 유용한 편집을 수행합니다.
렌더링된 동작을 검증합니다.
QA 최종 응답 보고서로 회신합니다.

브라우저 경로 선택

먼저 브라우저 가용성을 분류합니다:

사용 가능: Browser 플러그인과 그 browser 스킬이 세션에 나열되어 있습니다. 브라우저 작업 전에 해당 스킬을 읽고 따르십시오.
없음: Browser 플러그인 또는 browser 스킬이 나열되지 않았습니다. 일반 Playwright를 사용하고 Browser plugin not available (Browser 플러그인을 사용할 수 없음)을 기록하십시오.
호출 실패: Browser는 사용 가능해 보이지만, 스킬/런타임, Node REPL JavaScript 설정, 탭 획득 또는 탐색이 실패합니다. 이를 Browser 경로 차단기로 처리하십시오.

Browser를 사용할 수 있는 경우 일반 Playwright, 외부 Chrome 또는 셸 open을 먼저 사용하지 마십시오.

실패한 Browser 호출에서 일반 Playwright로 전환하는 것은 사용자가 이미 대체를 허용했거나 작업이 명시적으로 비Browser 검증을 허용하는 경우에만 가능합니다. 이 경우 정확한 Browser 실패와 대체 결정을 보고하십시오.

대상 흐름

브라우저 검증 전에 대상 흐름을 한 문장으로 정의하십시오:

테스트 중인 흐름: [진입 경로] -> [사용자 동작 또는 상태] -> [예상 렌더링 결과].

사용자가 일반 스모크 테스트를 요청한 경우 다음을 사용하십시오:

테스트 중인 흐름: 앱 로드 -> 첫 번째 의미 있는 화면 렌더링 -> 기본 가시 컨트롤이 런타임 오류 없이 응답합니다.

Browser 플러그인 루프

Browser 스킬에서 설명하는 Node REPL JavaScript 도구를 통해 Browser 명령을 실행하십시오. 별도의 브라우저 설정 경로를 만들지 마십시오. Browser 스킬에서 달리 명시하지 않는 한 동일한 탭 바인딩을 계속 사용하십시오.

필수 순서:

Browser 스킬이 지시하는 대로 정확히 Browser 런타임을 로드합니다.
agent.browser.nameSession("...")으로 세션 이름을 지정합니다.
agent.browser.tabs.selected() 또는 agent.browser.tabs.new()로 탭을 획득합니다.
tab.goto(url)로 이동합니다.
아래 필수 검사를 실행합니다.
범위가 지정된 tab.playwright 로케이터 또는 Browser 스킬 상호작용 API와 상호작용합니다.
편집 후 await tab.reload()를 호출한 다음, 검사와 실패한 상호작용을 반복합니다.

각 UI 변경 동작에 대해 다음 상태가 올바르다는 가장 저렴한 증거를 수집하십시오: 새로운 DOM 스냅샷, 가시 텍스트/상태, URL 변경, 포커스된 컨트롤, 토스트, 모달, 스크린샷 또는 콘솔 로그.

필수 Browser 검사

렌더링된 앱이 작동한다고 주장하기 전에 다음 검사를 실행하십시오:

페이지 정체성: await tab.url() 및 await tab.title()이 의도한 페이지와 일치합니다.
빈 페이지 아님: await tab.playwright.domSnapshot()에 빈 셸이 아닌 의미 있는 앱 콘텐츠가 포함되어 있습니다.
프레임워크 오버레이 없음: 스냅샷 또는 스크린샷에 Next.js, Vite, Webpack 또는 프레임워크 오류 오버레이가 표시되지 않습니다.
콘솔 상태: await tab.dev.logs({ levels: ["error", "warn"], limit: 50 })에 관련 앱 오류가 없거나 각 관련 오류가 설명됩니다.
스크린샷 증거: await display(await tab.playwright.screenshot({ fullPage: false }))가 시각적 주장을 뒷받침합니다.
상호작용 증명: 최소 하나의 대상 흐름 상호작용이 실행되고 상태 확인이 이어집니다.

시각적 작업의 경우 실용적일 때 데스크톱 및 하나의 모바일 크기 뷰포트를 추가하십시오. 참조 기반 작업의 경우 짧은 불일치 원장을 유지하십시오: 참조 증거, 렌더링된 증거, 수정 또는 의도된 편차.

Playwright 루프

Browser를 사용할 수 없거나, 사용자가 Browser 호출 실패 후 대체를 허용한 경우 이 분기를 사용하십시오.

다음 순서를 사용하십시오:

package.json에서 스크립트를 찾습니다.
리포지토리의 패키지 관리자로 앱을 시작하고 요청된 호스트를 정확하게 유지합니다.
리포지토리의 e2e 스크립트가 있으면 선호합니다.
그렇지 않으면 Playwright가 구성된 경우 pnpm exec playwright test 또는 패키지 관리자에 상응하는 명령을 실행합니다.
프로젝트 Playwright 워크플로우가 없으면 pnpm exec playwright --version으로 Playwright를 확인한 다음, pnpm exec playwright screenshot <url> /tmp/frontend-check.png로 스크린샷을 캡처합니다.
더 깊은 디버깅의 경우, URL을 열고 콘솔 오류를 캡처하고 스크린샷을 찍고 대상 상호작용을 실행하는 작은 임시 Playwright 스크립트를 커밋된 소스 외부에 만듭니다.
편집 후 동일한 명령 또는 스크립트를 다시 실행합니다.

작업에 필요하고 사용자가 종속성 변경을 허용하지 않는 한 새로운 브라우저 종속성을 설치하지 마십시오.

검증 체크리스트

요청된 호스트를 정확하게 유지합니다.
컨트롤이 실제 UI 상태를 업데이트하는지 확인합니다.
스크롤하기 전 첫 번째 뷰포트와 실용적일 때 데스크톱 및 하나의 모바일 크기 뷰포트를 확인합니다.
잘림, 겹침, 읽을 수 없는 텍스트, 줄바꿈, 레이아웃 이동, 누락된 에셋, z-index 문제, 스크롤 트랩, 오래된 로딩, 깨진 상태를 찾습니다.
참조 기반 작업의 경우 렌더링된 스크린샷을 참조와 비교하고 짧은 불일치 원장을 유지합니다.
렌더링된 검증이 요청된 경우 빌드 통과만으로는 충분하지 않습니다.

QA 최종 응답 보고서

사소하지 않은 렌더링된 UI 검증 실행의 경우, QA 엔지니어가 코드 변경을 검증하는 것처럼 최종 응답을 작성하십시오. 응답을 통해 사용자 또는 PR 리뷰어가 무엇이 변경되었는지, 무엇이 테스트되었는지, 어떤 증거가 이를 입증하는지, 무엇이 테스트되지 않았는지 쉽게 이해할 수 있어야 합니다.

다음 형식을 사용하십시오:

요약: 사용자에게 보이는 변경 사항과 QA 통과 여부를 설명하는 한두 개의 글머리 기호.
환경: URL, 뷰포트, Browser 가용성 분류, Playwright가 사용된 경우 대체 사유.
확인된 변경 사항: 변경된 파일 또는 표면과 예상되는 특정 사용자 대면 동작.
검사: 페이지 정체성, 빈 페이지 확인, 프레임워크 오버레이 확인, 콘솔 상태, 스크린샷 증거, 상호작용 증명에 대한 통과/실패 표.
상호작용 루프: 테스트된 정확한 상호작용 경로(실행된 컨트롤 또는 워크플로우 및 관찰된 상태 변경 포함).
증거: QA 섹션에서 스크린샷 증거를 설명하고, 실제 스크린샷을 응답 끝에 연속 이미지로 배치하십시오. 관련 있는 이전, 이후, 상호작용, 반응형, 오류 또는 수정된 상태를 입증하는 데 유용한 만큼 많은 스크린샷을 포함하십시오.
명령 / Browser API: 시끄러운 로그를 덤프하지 않고 사용된 주요 명령 및 Browser API 시퀀스를 나열합니다.
남은 위험: 테스트되지 않은 뷰포트, 흐름, 브라우저, 데이터 상태 또는 알려진 제한 사항.

문제가 발견된 경우 요약 앞에 발견 사항을 먼저 제시하십시오. 각 발견 사항에는 사용자가 보는 내용, 재현 단계, 스크린샷/DOM/콘솔 증거, 알려진 경우 소유자 또는 파일, 그리고 수행된 수정 또는 남은 차단기가 포함되어야 합니다.

사용자에게 표시되어야 하는 Browser 스크린샷을 사용하는 경우, 채팅에서 참조할 수 있도록 Browser 런타임을 통해 스크린샷을 내보내거나 표시하십시오. Playwright 스크린샷을 사용하는 경우 리포지토리 외부에 저장하고 채팅에서 참조하십시오. 고유한 상태 또는 흐름을 확인하는 데 도움이 되는 경우 여러 스크린샷을 포함하십시오.

작성된 보고서 전체에 스크린샷을 산재시키지 마십시오. 맨 끝에 짧은 스크린샷 섹션을 넣고, 한 줄에 하나의 이미지로 연속 이미지 갤러리로 만드십시오. 상태를 명확히 하는 경우에만 짧은 레이블(예: 이전, 이후, 필터링된 결과, 빈 상태, 모바일)을 추가하십시오.

기본적으로 별도의 HTML 보고서를 만들지 마십시오. 사용자가 명시적으로 요청한 경우에만 독립 실행형 보고서 파일을 만들고, 사용자가 명시적으로 커밋된 아티팩트를 요청하지 않는 한 리포지토리 외부에 작성하십시오.

사용자가 명시적으로 커밋된 아티팩트를 요청하지 않는 한 리포지토리에 보고서, 스크린샷, 추적 또는 임시 스크립트를 작성하지 마십시오.

최종 응답

위의 QA 최종 응답 보고서 형식을 사용하십시오. 간결하게 유지하되, PR 리뷰어가 즉시 재실행하지 않고도 검증을 신뢰할 수 있을 만큼 충분한 구체적인 증거를 포함하십시오.

Browser가 없었고 Playwright가 사용된 경우, 인앱 네비게이션, 스크린샷, DOM 스냅샷, 콘솔 로그 및 상호작용 검증을 통해 더 나은 프론트엔드 개발 경험을 위해 사용자에게 Browser 플러그인 설치를 제안하는 것으로 마무리하십시오.

프론트엔드 테스트 디버깅