{"id":29196113,"url":"https://github.com/terryso/claude-code-playwright-mcp-test","last_synced_at":"2025-07-02T06:02:38.343Z","repository":{"id":299159830,"uuid":"1002213651","full_name":"terryso/claude-code-playwright-mcp-test","owner":"terryso","description":"A YAML-based Playwright MCP automation testing framework designed for Claude Code","archived":false,"fork":false,"pushed_at":"2025-06-24T02:15:00.000Z","size":1707,"stargazers_count":38,"open_issues_count":1,"forks_count":5,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2025-06-24T03:26:09.670Z","etag":null,"topics":["claudecode","playwright"],"latest_commit_sha":null,"homepage":"https://terryso.github.io/blog/yaml-playwright-testing-revolution","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terryso.png","metadata":{"files":{"readme":"README.cn.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T00:53:32.000Z","updated_at":"2025-06-24T02:15:04.000Z","dependencies_parsed_at":"2025-06-15T03:37:16.873Z","dependency_job_id":null,"html_url":"https://github.com/terryso/claude-code-playwright-mcp-test","commit_stats":null,"previous_names":["terryso/claude-code-playwright-mcp-test"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/terryso/claude-code-playwright-mcp-test","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terryso%2Fclaude-code-playwright-mcp-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terryso%2Fclaude-code-playwright-mcp-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terryso%2Fclaude-code-playwright-mcp-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terryso%2Fclaude-code-playwright-mcp-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terryso","download_url":"https://codeload.github.com/terryso/claude-code-playwright-mcp-test/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terryso%2Fclaude-code-playwright-mcp-test/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263083490,"owners_count":23411160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claudecode","playwright"],"created_at":"2025-07-02T06:00:41.942Z","updated_at":"2025-07-02T06:02:38.254Z","avatar_url":"https://github.com/terryso.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude 测试框架 - 演示项目\n\n[![GitHub stars](https://img.shields.io/github/stars/terryso/claude-code-playwright-mcp-test.svg)](https://github.com/terryso/claude-code-playwright-mcp-test/stargazers)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/terryso/claude-code-playwright-mcp-test/pulls)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Claude Code](https://img.shields.io/badge/Claude-Code-blue.svg)](https://claude.ai/code)\n[![Playwright MCP](https://img.shields.io/badge/Playwright-MCP-green.svg)](https://github.com/microsoft/playwright-mcp)\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-项目文档-blue)](https://deepwiki.com/terryso/claude-code-playwright-mcp-test)\n[![claude-test CLI](https://img.shields.io/badge/claude--test-CLI-orange.svg)](https://github.com/terryso/claude-test)\n\n\u003e **中文文档** | **[English Documentation](README.md)**\n\n**[claude-test CLI框架](https://github.com/terryso/claude-test)** 的**实时演示项目** - 展示由 **Claude Code + Playwright MCP** 驱动的智能自动化测试，具备基于自然语言的YAML测试配置、动态元素定位、多环境支持和会话持久化功能。\n\n## 🚀 关于本项目\n\n这是 **[claude-test CLI工具](https://github.com/terryso/claude-test)** 的**演示和示例项目**。虽然本项目包含可运行的测试用例和完整文档，但**实际的框架代码和CLI命令已迁移到官方 `claude-test` npm包中**。\n\n## 🧠 Playwright MCP 工作原理 - 核心创新\n\n### 🎯 革命性元素定位系统\n\n与传统的Playwright自动化依赖脆弱的CSS选择器或XPath表达式不同，**Playwright MCP使用革命性的动态元素识别系统**：\n\n```mermaid\nflowchart TD\n    A[\"🌐 网页加载完成\"] --\u003e B[\"🔍 Playwright MCP 扫描页面\"]\n    B --\u003e C[\"🏷️ 为每个元素分配唯一 ref_id\"]\n    C --\u003e D[\"📋 创建可访问性快照\"]\n    D --\u003e E[\"🤖 Claude Code 接收元素映射\"]\n    E --\u003e F[\"🗣️ 用户编写自然语言步骤\"]\n    F --\u003e G[\"🎯 Claude 将描述匹配到 ref_id\"]\n    G --\u003e H[\"⚡ 执行精确操作\"]\n    \n    style A fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#ffffff\n    style B fill:#2196F3,stroke:#1565C0,stroke-width:3px,color:#ffffff\n    style C fill:#FF9800,stroke:#F57C00,stroke-width:3px,color:#ffffff\n    style D fill:#9C27B0,stroke:#6A1B9A,stroke-width:3px,color:#ffffff\n    style E fill:#F44336,stroke:#C62828,stroke-width:3px,color:#ffffff\n    style F fill:#607D8B,stroke:#37474F,stroke-width:3px,color:#ffffff\n    style G fill:#3F51B5,stroke:#283593,stroke-width:3px,color:#ffffff\n    style H fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#ffffff\n```\n\n#### 🎯 **动态ref_id生成**\n当Playwright MCP访问网页时，会自动：\n1. **扫描页面上所有可交互元素**（按钮、输入框、链接等）\n2. **为每个元素动态分配唯一的ref_id属性**\n3. **创建包含元素描述和对应ref_id的可访问性快照**\n4. **将此映射提供给Claude Code**进行智能元素选择\n\n#### 🎯 **智能元素选择**\nClaude Code无需猜测选择器，可以：\n- **准确看到页面上存在哪些元素**，包含人类可读的描述\n- **通过唯一的ref_id引用元素**，100%准确定位\n- **避免传统自动化中脆弱的选择器失败**问题\n- **处理动态内容**，无需手动更新选择器\n\n#### 🎯 **自然语言到精确操作**\n```yaml\n# 你的YAML测试步骤:\n- \"Click Add to Cart button for first product\"\n\n# 幕后发生的过程:\n# 1. Playwright MCP识别所有\"Add to Cart\"按钮\n# 2. 分配ref_ids: button[ref_id=\"addcart_123\"], button[ref_id=\"addcart_456\"]\n# 3. Claude Code智能选择第一个: ref_id=\"addcart_123\"\n# 4. 执行精确的点击操作，无需猜测选择器\n```\n\n#### 🎯 **相比传统自动化的优势**\n| 传统方法 | Playwright MCP方法 |\n|---------|------------------|\n| `page.click('#add-cart-btn-1')` | Claude看到\"Sauce Labs Backpack的Add to Cart按钮\"及其ref_id |\n| 脆弱的CSS选择器 | 动态元素识别 |\n| HTML变化时会失效 | 自动适应页面结构变化 |\n| 需要手动维护 | 自愈性元素检测 |\n| 多次重试尝试 | 首次即可准确定位 |\n\n**这就是我们基于YAML的方法如此强大的原因** - **你用自然语言编写，Playwright MCP自动处理复杂的元素定位**。\n\n## 🎬 演示视频\n\n观看YAML-based Playwright测试的实际演示：\n\n[![YAML Playwright Testing Demo](https://img.youtube.com/vi/tx3xExU_Xhc/maxresdefault.jpg)](https://www.youtube.com/watch?v=tx3xExU_Xhc)\n\n**📺 [观看演示视频](https://www.youtube.com/watch?v=tx3xExU_Xhc)** - 了解如何使用Claude Code和Playwright MCP通过自然语言编写和执行测试。\n\n## 🌟 主要特性\n\n- **🌍 多环境支持**: 支持dev/test/prod环境，自动加载对应配置\n- **📚 步骤库复用**: 可复用的参数化步骤库，提高测试效率\n- **🗣️ 自然语言**: 直接使用自然语言描述测试步骤，易读易写\n- **🔧 环境变量**: 从.env文件自动加载配置，安全管理敏感信息\n- **📊 智能报告**: 可配置的测试报告生成，支持内嵌数据的HTML/JSON格式\n- **📝 智能提示**: Claude Code项目命令支持参数提示\n- **🚀 会话持久化**: 革命性的跨命令会话持久化，一次登录终生受益\n- **⚡ 性能提升**: 首次登录后80-95%的性能提升，极速测试执行\n\n## 🗺️ 开发路线图\n\n我们正在积极开发令人兴奋的新功能，让基于YAML的测试更加强大：\n\n### ✅ 已完成特性\n\n#### ✅ **Cursor IDE 支持** - **已完成** 🎉\n- **✅ 项目规则集成**: 完整的 `.mdc` 规则文件，实现Cursor AI集成\n- **✅ 命令支持**: 在Cursor中完整支持 `/run-yaml-test` 命令\n- **✅ 会话持久化**: 在Cursor中实现与Claude Code相同的80-95%性能提升\n- **✅ 跨平台兼容**: 统一框架在两个IDE中无缝运行\n\n#### ✅ **测试套件支持** - **已完成** 🎉\n- **✅ 套件组织**: 将相关测试用例组织成逻辑套件\n- **✅ 批量执行**: 用单个命令运行整个测试套件\n- **✅ 套件级配置**: 每个套件的环境变量和设置\n- **✅ 套件报告**: 跨多个测试用例的聚合报告\n- **✅ 前置/后置操作**: 套件级的设置和清理操作\n- **✅ 验证命令**: 完整的套件验证功能\n\n```yaml\n# 示例: test-suites/e-commerce.yml\nname: \"电商测试套件\"\ndescription: \"完整的电商工作流测试\"\ntags:\n  - e-commerce\n  - integration\ntest-cases:\n  - \"test-cases/order.yml\"\n  - \"test-cases/product-details.yml\"\n  - \"test-cases/sort-optimized.yml\"\n```\n\n**可用的套件命令**:\n- `/run-test-suite suite:e-commerce.yml env:test`\n- `/validate-test-suite suite:smoke-tests.yml env:dev`\n\n### 📅 发布时间表\n\n| 特性 | 状态 | 预期发布 |\n|------|------|----------|\n| ✅ Cursor IDE 支持 | ✅ **已完成** | ✅ **已发布** |\n| ✅ 测试套件支持 | ✅ **已完成** | ✅ **已发布** |\n\n## 🚀 快速开始\n\n### 1. 安装 claude-test CLI\n\n```bash\nnpm install -g claude-test\n```\n\n### 2. 安装 Playwright MCP\n\n```bash\nclaude mcp add playwright -- npx -y @playwright/mcp@latest \\\n  --user-data-dir ~/.cache/claude-playwright \\\n  --storage-state ~/.cache/claude-playwright/auth-state.json \\\n  --save-trace \\\n  --output-dir ~/CascadeProjects/claude-code-playwright-mcp-test/screenshots\n```\n\n### 3. 初始化新项目（替代使用此演示项目）\n\n```bash\n# 创建包含框架的新项目\ncd your-new-project\nclaude-test init\n```\n\n### 4. 或使用此演示项目\n\n```bash\n# 克隆演示项目\ngit clone https://github.com/terryso/claude-code-playwright-mcp-test.git\ncd claude-code-playwright-mcp-test\n\n# 执行订单测试\n/run-yaml-test file:test-cases/order.yml env:dev\n\n# 查看报告\n/view-reports-index\n```\n\n### 简单的YAML测试示例\n\n```yaml\n# test-cases/example.yml\ntags:\n  - smoke\nsteps:\n  - include: \"login\"\n  - \"Click Add to Cart button for first product\"\n  - \"Click shopping cart icon\"\n  - \"Verify cart contains 1 item\"\n```\n\n## 📚 文档\n\n- **📖 [安装指南](docs/cn/installation.md)** - 详细的安装说明\n- **🏗️ [项目结构](docs/cn/project-structure.md)** - 理解框架结构\n- **⚡ [命令详解](docs/cn/commands.md)** - 完整的命令文档\n- **📝 [YAML格式说明](docs/cn/yaml-format.md)** - 编写测试用例和步骤库\n- **🔧 [环境配置](docs/cn/environment-config.md)** - 多环境设置\n- **✨ [最佳实践](docs/cn/best-practices.md)** - 有效测试的技巧\n\n## 📊 最新测试结果\n\n**📈 [最新测试报告](reports/test/latest-test-report.html)** - 每次测试运行后自动生成，显示详细的执行结果、截图和性能指标。\n\n## 💡 功能请求\n\n有新功能的想法？我们很乐意听到您的声音！\n- 提交 [Issue](https://github.com/terryso/claude-code-playwright-mcp-test/issues) 并添加 `enhancement` 标签\n- 参与我们的社区讨论\n- 为路线图规划贡献力量\n\n## 🤝 贡献指南\n\n1. Fork 项目\n2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\n3. 提交更改 (`git commit -m 'Add some amazing feature'`)\n4. 推送到分支 (`git push origin feature/amazing-feature`)\n5. 开启 Pull Request\n\n## 📄 许可证\n\n本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\n\n## 📺 相关资源\n\n### 🛠️ 官方CLI工具\n- **📦 [claude-test CLI](https://github.com/terryso/claude-test)** - **框架管理的官方CLI包**\n- **📥 [NPM包](https://www.npmjs.com/package/claude-test)** - 通过npm全局安装\n- **📋 [CLI文档](https://github.com/terryso/claude-test#readme)** - 完整使用指南和API参考\n\n### 📖 学习资源\n- **🎬 [演示视频](https://www.youtube.com/watch?v=tx3xExU_Xhc)** - 框架实际演示\n- **📈 [最新测试报告](reports/test/latest-test-report.html)** - 最近的测试执行结果\n- **📖 [Medium文章](https://medium.com/@oxtiger/stop-writing-brittle-playwright-tests-why-yaml-based-testing-is-the-future-5cc90a81bfa2)** - 详细解释和优势\n\n### 🔧 工具和集成\n- **🛠️ [Claude Code](https://claude.ai/code)** - AI驱动的开发环境\n- **🎭 [Playwright MCP](https://github.com/microsoft/playwright-mcp)** - 浏览器自动化集成\n\n## 🆘 支持\n\n### CLI工具问题\n- **🐛 [CLI问题](https://github.com/terryso/claude-test/issues)** - 报告CLI缺陷或功能请求\n- **📖 [CLI文档](https://github.com/terryso/claude-test#readme)** - 完整CLI使用指南\n\n### 演示项目问题\n1. 观看[演示视频](https://www.youtube.com/watch?v=tx3xExU_Xhc)获取视觉指导\n2. 查看[文档](docs/cn/)\n3. 检查 [演示项目Issues](https://github.com/terryso/claude-code-playwright-mcp-test/issues) \n4. 创建新的Issue描述问题\n5. 在Claude Code中使用 `/help` 获取更多帮助\n\n## 🔗 相关项目\n\n- **📦 [claude-test CLI](https://github.com/terryso/claude-test)** - 框架管理的官方CLI工具\n- **🎬 [演示视频](https://www.youtube.com/watch?v=tx3xExU_Xhc)** - YAML测试的实时演示\n- **📖 [Medium文章](https://medium.com/@oxtiger/stop-writing-brittle-playwright-tests-why-yaml-based-testing-is-the-future-5cc90a81bfa2)** - 框架深度解析\n\n---\n\n**测试愉快！🚀**\n\n*此演示项目展示了[claude-test CLI框架](https://github.com/terryso/claude-test)的强大功能。对于新项目，请全局安装CLI并使用`claude-test init`开始。*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterryso%2Fclaude-code-playwright-mcp-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterryso%2Fclaude-code-playwright-mcp-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterryso%2Fclaude-code-playwright-mcp-test/lists"}