277 lines
9.2 KiB
Markdown
277 lines
9.2 KiB
Markdown
# Playwright浏览器自动化技能
|
||
|
||
`浏览器自动化` `Playwright` `Claude技能` `测试` `Python`
|
||
|
||
# Claude Code 的 Playwright 技能
|
||
|
||
**作为 Claude 技能的通用浏览器自动化工具**
|
||
|
||
这是一个 [Claude 技能](https://www.anthropic.com/blog/skills)，使 Claude 能够即时编写和执行任意 Playwright 自动化脚本——从简单的页面测试到复杂的多步骤流程。以 [Claude Code 插件](https://docs.claude.com/en/docs/claude-code/plugins) 的形式打包，便于安装和分发。
|
||
|
||
Claude 会根据您的浏览器自动化需求自主决定何时使用此技能，仅加载特定任务所需的最少信息。
|
||
|
||
使用 Claude Code 构建。
|
||
|
||
## 功能特性
|
||
|
||
- **任意自动化任务** - Claude 针对您的具体需求编写自定义代码，不局限于预置脚本
|
||
- **默认可见浏览器** - 通过 `headless=False` 实时查看自动化过程
|
||
- **零模块解析错误** - 通用执行器确保正确的模块访问
|
||
- **渐进式信息披露** - 简洁的 SKILL.md，完整 API 参考仅在需要时加载
|
||
- **安全清理** - 智能临时文件管理，无竞态条件
|
||
- **全面的辅助函数** - 常见任务的可选工具函数
|
||
- **PEP 723 元数据** - 所有脚本包含内联依赖规范
|
||
- **始终使用 Playwright 1.57.0** - 固定精确版本以保持一致性
|
||
|
||
## 安装
|
||
|
||
本仓库以 [Claude Code 插件](https://docs.claude.com/en/docs/claude-code/plugins) 的形式组织，包含一个技能。您可以将其安装为**插件**（推荐）或将其提取为**独立技能**。
|
||
|
||
### 了解目录结构
|
||
|
||
本仓库使用带嵌套结构的插件格式：
|
||
|
||
```
|
||
playwright-py-skill/ # 插件根目录
|
||
├── .claude-plugin/ # 插件元数据
|
||
└── skills/
|
||
└── playwright-py-skill/ # 实际技能目录
|
||
└── SKILL.md
|
||
```
|
||
|
||
Claude Code 期望技能直接位于 `.claude/skills/` 下的文件夹中，因此手动安装需要提取嵌套的技能文件夹。
|
||
|
||
### 前置条件
|
||
|
||
- Python 3.10 或更高版本（PEP 723 支持所需）
|
||
- Chromium 浏览器（Playwright 1.57.0 对应的正确版本）- 需单独安装
|
||
- `uv` 包管理器（用于运行带有 PEP 723 元数据的脚本）
|
||
|
||
**注意：** 此技能**不会**安装浏览器。Chromium 必须单独安装，且版本须与 Playwright 1.57.0 匹配。
|
||
|
||
---
|
||
|
||
### 方式一：插件安装（推荐）
|
||
|
||
通过 Claude Code 的插件系统安装，支持自动更新和团队分发：
|
||
|
||
```bash
|
||
# 将本仓库添加为市场源
|
||
/plugin marketplace add akaihola/playwright-py-skill
|
||
|
||
# 安装插件
|
||
/plugin install playwright-py-skill@playwright-py-skill
|
||
|
||
# 验证安装（自动安装 playwright==1.57.0）
|
||
cd ~/.claude/plugins/marketplaces/playwright-py-skill/skills/playwright-py-skill
|
||
uv run run.py --help
|
||
```
|
||
|
||
运行 `/help` 验证安装，确认技能已可用。
|
||
|
||
---
|
||
|
||
### 方式二：独立技能安装
|
||
|
||
若不使用插件系统，仅提取技能文件夹进行安装：
|
||
|
||
**全局安装（随处可用）：**
|
||
|
||
```bash
|
||
# 克隆到临时位置
|
||
git clone https://github.com/akaihola/playwright-py-skill.git /tmp/playwright-py-skill-temp
|
||
|
||
# 仅将技能文件夹复制到全局技能目录
|
||
mkdir -p ~/.claude/skills
|
||
cp -r /tmp/playwright-py-skill-temp/skills/playwright-py-skill ~/.claude/skills/
|
||
|
||
# 进入技能目录并运行配置（自动安装 playwright==1.57.0）
|
||
cd ~/.claude/skills/playwright-py-skill
|
||
uv run run.py --help
|
||
|
||
# 清理临时文件
|
||
rm -rf /tmp/playwright-py-skill-temp
|
||
```
|
||
|
||
**项目级安装：**
|
||
|
||
```bash
|
||
# 克隆到临时位置
|
||
git clone https://github.com/akaihola/playwright-py-skill.git /tmp/playwright-py-skill-temp
|
||
|
||
# 仅将技能文件夹复制到您的项目
|
||
mkdir -p .claude/skills
|
||
cp -r /tmp/playwright-py-skill-temp/skills/playwright-py-skill .claude/skills/
|
||
|
||
# 进入技能目录并运行配置（自动安装 playwright==1.57.0）
|
||
cd .claude/skills/playwright-py-skill
|
||
uv run run.py --help
|
||
|
||
# 清理临时文件
|
||
rm -rf /tmp/playwright-py-skill-temp
|
||
```
|
||
|
||
**为何采用此结构？** 插件格式需要 `skills/` 目录来组织插件内的多个技能。作为独立技能安装时，您只需要内层的 `skills/playwright-py-skill/` 文件夹内容。
|
||
|
||
---
|
||
|
||
### 方式三：下载发布包
|
||
|
||
1. 从 [GitHub Releases](https://github.com/akaihola/playwright-py-skill/releases) 下载并解压最新发布包
|
||
2. 仅将 `skills/playwright-py-skill/` 文件夹复制到：
|
||
- 全局：`~/.claude/skills/playwright-py-skill`
|
||
- 项目：`/path/to/your/project/.claude/skills/playwright-py-skill`
|
||
3. 进入技能目录并运行配置：
|
||
```bash
|
||
cd ~/.claude/skills/playwright-py-skill # 或您的项目路径
|
||
uv run run.py --help
|
||
```
|
||
|
||
---
|
||
|
||
### 验证安装
|
||
|
||
运行 `/help` 确认技能已加载，然后让 Claude 执行一个简单的浏览器任务，例如"测试 google.com 是否可以加载"。
|
||
|
||
## 快速开始
|
||
|
||
安装完成后，只需让 Claude 测试或自动化任意浏览器任务。Claude 将编写自定义 Playwright 代码、执行并返回带有截图和控制台输出的结果。
|
||
|
||
## 使用示例
|
||
|
||
### 测试任意页面
|
||
|
||
```
|
||
"测试首页"
|
||
"检查联系表单是否正常工作"
|
||
"验证注册流程"
|
||
```
|
||
|
||
### 视觉测试
|
||
|
||
```
|
||
"在移动端和桌面端截取仪表盘截图"
|
||
"跨不同视口测试响应式设计"
|
||
```
|
||
|
||
### 交互测试
|
||
|
||
```
|
||
"填写注册表单并提交"
|
||
"点击主导航逐项测试"
|
||
"测试搜索功能"
|
||
```
|
||
|
||
### 验证
|
||
|
||
```
|
||
"检查失效链接"
|
||
"验证所有图片正常加载"
|
||
"测试表单验证"
|
||
```
|
||
|
||
## 工作原理
|
||
|
||
1. 描述您要测试或自动化的内容
|
||
2. Claude 为任务编写自定义 Playwright 代码
|
||
3. 通用执行器（run.py）以正确的模块解析方式运行代码
|
||
4. 浏览器打开（默认可见）并执行自动化
|
||
5. 显示结果，包含控制台输出和截图
|
||
|
||
## 配置
|
||
|
||
默认设置：
|
||
|
||
- **无头模式：** `False`（除非明确要求，否则浏览器可见）
|
||
- **慢动作：** `100ms`（便于观察）
|
||
- **超时：** `30s`
|
||
- **截图：** 保存到 `/tmp/`
|
||
- **Playwright 版本：** 始终为 `1.57.0`（精确版本）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
playwright-py-skill/
|
||
├── .claude-plugin/
|
||
│ ├── plugin.json # 分发用插件元数据
|
||
│ └── marketplace.json # 市场配置
|
||
├── skills/
|
||
│ └── playwright-py-skill/ # 实际技能（Claude 会发现此目录）
|
||
│ ├── SKILL.md # Claude 读取的内容
|
||
│ ├── run.py # 通用执行器（正确的模块解析）
|
||
│ ├── lib/
|
||
│ │ └── helpers.py # 可选工具函数
|
||
│ └── API_REFERENCE.md # 完整 Playwright API 参考
|
||
├── README.md # 本文件 - 用户文档
|
||
├── CONTRIBUTING.md # 贡献指南
|
||
└── LICENSE # MIT 许可证
|
||
```
|
||
|
||
## 高级用法
|
||
|
||
Claude 将在需要时自动加载 `API_REFERENCE.md`，获取关于选择器、网络拦截、身份验证、视觉回归测试、移动端模拟、性能测试和调试的全面文档。
|
||
|
||
## 依赖项
|
||
|
||
- Python 3.10+（PEP 723 支持所需）
|
||
- `uv` 包管理器（用于运行带有 PEP 723 元数据的脚本）
|
||
- Playwright 1.57.0（通过 PEP 723 运行脚本时自动安装）
|
||
- Chromium 浏览器（需单独安装对应正确版本）
|
||
|
||
## 执行模式
|
||
|
||
所有脚本均包含 PEP 723 元数据块：
|
||
|
||
```python
|
||
# /// script
|
||
# requires-python = ">=3.10"
|
||
# dependencies = [
|
||
# "playwright==1.57.0",
|
||
# "aiohttp>=3.9.0",
|
||
# ]
|
||
# ///
|
||
|
||
# 您的 Playwright 代码...
|
||
```
|
||
|
||
运行 `uv run script.py` 时，会自动安装 PEP 723 块中指定的精确依赖项。
|
||
|
||
## 故障排除
|
||
|
||
**Playwright 未安装？**
|
||
进入技能目录并运行 `uv run run.py --help`（通过 PEP 723 自动安装）。
|
||
|
||
**模块未找到错误？**
|
||
确保通过 `run.py` 运行自动化脚本，它负责处理模块解析。
|
||
|
||
**浏览器未打开？**
|
||
确认已设置 `headless=False`。除非请求无头模式，否则技能默认显示浏览器。
|
||
|
||
**Chromium 版本错误？**
|
||
请单独安装与 Playwright 1.57.0 对应的正确 Chromium 版本。该技能不安装浏览器。
|
||
|
||
**需要安装所有浏览器？**
|
||
如需其他浏览器（firefox、webkit），请单独安装。该技能默认 Chromium 已安装。
|
||
|
||
## 什么是技能？
|
||
|
||
[Agent 技能](https://agentskills.io) 是包含指令、脚本和资源的文件夹，Agent 可以发现并使用它们来更准确、高效地完成任务。当您让 Claude 测试网页或自动化浏览器交互时，Claude 会发现此技能、加载必要的指令、执行自定义 Playwright 代码，并返回带有截图和控制台输出的结果。
|
||
|
||
此 Playwright 技能实现了[开放 Agent 技能规范](https://agentskills.io)，使其与各 Agent 平台兼容。
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献。Fork 本仓库，创建功能分支，提交您的更改，然后发起 Pull Request。详情参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||
|
||
## 了解更多
|
||
|
||
- [Agent 技能规范](https://agentskills.io) - Agent 技能的开放规范
|
||
- [Claude Code 技能文档](https://docs.claude.com/en/docs/claude-code/skills)
|
||
- [Claude Code 插件文档](https://docs.claude.com/en/docs/claude-code/plugins)
|
||
- [插件市场](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)
|
||
- [API_REFERENCE.md](skills/playwright-py-skill/API_REFERENCE.md) - 完整 Playwright 文档
|
||
- [GitHub Issues](https://github.com/akaihola/playwright-py-skill/issues)
|
||
|
||
## 许可证
|
||
|
||
MIT 许可证 - 详情参见 [LICENSE](LICENSE) 文件。 |