4.5 KiB
4.5 KiB
name, description
| name | description |
|---|---|
| webapp-testing | Playwright 기반으로 로컬 웹앱을 점검하고 테스트합니다. 프론트엔드 동작 검증, UI 디버깅, 스크린샷, 브라우저 로그 확인이 필요할 때 호출합니다. |
웹앱 테스트
이 스킬은 로컬 웹 애플리케이션을 브라우저에서 실제로 검증하기 위한 Playwright 기반 테스트 가이드입니다.
기본 원칙
- 동적 웹앱은 렌더링이 끝나기 전에 DOM을 섣불리 읽지 않습니다.
- 브라우저 조작 전에 먼저 화면 상태를 관찰합니다.
- 가능하면 기본 제공 스크립트를 블랙박스로 활용합니다.
- 정적인 추측보다 브라우저에서 직접 확인한 셀렉터와 상태를 신뢰합니다.
사용 가능한 보조 스크립트
scripts/with_server.py- 서버 실행과 종료를 관리합니다.
이 스크립트는 먼저 --help로 사용법을 확인한 뒤 사용합니다. 소스를 먼저 읽기보다, 가능한 한 도구처럼 호출하는 방식을 우선합니다.
언제 사용할지
- 로컬 웹앱의 실제 동작을 확인해야 할 때
- 버튼, 폼, 내비게이션, 모달 같은 UI 상호작용을 점검할 때
- 스크린샷이나 브라우저 로그가 필요할 때
- 동적 렌더링 이후의 DOM을 기준으로 문제를 확인해야 할 때
접근 방식 결정
정적 HTML인 경우
- 파일을 직접 읽어 셀렉터를 먼저 확인합니다.
- 그 셀렉터를 바탕으로 Playwright 스크립트를 작성합니다.
- 직접 확인이 부족하면 동적 앱처럼 취급합니다.
동적 웹앱인 경우
- 서버가 안 떠 있다면
with_server.py로 서버 라이프사이클을 관리합니다. - 서버가 이미 떠 있다면 브라우저에서 먼저 정찰한 뒤 조작합니다.
정찰 후 행동 패턴
이 스킬의 기본 패턴은 "정찰 후 행동"입니다.
- 페이지에 접속합니다.
networkidle상태까지 기다립니다.- 스크린샷을 찍거나 렌더링된 DOM을 확인합니다.
- 그 상태를 기준으로 셀렉터를 식별합니다.
- 그 다음 클릭, 입력, 검증 같은 행동을 수행합니다.
정적 분석으로 셀렉터를 추측하는 대신, 실제 렌더링 결과를 기준으로 선택자를 확정합니다.
서버 관리 예시
단일 서버:
python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
복수 서버:
python scripts/with_server.py --server "cd backend && python server.py" --port 3000 --server "cd frontend && npm run dev" --port 5173 -- python your_automation.py
자동화 스크립트 원칙
sync_playwright()를 기본으로 사용합니다.- Chromium은 headless 모드로 실행합니다.
- 페이지 이동 후
page.wait_for_load_state('networkidle')를 호출합니다. - 작업이 끝나면 브라우저를 닫습니다.
with_server.py 사용 원칙
- 먼저
python scripts/with_server.py --help로 옵션을 확인합니다. - 서버가 여러 개인 경우에도 이 스크립트로 생명주기를 한 번에 관리합니다.
- Playwright 스크립트 안에는 서버 시작 로직을 넣지 않습니다.
- 자동화 스크립트는 브라우저 조작에만 집중합니다.
좋은 습관
- 먼저 관찰하고 나중에 조작합니다.
text=,role=, CSS 선택자, ID 등 설명력 있는 셀렉터를 씁니다.- 필요한 경우
wait_for_selector()같은 명시적 대기를 사용합니다. - 스크린샷과 콘솔 로그 수집을 적극 활용합니다.
- 재현이 불안정하면 관찰 스텝을 늘리고, 행동 스텝은 줄여 원인을 좁힙니다.
흔한 실수
- JS가 끝나기 전에 DOM을 확인하는 것
- 서버 실행과 테스트 로직을 뒤섞는 것
- 셀렉터 확인 없이 곧바로 클릭부터 시도하는 것
- 렌더링 전 HTML만 보고 동적 UI 동작을 단정하는 것
기대 결과
이 스킬을 적용한 결과물은 다음을 만족해야 합니다.
- 서버 실행과 테스트 로직이 분리되어 있어야 합니다.
- 브라우저에서 실제 보이는 상태를 기준으로 상호작용이 설계되어야 합니다.
- 셀렉터와 검증 조건이 관찰 결과를 기반으로 정해져야 합니다.
- 필요 시 스크린샷, 콘솔 로그, DOM 확인 결과를 남길 수 있어야 합니다.
목표
이 스킬의 목적은 브라우저에서 실제 사용자 흐름을 검증하고, 화면 기준으로 문제를 발견하며, 재현 가능한 자동화 스크립트를 만드는 것입니다.