webapp-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Application Testing

Web应用测试

To test local web applications, write native Python Playwright scripts.

Helper Scripts Available:

```
scripts/with_server.py
```
- Manages server lifecycle (supports multiple servers)

Always run scripts with
--help
first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is absolutely necessary.

要测试本地Web应用，请编写原生Python Playwright脚本。

可用辅助脚本:

```
scripts/with_server.py
```
- 管理服务器生命周期（支持多服务器）

请始终先使用
--help
运行脚本查看使用方法。除非在尝试运行脚本后发现确实需要定制化解决方案，否则不要直接阅读源代码。

Decision Tree: Choosing Your Approach

决策树：选择合适的方法

User task → Is it static HTML?
    ├─ Yes → Read HTML file directly to identify selectors
    │         ├─ Success → Write Playwright script using selectors
    │         └─ Fails/Incomplete → Treat as dynamic (below)
    │
    └─ No (dynamic webapp) → Is the server already running?
        ├─ No → Run: python scripts/with_server.py --help
        │        Then use the helper + write simplified Playwright script
        │
        └─ Yes → Reconnaissance-then-action:
            1. Navigate and wait for networkidle
            2. Take screenshot or inspect DOM
            3. Identify selectors from rendered state
            4. Execute actions with discovered selectors

用户任务 → 是否为静态HTML？
    ├─ 是 → 直接读取HTML文件以定位选择器
    │         ├─ 成功 → 使用选择器编写Playwright脚本
    │         └─ 失败/不完整 → 按动态应用处理（见下方）
    │
    └─ 否（动态Web应用） → 服务器是否已运行？
        ├─ 否 → 运行：python scripts/with_server.py --help
        │        然后使用辅助脚本 + 编写简化的Playwright脚本
        │
        └─ 是 → 先侦察再执行：
            1. 导航至页面并等待networkidle状态
            2. 截取截图或检查DOM
            3. 从渲染状态中定位选择器
            4. 使用找到的选择器执行操作

Example: Using with_server.py

示例：使用with_server.py

To start a server, run

--help

first, then use the helper:

Single server:

bash

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

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

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

To create an automation script, include only Playwright logic (servers are managed automatically):

python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
    page = browser.new_page()
    page.goto('http://localhost:5173') # Server already running and ready
    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
    # ... your automation logic
    browser.close()

要启动服务器，请先运行

--help

查看帮助，然后使用辅助脚本：

单服务器：

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

要创建自动化脚本，只需包含Playwright逻辑（服务器将自动管理）：

python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
    page = browser.new_page()
    page.goto('http://localhost:5173') # Server already running and ready
    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
    # ... your automation logic
    browser.close()

Reconnaissance-Then-Action Pattern

先侦察再执行模式

Inspect rendered DOM:

python

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

Identify selectors from inspection results
Execute actions using discovered selectors

检查渲染后的DOM:

python

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

从检查结果中定位选择器
使用找到的选择器执行操作

Common Pitfall

常见误区

❌ Don't inspect the DOM before waiting for

networkidle

on dynamic apps ✅ Do wait for

page.wait_for_load_state('networkidle')

before inspection

❌ 不要在动态应用中未等待

networkidle

状态就检查DOM ✅ 务必在检查前等待

page.wait_for_load_state('networkidle')

Best Practices

最佳实践

Use bundled scripts as black boxes - To accomplish a task, consider whether one of the scripts available in
```
scripts/
```
can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use
```
--help
```
to see usage, then invoke directly.
Use
```
sync_playwright()
```
for synchronous scripts
Always close the browser when done
Use descriptive selectors:
```
text=
```
,
```
role=
```
, CSS selectors, or IDs

Add appropriate waits:

page.wait_for_selector()

page.wait_for_timeout()

将打包脚本视为黑盒 - 要完成任务时，先考虑
```
scripts/
```
目录下的可用脚本是否能提供帮助。这些脚本可可靠处理常见的复杂工作流，且不会占用上下文窗口空间。使用
```
--help
```
查看用法后直接调用即可。
同步脚本使用
```
sync_playwright()
```
完成操作后务必关闭浏览器
使用描述性选择器：
```
text=
```
,
```
role=
```
, CSS选择器或IDs

添加适当的等待：

page.wait_for_selector()

或

page.wait_for_timeout()

Reference Files

参考文件

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

examples/ - 展示常见模式的示例：
- ```
element_discovery.py
```
  - 发现页面上的按钮、链接和输入框
- ```
static_html_automation.py
```
  - 对本地HTML使用file:// URLs
- ```
console_logging.py
```
  - 自动化过程中捕获控制台日志

User task → Is it static HTML? ├─ Yes → Read HTML file directly to identify selectors │ ├─ Success → Write Playwright script using selectors │ └─ Fails/Incomplete → Treat as dynamic (below) │ └─ No (dynamic webapp) → Is the server already running? ├─ No → Run: python scripts/with_server.py --help │ Then use the helper + write simplified Playwright script │ └─ Yes → Reconnaissance-then-action: 1. Navigate and wait for networkidle 2. Take screenshot or inspect DOM 3. Identify selectors from rendered state 4. Execute actions with discovered selectors

用户任务 → 是否为静态HTML？ ├─ 是 → 直接读取HTML文件以定位选择器 │ ├─ 成功 → 使用选择器编写Playwright脚本 │ └─ 失败/不完整 → 按动态应用处理（见下方） │ └─ 否（动态Web应用） → 服务器是否已运行？ ├─ 否 → 运行：python scripts/with_server.py --help │ 然后使用辅助脚本 + 编写简化的Playwright脚本 │ └─ 是 → 先侦察再执行： 1. 导航至页面并等待networkidle状态 2. 截取截图或检查DOM 3. 从渲染状态中定位选择器 4. 使用找到的选择器执行操作

from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode page = browser.new_page() page.goto('http://localhost:5173') # Server already running and ready page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute # ... your automation logic browser.close()