WebappTesting 中文操作手册

1. 安装结果

已安装成功：

• Skill 名称：webapp-testing
• 安装位置：C:\Users\yzw\.codex\skills\webapp-testing

安装完成后，如 Codex 当前会话未自动识别新技能，建议重启 Codex 以加载新 skill。

2. 这个 Skill 是做什么的

webapp-testing 用来测试本地 Web 应用，核心方式是：

• 使用 Python
• 使用 Playwright
• 针对本地页面做：
• 功能验证
• UI 行为排查
• 截图
• 控制台日志采集

它自带一个辅助脚本：

• scripts/with_server.py：负责启动/等待/关闭本地服务，适合动态 Web 应用测试

3. 使用前准备

你需要本机具备：

1. Python
2. Playwright
3. 被测项目的启动命令（如 npm run dev）

如果只是使用这个 skill 的思路写脚本，最核心的是：

• 本地页面地址明确
• 能识别页面元素选择器
• 动态页面在操作前要先等待 networkidle

4. 官方建议的使用判断

这个 skill 的推荐流程很简单：

情况 A：静态 HTML

如果你测试的是单个 HTML 文件：

1. 直接读取 HTML，先判断页面元素
2. 用 Playwright 通过 file:// 打开
3. 编写点击、输入、截图脚本

情况 B：动态 Web 应用，且服务还没启动

先看帮助：

python C:\Users\yzw\.codex\skills\webapp-testing\scripts\with_server.py --help

帮助信息对应参数如下：

• --server：服务启动命令，可重复传入
• --port：对应服务端口
• --timeout：等待服务就绪超时，默认 30 秒
• command：服务启动成功后要执行的命令

情况 C：动态 Web 应用，且服务已经启动

推荐模式是：

1. 打开页面
2. 等待 networkidle
3. 截图 / 查看 DOM / 查看按钮和输入框
4. 根据真实渲染结果再执行操作

5. 最常用命令

5.1 查看辅助脚本帮助

python C:\Users\yzw\.codex\skills\webapp-testing\scripts\with_server.py --help

5.2 单服务启动后执行自动化脚本

python C:\Users\yzw\.codex\skills\webapp-testing\scripts\with_server.py --server "npm run dev" --port 5173 -- python your_automation.py

适用场景：

• 前端项目只有一个服务
• 启动后页面在 http://localhost:5173

5.3 多服务启动后执行自动化脚本

python C:\Users\yzw\.codex\skills\webapp-testing\scripts\with_server.py --server "cd backend && python server.py" --port 3000 --server "cd frontend && npm run dev" --port 5173 -- python your_automation.py

适用场景：

• 前后端分离
• 后端和前端都需要先启动

6. 推荐脚本模板

下面是一个最小可用模板：

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

    # 在这里做点击、输入、断言、截图等操作

    browser.close()

关键点：

• 建议 headless=True
• 动态页面操作前先 wait_for_load_state("networkidle")
• 脚本结束前记得 browser.close()

7. 三个官方示例怎么用

Skill 自带 3 个示例文件：

• C:\Users\yzw\.codex\skills\webapp-testing\examples\element_discovery.py
• C:\Users\yzw\.codex\skills\webapp-testing\examples\static_html_automation.py
• C:\Users\yzw\.codex\skills\webapp-testing\examples\console_logging.py

7.1 元素探测：element_discovery.py

用途：

• 查看页面上有多少个按钮
• 查看链接
• 查看输入框
• 顺手截图

适合你刚接手一个页面、还不知道该怎么写选择器时先跑一遍。

它的核心动作包括：

• page.locator('button').all()
• page.locator('a[href]').all()
• page.locator('input, textarea, select').all()
• page.screenshot(...)

7.2 静态 HTML 自动化：static_html_automation.py

用途：

• 用 file:// 直接测试本地 HTML 文件
• 做点击、填写表单、提交、截图

适合：

• 原型页面
• 纯静态演示页
• 不依赖启动服务的页面

7.3 控制台日志采集：console_logging.py

用途：

• 抓浏览器控制台输出
• 看页面交互过程中是否有报错或警告

核心方式：

• 给页面绑定 page.on("console", ...)
• 收集日志
• 保存到文件

这个很适合排查：

• 点击后页面没反应
• JS 报错
• 某个前端逻辑没有按预期执行

8. 推荐工作流

如果你要用这个 skill 测一个本地 Web 项目，建议按这个顺序：

1. 先确认项目是静态页还是动态应用
2. 如果未启动服务，先用 with_server.py
3. 打开页面后先等待 networkidle
4. 先做“侦察”：
   - 截图
   - 列出按钮
   - 列出链接
   - 列出输入框
5. 确认选择器后，再写点击、输入、断言
6. 如怀疑前端报错，再加控制台日志采集

9. 常见坑

9.1 没等页面加载完成就查 DOM

这是这个 skill 特别强调的坑。

错误方式：

• 页面刚打开就开始找按钮、找输入框

正确方式：

page.goto("http://localhost:5173")
page.wait_for_load_state("networkidle")

9.2 把辅助脚本当源码去改

官方建议是：

• 先把 scripts/with_server.py 当黑盒工具用
• 先看 --help
• 只有确实不够用时再考虑读源码

9.3 选择器不稳定

优先使用更可读、更稳定的选择器：

• text=
• role=
• id
• 明确 CSS 选择器

10. 一个实战示例

假设你要测试本地前端项目：

• 启动命令：npm run dev
• 端口：5173
• 自动化脚本文件：smoke_test.py

可以这样执行：

python C:\Users\yzw\.codex\skills\webapp-testing\scripts\with_server.py --server "npm run dev" --port 5173 -- python smoke_test.py

而 smoke_test.py 可以先从这个版本开始：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={"width": 1440, "height": 900})

    page.goto("http://localhost:5173")
    page.wait_for_load_state("networkidle")

    page.screenshot(path="home.png", full_page=True)

    print("title:", page.title())
    print("buttons:", len(page.locator("button").all()))

    browser.close()

11. 我对这个 Skill 的简要建议

如果你后面准备用它做持续化测试，建议你把脚本分成三层：

1. 服务管理层：交给 with_server.py
2. 页面侦察层：负责截图、查元素、抓日志
3. 业务测试层：只写登录、查询、提交、断言等逻辑

这样后续维护会更轻松。

如果你愿意，我下一步可以继续帮你补两样东西之一：

1. 基于你自己的项目，直接写一个可运行的 smoke_test.py
2. 再补一份“WebappTesting 常用命令速查表”