playwright-cli-automation

概述

使用 playwright-cli 自动化浏览器交互、测试网页、生成 Playwright 测试代码、调试端到端测试失败。本技能提供全面的浏览器自动化能力，包括页面导航、元素交互、网络模拟、会话管理、测试生成和规范驱动测试工作流。

功能特性

• 浏览器操作：打开、导航、标签页管理、视口调整、快照和截图
• 页面交互：点击、填充、输入、悬停、拖拽、选择、勾选/取消、键盘/鼠标控制、对话框处理
• 网络模拟：使用 URL 模式匹配拦截、模拟、修改和阻断网络请求
• 会话管理：多隔离浏览器会话、持久化配置、连接外部浏览器
• 测试生成：从实时浏览器交互自动生成 Playwright TypeScript 测试代码
• 高级代码执行：运行自定义 Playwright 代码实现地理位置、权限、媒体模拟、iframe、下载
• 存储状态：管理 Cookie、localStorage、sessionStorage 和认证状态持久化
• 调试与追踪：控制台/网络监控、追踪录制、视频捕获、元素检查
• 规范驱动测试：完整的 规划 → 生成 → 修复 工作流用于 Playwright 测试编写与维护

前置条件与安装

• 本地工具：全局安装 playwright-cli：npm install -g @playwright/cli@latest
• 替代方式：若全局命令不可用，通过 npx playwright-cli 使用本地版本
• Playwright 测试：在项目中安装 Playwright：npm init playwright@latest

触发场景

• 场景 1：浏览器自动化 — "打开网页并点击登录按钮"
• 场景 2：测试调试 — "调试失败的 Playwright 测试"
• 场景 3：测试生成 — "帮我生成这个页面的 Playwright 测试"
• 场景 4：网络模拟 — "拦截 API 请求并返回模拟数据"
• 场景 5：追踪录制 — "录制浏览器操作追踪用于分析"
• 场景 6：规范驱动测试 — "执行规范驱动测试流程"
• 场景 7：媒体模拟 — "设置浏览器暗色模式并截图对比"

使用示例

# 基本浏览器操作
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e3
playwright-cli close

# 多会话并发
playwright-cli -s=auth open https://app.com/login
playwright-cli -s=guest open https://app.com

# 调试测试
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
playwright-cli attach tw-XXXX

限制与注意事项

• 需要 playwright-cli 已安装（全局或本地）
• run-code 中的代码必须是单个函数表达式，不支持 import/export/require
• 调试模式需在后台运行测试，等待 "Debugging Instructions" 输出后再 attach
• 存储状态文件包含敏感信息时不要提交到版本控制

参考文档

• references/browser-operations.md — 浏览器打开/关闭、导航、标签页、快照、截图、PDF、原始输出
• references/page-interaction.md — 元素定位、点击、填充、键盘、鼠标、拖拽、表单控件、对话框、eval
• references/network-mocking.md — 路由命令、URL 模式、高级模拟（run-code）
• references/session-management.md — 命名会话、持久化、连接/分离、并发模式
• references/test-generation.md — 自动生成代码、断言、规范驱动测试参考
• references/advanced-code.md — run-code 语法、地理位置、权限、媒体、等待、iframe、下载
• references/storage-state.md — 状态保存/恢复、Cookie、localStorage、sessionStorage、认证复用
• references/debugging.md — 测试运行、调试模式、控制台、请求、追踪、视频、元素属性
• references/spec-driven-testing.md — 规划、生成、修复工作流

许可证

本项目使用许可证，详见 LICENSE 文件。