---
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 확인 결과를 남길 수 있어야 합니다.

## 목표

이 스킬의 목적은 브라우저에서 실제 사용자 흐름을 검증하고, 화면 기준으로 문제를 발견하며, 재현 가능한 자동화 스크립트를 만드는 것입니다.
