webapp-testing

Web Application Testing

To test a local web application, write a Python Playwright script.

Available helper scripts:

• scripts/with_server.py - Server lifecycle management (supports multiple servers)

Always run the script with --helpfirstto check usage. Try running the script directly and do not read the source code until you determine that a custom solution is absolutely necessary. These scripts are very large and can pollute the context window. They are designed to be called directly as black-box scripts rather than being included in the context.

Decision Tree: Choosing an Approach

사용자 작업 → 정적 HTML인가?
    ├─ 예 → HTML 파일을 직접 읽어 셀렉터(selectors) 식별
    │         ├─ 성공 → 식별된 셀렉터로 Playwright 스크립트 작성
    │         └─ 실패/불충분 → 동적 앱으로 간주 (아래 참조)
    │
    └─ 아니오 (동적 웹앱) → 서버가 이미 실행 중인가?
        ├─ 아니오 → 실행: python scripts/with_server.py --help
        │            그다음 헬퍼를 사용하여 간소화된 Playwright 스크립트 작성
        │
        └─ 예 → 정찰 후 행동(Reconnaissance-then-action):
            1. 이동(Navigate) 후 networkidle 상태까지 대기
            2. 스크린샷 캡처 또는 DOM 검사
            3. 렌더링된 상태에서 셀렉터 식별
            4. 찾은 셀렉터로 작업 수행

Example: Using with_server.py

To start the server, first run --helpand then use the helper:

Single server:

python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py

Multiple servers (e.g., backend + frontend):

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

When writing automation scripts, include only the Playwright logic (servers are managed automatically):

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()

Reconnaissance-Then-Action Pattern

1. Inspect the rendered DOM:

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

2. Identify selectors from the inspection results

3. Execute the action using the found selector

Pitfalls to watch out for

❌ Bad: Inspecting the DOM in a dynamic app without waiting for the networkidle state ✅ Good: Calling page.wait_for_load_state('networkidle')to wait before inspecting

Best Practices

• Use bundled scripts as black boxes - When performing a task, consider whether scripts in scripts/could help. These scripts reliably handle complex common workflows without cluttering the context window. Check usage with --helpand then call them directly.
• Use sync_playwright()for synchronous scripts.
• Always close the browser when the task is finished.
• Use descriptive selectors: text=, role=, CSS selectors, or IDs.
• Add appropriate wait times: page.wait_for_selector() or page.wait_for_timeout().

Reference Files

• examples/ - Examples showing common patterns:
  • element_discovery.py - Finding buttons, links, and input fields on a page
  • static_html_automation.py - Using file:// URLs for local HTML
  • console_logging.py - Capturing console logs during automation