webapp-testing

網頁應用程式測試

若要測試本地網頁應用程式，請撰寫原生的 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
    page = browser.new_page()
    page.goto('http://localhost:5173') # 伺服器已在執行並準備就緒
    page.wait_for_load_state('networkidle') # 關鍵：等待 JavaScript 執行完畢
    # ... 你的自動化邏輯
    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 - 使用 file:// URL 處理本地 HTML
  • console_logging.py - 在自動化過程中擷取主控台日誌