# 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) 文件。