webapp-testing

Web Application Testing

To test a local web application, write native Python Playwright scripts.

Available Helper Scripts:

• scripts/with_server.py - Manage server lifecycle (supports multiple servers)

Be sure to first run the script with the --help argumentto see usage. Do not read the source code unless you find after trying to run the script that a custom solution is absolutely necessary. These scripts can be very large, thereby polluting your context window. They are designed to be invoked directly as black-box scripts, not ingested into your context window.

Decision Tree: Choosing Your Approach

用户任务 → 是静态 HTML 吗？
    ├─ 是 → 直接读取 HTML 文件以识别选择器 (selectors)
    │         ├─ 成功 → 使用选择器编写 Playwright 脚本
    │         └─ 失败/不完整 → 视为动态（见下文）
    │
    └─ 否 (动态 Web 应用) → 服务器是否已在运行？
        ├─ 否 → 运行：python scripts/with_server.py --help
        │        然后使用辅助工具 + 编写简化的 Playwright 脚本
        │
        └─ 是 → 侦察并行动：
            1. 导航并等待 networkidle
            2. 截图或检查 DOM
            3. 从渲染状态中识别选择器 (selectors)
            4. 使用发现的选择器执行操作

Example: Using with_server.py

To start a server, first run --help, then use the helper tool:

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

To create an automation script, include only the Playwright logic (the server is managed automatically by the program):

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') # 关键：等待 JS 执行
    # ... 您的自动化逻辑
    browser.close()

Reconnaissance and 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. Perform actions using the discovered selectors

Common Pitfalls

❌ Do notinspect the DOM before a dynamic application waits for networkidle ✅ Alwayswait for page.wait_for_load_state('networkidle')

Best Practices

• Treat bundled scripts as black boxes - To accomplish a task, consider whether one of the scripts available in scripts/ can help. These scripts can reliably handle common complex workflows without cluttering the context window. Use --help to view usage, then invoke directly.
• Use sync_playwright()
• Always close the browser when done
• Use descriptive selectors:text=、role=, CSS selectors, or IDs
• Add appropriate waits:page.wait_for_selector() or page.wait_for_timeout()

Reference Files

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