📌 참고: 이 문서는 공식 Claude Code 문서의 원문 + 레퍼런스입니다.

• 원문 링크를 직접 사용하셔도 됩니다
• 이 파일을 .claude/skills/ 하위에 복사하여 스킬로 등록할 수도 있습니다

(2026.03.15 기준)

웹 애플리케이션 테스팅

로컬 웹 애플리케이션을 테스트하려면 네이티브 Python Playwright 스크립트를 작성하세요.

사용 가능한 헬퍼 스크립트:

• scripts/with_server.py - 서버 생명주기 관리 (다중 서버 지원)

항상 스크립트를 --help와 함께 먼저 실행하세요 사용법을 확인하기 위해. 스크립트를 먼저 실행해보고 맞춤 솔루션이 절대적으로 필요하다고 판단되기 전까지는 소스를 읽지 마세요. 이 스크립트들은 매우 클 수 있어 컨텍스트 윈도우를 오염시킵니다. 이 스크립트들은 컨텍스트 윈도우에 내용을 주입하기보다 블랙박스 스크립트로서 직접 호출되도록 만들어졌습니다.

의사결정 트리: 접근 방식 선택

사용자 작업 --> 정적 HTML인가?
    |-- 예 --> HTML 파일을 직접 읽어 셀렉터 식별
    |         |-- 성공 --> 셀렉터를 사용하여 Playwright 스크립트 작성
    |         +-- 실패/불완전 --> 동적으로 취급 (아래 참조)
    |
    +-- 아니오 (동적 웹앱) --> 서버가 이미 실행 중인가?
        |-- 아니오 --> 실행: python scripts/with_server.py --help
        |              그런 다음 헬퍼를 사용하고 + 간소화된 Playwright 스크립트 작성
        |
        +-- 예 --> 정찰 후 행동:
            1. 네비게이션 후 networkidle 대기
            2. 스크린샷 촬영 또는 DOM 검사
            3. 렌더링된 상태에서 셀렉터 식별
            4. 발견된 셀렉터로 액션 실행

예제: with_server.py 사용

서버를 시작하려면 먼저 --help를 실행한 다음 헬퍼를 사용하세요:

단일 서버:

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

자동화 스크립트를 만들 때는 Playwright 로직만 포함하세요 (서버는 자동으로 관리됩니다):

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # 항상 chromium을 headless 모드로 실행
    page = browser.new_page()
    page.goto('http://localhost:5173') # 서버가 이미 실행 중이며 준비 완료
    page.wait_for_load_state('networkidle') # 중요: JS 실행 완료 대기
    # ... 자동화 로직
    browser.close()

정찰 후 행동 패턴

1. 렌더링된 DOM 검사:

   page.screenshot(path='/tmp/inspect.png', full_page=True)
   content = page.content()
   page.locator('button').all()
   

2. 검사 결과에서 셀렉터 식별

3. 발견된 셀렉터를 사용하여 액션 실행

흔한 실수

• 하지 마세요: 동적 앱에서 networkidle을 기다리기 전에 DOM을 검사하는 것
• 하세요: 검사 전에 page.wait_for_load_state('networkidle')을 기다리기

모범 사례

• 번들된 스크립트를 블랙박스로 사용하세요 - 작업을 수행할 때 scripts/에 있는 스크립트 중 도움이 될 수 있는 것이 있는지 고려하세요. 이 스크립트들은 컨텍스트 윈도우를 어지럽히지 않으면서 일반적이고 복잡한 워크플로우를 안정적으로 처리합니다. --help로 사용법을 확인한 다음 직접 호출하세요.
• 동기식 스크립트에 sync_playwright() 사용
• 완료 시 항상 브라우저 닫기
• 서술적 셀렉터 사용: text=, role=, CSS 셀렉터, 또는 ID
• 적절한 대기 추가: page.wait_for_selector() 또는 page.wait_for_timeout()

참조 파일

• examples/ - 일반적인 패턴을 보여주는 예제:
  • element_discovery.py - 페이지에서 버튼, 링크, 입력 요소 발견
  • static_html_automation.py - 로컬 HTML에 file:// URL 사용
  • console_logging.py - 자동화 중 콘솔 로그 캡처