告别繁琐！本地Web应用自动化测试指南及工具包介绍

告别手动点点点！本地 Web 应用自动化测试指南

不用 的繁琐配置，不用人工一遍遍刷新页面——一个命令启动服务，一段脚本完成测试，前端调试从此进入自动化时代。

这个 Skill 是做什么的？

- 是一套基于 的本地 Web 应用测试工具包。它的核心使命很简单：让你用 脚本替代双手，自动完成浏览器里的所有操作——点击、填表、截图、抓日志，全都能代码化。

这个 skill 不是简单的 封装，而是提供了一整套本地开发场景的完整工作流：

一句话定位：它是给开发者用的"前端机器人"——你说它点哪就点哪，还能截图存证。

它解决了什么痛点？

痛点

传统做法

-

服务启停麻烦

手动开终端启动前端、再开终端启动后端，测完还要一个个关

.py 一键启动多服务，测试完自动清理

JS 异步渲染

用 / 抓到的 DOM 是空的（Vue/React 还没挂载）

执行真实 ，等 后再操作

手动回归测试

每次改代码都要手动点一遍所有功能，枯燥且容易漏

脚本一键跑完全流程，重复执行零成本

Bug 难复现

用户说"点这里然后那里就崩了"，你本地复现不了

脚本精确回放用户路径，配合截图和 log 定位问题

截图存档混乱

手动截图发群里，文件名乱、版本对不上

自动化截图按时间戳命名，可集成到 CI 生成报告

典型场景：

安装

依赖只有一个——：

pip install playwright
playwright install chromium

然后把 - 目录放入项目，或者只拷贝你需要的 / 和 / 即可。

核心武器：.py

这是整个 skill 的"指挥中枢"。它的职责是：启动你的 Web 服务 → 等服务就绪 → 跑测试脚本 → 测试完关闭服务。

单服务场景

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

前后端分离（多服务）

python scripts/with_server.py \
  --server "cd backend && python server.py" --port 3000 \
  --server "cd frontend && npm run dev" --port 5173 \
  -- python your_test.py

背后的流程：

启动后端服务，轮询 :3000 直到就绪启动前端服务，轮询 :5173 直到就绪两个服务都 ready 后，执行 .py测试结束，自动 所有服务进程

服务管理从此不用人肉盯终端，脚本出错或超时也会自动清理，不留僵尸进程。

快速上手：写一个测试脚本

以下是一个完整的用户登录流程测试脚本：

from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    # 1. 启动无头浏览器
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={'width': 1920, 'height': 1080})
    # 2. 访问页面并等待 JS 完全执行
    page.goto('http://localhost:5173')
    page.wait_for_load_state('networkidle')  # 关键！等异步内容加载完
    # 3. 侦察：先截图看看当前页面状态
    page.screenshot(path='step_1_homepage.png', full_page=True)
    # 4. 行动：模拟用户操作
    page.click('text=登录')
    page.fill('#username', 'admin')
    page.fill('#password', 'secret123')
    page.click('button[type="submit"]')
    # 5. 等待跳转完成
    page.wait_for_load_state('networkidle')
    page.screenshot(path='step_2_dashboard.png', full_page=True)
    # 6. 验证：检查关键元素是否存在
    welcome = page.locator('text=欢迎回来').first
    assert welcome.is_visible(), "登录后未显示欢迎语"
    # 7. 清理
    browser.close()
print("测试通过！截图已保存。")

运行命令：

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

输出：

Starting server 1/1: npm run dev
Waiting for server on port 5173...
Server ready on port 5173
Running: python test_login.py
测试通过！截图已保存。
Stopping 1 server(s)...
Server 1 stopped
All servers stopped

侦察-行动模式：动态页面的正确打开方式

这个 skill 倡导的核心方法论叫做

-Then-（先侦察，再行动）。

为什么必须这样？

现代前端框架（Vue、React、）的 DOM 是异步渲染的。页面 HTML 刚下载时可能只有一个空的

，真正的内容要等 JS 执行完才挂载。如果你一上来就查元素，大概率找不到。

正确流程：

Step 1: 导航到页面
    ↓
Step 2: 等待 networkidle（JS 执行完毕）
    ↓
Step 3: 侦察——截图或抓取 DOM，看看实际渲染了什么
    ↓
Step 4: 从渲染结果中识别可用的选择器
    ↓
Step 5: 行动——用确认过的选择器执行点击、填表等操作

侦察脚本示例：自动发现页面元素

