mc-skills/catalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
catalog/repos/akaihola--playwright-py-skill.md

277 lines
9.2 KiB
Markdown
Raw Normal View History

catalog: 更新 2026-04-07 11:44
2026-04-07 11:44:56 +08:00
# 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) 文件。
Reference in New Issue Copy Permalink