使用 awesome-codex-skills 的 webapp-testing 技能基于 Playwright 的本地 Web 应用自动化测试指南【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills本指南围绕 awesome-codex-skills 仓库中的 webapp-testing 技能展开讲解如何用原生 Python Playwright 脚本对本地 Web 应用进行交互、验证前端功能、调试 UI 行为、捕获浏览器截图与查看控制台日志。读完本文你将掌握with_server.py服务生命周期管理脚本的完整用法、静态 HTML 与动态应用的测试决策方法以及侦察-再行动Reconnaissance-Then-Action的可靠测试范式并理解其背后的源码实现。webapp-testing 技能概览webapp-testing 是 awesome-codex-skills 仓库在开发与代码工具分类下提供的一个 Codex 技能见 README.md 中的 Skills 列表其定位是对本地 Web 应用进行定向测试并总结结果。该技能的核心约定非常明确要测试本地 Web 应用直接编写原生 Python Playwright 脚本而不是依赖封装过度的框架。整个技能目录结构如下webapp-testing/ ├── SKILL.md # 技能主文档frontmatter 声明 name / description / license ├── LICENSE.txt # Apache License 2.0 ├── scripts/ │ └── with_server.py # 服务生命周期管理脚本支持多服务 └── examples/ ├── element_discovery.py # 发现页面上的按钮、链接、输入框 ├── static_html_automation.py # 通过 file:// URL 测试静态 HTML └── console_logging.py # 捕获浏览器控制台日志技能 frontmatter 中的description是 Codex 触发该技能的匹配依据Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.——即该技能覆盖四大能力验证前端功能、调试 UI 行为、截图、查看浏览器日志。使用辅助脚本的第一原则黑盒调用SKILL.md 强调了一条重要的使用原则任何脚本都要先用--help查看用法不要一上来就阅读源码。with_server.py这类脚本可能体积很大直接读进上下文会严重污染上下文窗口context window。它们的定位是黑盒脚本直接调用即可只有在确实需要定制化方案时才去阅读源码。这条原则在 SKILL.md 中有明确表述也符合仓库 README 中关于技能设计keep context lean的理念。决策树先判断场景再动手webapp-testing 技能给出了一个清晰的决策树用于在动手前选择正确的测试路径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 文件本身来确定选择器selector无需启动浏览器渲染。如果读取失败或信息不完整则按动态应用处理。动态 Web 应用且服务未启动先运行python scripts/with_server.py --help查看用法再用该辅助脚本管理服务生命周期同时编写精简的 Playwright 脚本。动态 Web 应用且服务已在运行走侦察-再行动流程——导航并等待networkidle、截图或检查 DOM、从渲染结果中识别选择器、用识别出的选择器执行操作。这一决策树的价值在于它把测试本地应用这个模糊任务拆解成可判定的二分问题静态/动态、服务是否已启动从而避免在错误路径上浪费资源。with_server.py 实战服务生命周期管理with_server.py是 webapp-testing 技能唯一的辅助脚本职责是启动一个或多个服务、等待它们就绪、运行你的命令、最后统一清理。单服务器用法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完整参数说明从 with_server.py 的 argparse 定义第 35-40 行可以确认以下参数参数类型必填说明--server可重复追加是服务启动命令如npm run dev可多次指定--port可重复追加int是每个服务对应的端口数量必须与--server一致--timeoutint否每个服务就绪等待超时秒数默认 30 秒command剩余参数是服务就绪后要运行的命令--之后的部分底层实现原理阅读 with_server.py 源码可以确认其执行流程参数校验第 44-55 行自动剥离命令前的--分隔符若--server与--port数量不匹配直接报错退出若未提供要执行的命令同样报错退出。顺序启动服务第 63-83 行对每个服务使用subprocess.Popen(..., shellTrue)启动。注释明确指出使用shellTrue是为了支持包含cd和的命令如cd backend python server.py。端口就绪轮询第 23-32 行is_server_ready()函数通过socket.create_connection((localhost, port), timeout1)探测端口每 0.5 秒重试一次直到超时默认 30 秒。连接成功即认为服务就绪。执行用户命令第 84-89 行全部服务就绪后打印All N server(s) ready然后用subprocess.run(args.command)运行用户命令并以其返回码作为脚本退出码。finally 清理第 91-102 行无论成功失败都会依次terminate()所有服务进程若 5 秒内未退出则升级为kill()。这正是该脚本能保证服务不会残留的关键设计。编写自动化脚本Playwright 核心模式服务由with_server.py管理后你的自动化脚本只需包含纯 Playwright 逻辑。SKILL.md 给出了标准骨架from playwright.sync_api import sync_playwright with sync_playwright() as p: browser p.chromium.launch(headlessTrue) # 始终以 headless 模式启动 chromium page browser.new_page() page.goto(http://localhost:5173) # 服务已由 helper 启动并就绪 page.wait_for_load_state(networkidle) # 关键等待 JS 执行完成 # ... 你的自动化逻辑 browser.close()要点解读使用sync_playwright()同步 API脚本采用同步风格逻辑直观适合顺序执行的操作序列。始终headlessTrueSKILL.md 特别注释要求 chromium 必须用无头模式启动避免弹出浏览器窗口。服务地址直接可访问因为with_server.py已经等待服务就绪脚本中page.goto()时可以假设服务已可用。wait_for_load_state(networkidle)是 CRITICAL 级别的要求动态应用必须等待网络空闲确保 JavaScript 执行完毕后再继续否则后续元素定位可能落空。侦察-再行动模式Reconnaissance-Then-Action对于已经运行中的动态应用webapp-testing 推荐侦察-再行动三步流程第 1 步侦察渲染后的 DOMpage.screenshot(path/tmp/inspect.png, full_pageTrue) content page.content() page.locator(button).all()通过整页截图、获取页面 HTML 内容、枚举元素三种手段先看清页面真实渲染后的样子。第 2 步从侦察结果中识别选择器根据截图和 DOM 内容确定可靠的定位方式按钮文本、链接 href、输入框 name/id、CSS 选择器等。第 3 步用发现的选择器执行操作page.click(textClick Me) page.fill(#name, John Doe) page.click(button[typesubmit])这种模式的精髓在于永远基于渲染后的真实状态来定位元素而不是凭对源码的臆测从而大幅降低选择器失效的概率。常见陷阱不要在 networkidle 之前检查 DOMSKILL.md 特别标注了一个高频错误❌ 不要在动态应用上未等待 networkidle 就检查 DOM ✅ 应该先 page.wait_for_load_state(networkidle) 再检查原因很直接SPA 等动态应用在初始 HTML 加载后还有大量 JS 异步渲染过早读取 DOM 会得到空壳页面导致找不到元素的误判。等待网络空闲是动态应用测试的前提条件。最佳实践清单综合 SKILL.md 的最佳实践章节与示例源码可以归纳出以下实战准则把内置脚本当黑盒用优先判断scripts/中的脚本能否完成当前任务它们覆盖了常见复杂工作流且不污染上下文用--help查看用法后直接调用。同步 API统一使用sync_playwright()。用完关闭浏览器browser.close()必须执行避免资源泄漏。使用描述性选择器优先text、role、CSS 选择器或元素 ID而不是脆弱的 XPath。适当等待根据场景使用page.wait_for_selector()或page.wait_for_timeout()。三个官方示例的深度解读1. element_discovery.py页面元素侦察element_discovery.py 演示了如何系统化地发现页面元素按钮page.locator(button).all()枚举所有按钮用inner_text()读取文本不可见元素标记为[hidden]。链接page.locator(a[href]).all()枚举带 href 的链接输出文本与目标地址示例只打印前 5 个。输入框page.locator(input, textarea, select).all()枚举表单控件优先取name属性、其次id否则标为[unnamed]同时输出type属性。截图留证最后保存整页截图/tmp/page_discovery.png作为视觉参考。这正对应决策树中从渲染状态识别选择器的落地实现先摸清页面有什么再决定怎么操作。2. static_html_automation.pyfile:// 协议测静态页面static_html_automation.py 展示了测试静态 HTML 的路径html_file_path os.path.abspath(path/to/your/file.html) file_url ffile://{html_file_path}关键点用os.path.abspath()把相对路径转绝对路径再拼成file://URL浏览器即可直接加载本地文件无需启动任何服务器。可设置视口viewport{width: 1920, height: 1080}模拟桌面分辨率。操作前无需等待networkidle静态页面没有异步网络请求可直接点击、填表、提交。该示例展示了完整交互闭环填写表单字段page.fill(#name, ...)、提交表单page.click(button[typesubmit])、wait_for_timeout(500)等待提交结果、前后各截一张图对比。这也印证了决策树中静态 HTML → 直接识别选择器 → 写脚本的路径静态场景不需要服务器with_server.py都可以省掉。3. console_logging.py控制台日志捕获console_logging.py 演示了技能描述的查看浏览器日志能力def handle_console_message(msg): console_logs.append(f[{msg.type}] {msg.text}) print(fConsole: [{msg.type}] {msg.text}) page.on(console, handle_console_message)核心机制通过page.on(console, handler)注册监听器在浏览器控制台产生消息log、warning、error、info 等由msg.type标识时实时捕获。交互操作如点击 Dashboard触发的日志会被完整记录。最后将日志写入文件示例中为/mnt/user-data/outputs/console.log便于事后分析。这对调试 UI 行为尤其有用前端报错、警告、调试输出都能被自动化流程捕获而不需要人工打开 DevTools。在 Codex 中安装与触发该技能webapp-testing 是仓库内的标准技能目录安装方式遵循仓库统一的技能安装流程见 README.md 的 Quickstart 与 Using Skills in Codex 章节将该技能目录webapp-testing/复制到$CODEX_HOME/skills/默认~/.codex/skills/或使用仓库提供的 skill-installer 辅助脚本安装。重启 Codex 使其重新加载技能元数据。在会话中自然描述任务如测试本地 Web 应用的前端功能Codex 会根据 SKILL.md frontmatter 中的description自动触发该技能也可直接提及技能名。验证安装是否成功ls ~/.codex/skills查看已安装技能列表head ~/.codex/skills/webapp-testing/SKILL.md检查元数据。总结webapp-testing 技能将本地 Web 应用测试压缩为三个可复用的技术杠杆决策树——静态/动态、服务是否就绪快速定位测试路径with_server.py——一个黑盒脚本接管服务生命周期启动、端口轮询、命令执行、finally 清理自动化脚本只保留纯 Playwright 逻辑侦察-再行动 networkidle——动态应用的可靠测试范式配合截图、DOM 侦察与描述性选择器把测试脚本的稳定性放在第一位。结合 examples 目录下三个可直接参考的示例元素发现、静态 HTML 自动化、控制台日志捕获读者可以从零搭建一个覆盖验证功能、调试 UI、截图留证、日志分析的完整本地应用测试流水线。【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考