from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('http://localhost:5173')
    page.wait_for_load_state('networkidle')
    # 侦察所有按钮
    buttons = page.locator('button').all()
    print(f"发现 {len(buttons)} 个按钮:")
    for i, btn in enumerate(buttons):
        text = btn.inner_text() if btn.is_visible() else "[隐藏]"
        print(f"  [{i}] {text}")
    # 侦察所有链接
    links = page.locator('a[href]').all()
    print(f"\n发现 {len(links)} 个链接:")
    for link in links[:5]:
        print(f"  - {link.inner_text().strip()} -> {link.get_attribute('href')}")
    # 侦察所有输入框
    inputs = page.locator('input, textarea, select').all()
    print(f"\n发现 {len(inputs)} 个输入框:")
    for inp in inputs:
        name = inp.get_attribute('name') or inp.get_attribute('id') or "[未命名]"
        print(f"  - {name}")
    # 保存侦察截图
    page.screenshot(path='discovery.png', full_page=True)
    browser.close()

运行一次侦察脚本，你就拿到了页面上所有可用元素的选择器，然后把这些选择器写进正式的测试脚本即可。

三大实用示例1. 本地静态 HTML 测试（不用服务器）

from playwright.sync_api import sync_playwright
import os
html_path = os.path.abspath('dist/index.html')
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={'width': 1920, 'height': 1080})
    # 直接打开本地 HTML 文件
    page.goto(f'file://{html_path}')
    # 填表并提交
    page.fill('#name', '张三')
    page.fill('#email', 'zhangsan@example.com')
    page.click('button[type="submit"]')
    page.wait_for_timeout(500)
    # 截前后对比图
    page.screenshot(path='before_submit.png', full_page=True)
    browser.close()

适合测试打包后的静态产物，或原型阶段的 HTML demo。

2. 捕获浏览器 日志

from playwright.sync_api import sync_playwright
console_logs = []
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    # 监听 console 事件
    page.on("console", lambda msg: console_logs.append(f"[{msg.type}] {msg.text}"))
    page.goto('http://localhost:5173')
    page.wait_for_load_state('networkidle')
    # 触发可能报错的操作
    page.click('text=Dashboard')
    page.wait_for_timeout(1000)
    browser.close()
# 导出日志
with open('console.log', 'w') as f:
    f.write('\n'.join(console_logs))
print(f"捕获了 {len(console_logs)} 条 console 消息")

前端报错但页面没崩？ 日志里藏着真相。

3. 多服务联调测试

python scripts/with_server.py \
  --server "cd api && python manage.py runserver" --port 8000 \
  --server "cd web && npm run dev" --port 5173 \
  -- python test_e2e.py

一次命令启动后端 API + 前端应用，跑完端到端测试后自动全部关闭。

常见陷阱与最佳实践 常见错误：不等待

page.goto('http://localhost:5173')
# 错误！此时页面可能还是空白的
page.click('text=登录')  # 抛出 TimeoutError

正确做法

page.goto('http://localhost:5173')
page.wait_for_load_state('networkidle')  # 等所有异步请求完成
page.click('text=登录')  # 现在元素一定在 DOM 里了

其他最佳实践

建议

说明

总是用 =True

CI/CD 环境没有图形界面， 是标配

始终 .close()

否则 进程会变成僵尸，吃光内存

选择器优先级

text= > role= > CSS 选择器 > XPath，可读性依次下降

适当加 wait

提交表单后加 (500) 或 ()

截图即证据

每个关键步骤截图，出问题时一眼定位

决策树：我该用哪种方式？

你的任务是什么？
    │
    ├─ 本地静态 HTML 文件？
    │    └─ 直接用 file:// URL 打开，无需服务器
    │
    └─ 动态 Web 应用（Vue/React/Angular）？
         │
         ├─ 服务已经在跑？
         │    └─ 直接写 Playwright 脚本，goto localhost
         │
         └─ 服务没启动？
              └─ 用 with_server.py 启动服务 + 自动跑测试

项目结构

webapp-testing/
├── scripts/
│   └── with_server.py          # 服务生命周期管理（核心）
├── examples/
│   ├── element_discovery.py    # 页面元素侦察示例
│   ├── static_html_automation.py # 静态 HTML 测试示例
│   └── console_logging.py      # 捕获 console 日志示例
├── SKILL.md                    # 完整 API 文档
└── LICENSE.txt

没有冗余的抽象层，没有复杂的配置文件——几个脚本、几段示例、一个核心思路。

总结

- 不是一个重量级的测试框架，而是一个务实的本地 Web 应用调试工具箱。它把 的强大能力，通过 .py 和侦察-行动模式，转化为开发者日常工作中随手可用的高效工具。

它的价值在于降低前端自动化测试的启动成本：

如果你经常遇到这些场景：“改了一行 CSS 要手动刷新 5 个页面看效果”、“用户报了个 bug 我本地复现不了”、“PR 合并前想快速验证主流程没崩”——这个 skill 就是为你准备的。

测试 服务 截图 脚本 侦察 启动