Initial commit

2026-06-10 12:49:53 +09:00
commit b159597559
707 changed files with 551154 additions and 0 deletions
@@ -0,0 +1,109 @@
+---
+name: "webapp-testing"
+description: "Playwright 기반으로 로컬 웹앱을 점검하고 테스트합니다. 프론트엔드 동작 검증, UI 디버깅, 스크린샷, 브라우저 로그 확인이 필요할 때 호출합니다."
+---
+
+# 웹앱 테스트
+
+이 스킬은 로컬 웹 애플리케이션을 브라우저에서 실제로 검증하기 위한 Playwright 기반 테스트 가이드입니다.
+
+## 기본 원칙
+
+- 동적 웹앱은 렌더링이 끝나기 전에 DOM을 섣불리 읽지 않습니다.
+- 브라우저 조작 전에 먼저 화면 상태를 관찰합니다.
+- 가능하면 기본 제공 스크립트를 블랙박스로 활용합니다.
+- 정적인 추측보다 브라우저에서 직접 확인한 셀렉터와 상태를 신뢰합니다.
+
+## 사용 가능한 보조 스크립트
+
+- `scripts/with_server.py` - 서버 실행과 종료를 관리합니다.
+
+이 스크립트는 먼저 `--help`로 사용법을 확인한 뒤 사용합니다. 소스를 먼저 읽기보다, 가능한 한 도구처럼 호출하는 방식을 우선합니다.
+
+## 언제 사용할지
+
+- 로컬 웹앱의 실제 동작을 확인해야 할 때
+- 버튼, 폼, 내비게이션, 모달 같은 UI 상호작용을 점검할 때
+- 스크린샷이나 브라우저 로그가 필요할 때
+- 동적 렌더링 이후의 DOM을 기준으로 문제를 확인해야 할 때
+
+## 접근 방식 결정
+
+### 정적 HTML인 경우
+
+- 파일을 직접 읽어 셀렉터를 먼저 확인합니다.
+- 그 셀렉터를 바탕으로 Playwright 스크립트를 작성합니다.
+- 직접 확인이 부족하면 동적 앱처럼 취급합니다.
+
+### 동적 웹앱인 경우
+
+- 서버가 안 떠 있다면 `with_server.py`로 서버 라이프사이클을 관리합니다.
+- 서버가 이미 떠 있다면 브라우저에서 먼저 정찰한 뒤 조작합니다.
+
+## 정찰 후 행동 패턴
+
+이 스킬의 기본 패턴은 "정찰 후 행동"입니다.
+
+1. 페이지에 접속합니다.
+2. `networkidle` 상태까지 기다립니다.
+3. 스크린샷을 찍거나 렌더링된 DOM을 확인합니다.
+4. 그 상태를 기준으로 셀렉터를 식별합니다.
+5. 그 다음 클릭, 입력, 검증 같은 행동을 수행합니다.
+
+정적 분석으로 셀렉터를 추측하는 대신, 실제 렌더링 결과를 기준으로 선택자를 확정합니다.
+
+## 서버 관리 예시
+
+단일 서버:
+
+```bash
+python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
+```
+
+복수 서버:
+
+```bash
+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 확인 결과를 남길 수 있어야 합니다.
+
+## 목표
+
+이 스킬의 목적은 브라우저에서 실제 사용자 흐름을 검증하고, 화면 기준으로 문제를 발견하며, 재현 가능한 자동화 스크립트를 만드는 것입니다.