Timmy
55e05c323c
安裝 playwright@claude-plugins-official，新增獨立筆記並於 README、 SUMMARY、QUICKSTART 建立索引，與既有 Python 版 Playwright 筆記區分。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
145 lines
5.1 KiB
Markdown
145 lines
5.1 KiB
Markdown
# Playwright Plugin (Claude Code) 安裝與使用筆記
|
||
|
||
> 本檔記錄的是 **Claude Code 外掛版** 的 Playwright，透過 MCP server 讓 Claude 直接操作瀏覽器。
|
||
> Python 函式庫版本請參考 [playwright-notes.md](./playwright-notes.md)。
|
||
|
||
## 基本資訊
|
||
|
||
- **專案頁**: https://claude.com/plugins/playwright
|
||
- **Marketplace**: `claude-plugins-official`（Anthropic 官方）
|
||
- **作者**: Microsoft
|
||
- **類型**: Claude Code 外掛（包裝 `@playwright/mcp` MCP server）
|
||
- **核心套件**: [`@playwright/mcp`](https://www.npmjs.com/package/@playwright/mcp)（`npx @playwright/mcp@latest`）
|
||
- **安裝規模**: 150,000+（官方 marketplace 顯示）
|
||
- **安裝日期**: 2026-04-19
|
||
|
||
## 是什麼
|
||
|
||
把 Microsoft 的 Playwright MCP server 打包成一個 Claude Code plugin。安裝後 Claude 就能直接：
|
||
|
||
- 開網頁、導覽 URL
|
||
- 讀取頁面 accessibility tree 並點擊、填表、上傳檔案
|
||
- 截圖、存 PDF
|
||
- 管理分頁、攔截 network request、讀 console 訊息
|
||
- 執行自訂 Playwright 腳本
|
||
- 做 E2E 測試斷言
|
||
|
||
**關鍵設計**：優先使用 accessibility data 而非螢幕截圖，互動是 deterministic 的，不需要 vision model 推論。
|
||
|
||
## 安裝
|
||
|
||
### 方式 1：CLI（推薦，可自動化）
|
||
|
||
```bash
|
||
claude plugin install playwright@claude-plugins-official
|
||
```
|
||
|
||
### 方式 2：Claude Code 對話內
|
||
|
||
```text
|
||
/plugin install playwright@claude-plugins-official
|
||
```
|
||
|
||
官方 marketplace `claude-plugins-official` 預設已加入，不需額外設定。如果沒有：
|
||
|
||
```bash
|
||
claude plugin marketplace add anthropics/claude-plugins-official
|
||
```
|
||
|
||
### 安裝後驗證
|
||
|
||
```bash
|
||
claude plugin list # 應列出 playwright@claude-plugins-official
|
||
ls ~/.claude/plugins/cache/claude-plugins-official/playwright/
|
||
```
|
||
|
||
預期路徑：`~/.claude/plugins/cache/claude-plugins-official/playwright/unknown/`（版本標為 `unknown` 是因為 plugin 只是一層 `.mcp.json` 包裝，實際版本鎖在 `@playwright/mcp@latest`）。
|
||
|
||
## 架構
|
||
|
||
這個 plugin 其實只是一個很薄的殼：
|
||
|
||
```
|
||
playwright/
|
||
├── .claude-plugin/plugin.json # plugin metadata
|
||
└── .mcp.json # 啟動 MCP server 的指令
|
||
```
|
||
|
||
`.mcp.json` 內容：
|
||
|
||
```json
|
||
{
|
||
"playwright": {
|
||
"command": "npx",
|
||
"args": ["@playwright/mcp@latest"]
|
||
}
|
||
}
|
||
```
|
||
|
||
所以真正的能力都在 `@playwright/mcp` 這個 npm 套件，第一次啟動時 `npx` 會自動下載。
|
||
|
||
### 系統需求
|
||
|
||
- Node.js（`npx` 可用即可）
|
||
- 第一次執行時會讓 Playwright 下載瀏覽器 binary；若已用過 Python 版 Playwright，可能需要獨立再下載一份給 `@playwright/mcp`
|
||
|
||
## 使用方式
|
||
|
||
安裝並重啟 Claude Code 後，Claude 對話裡會自動出現 `playwright` 系列 MCP 工具（例如 `browser_navigate`、`browser_click`、`browser_snapshot`、`browser_take_screenshot` 等）。直接用自然語言請 Claude 做事即可：
|
||
|
||
> 「打開 example.com，擷取主要標題並存一張截圖」
|
||
|
||
Claude 會自行呼叫對應的 MCP 工具，不需要手動寫 Playwright 程式碼。
|
||
|
||
### 常見指令範例（對 Claude 講）
|
||
|
||
- 「打開 https://example.com，截圖存 `out.png`」
|
||
- 「在登入頁輸入 `admin` / `secret`，按登入，回報導向哪裡」
|
||
- 「把目前頁面另存成 PDF」
|
||
- 「幫我攔截對 `/api/data` 的請求並印出 payload」
|
||
- 「檢查 `.price` 元素的文字內容，驗證是否為 `$99`」
|
||
|
||
## 與 Python Playwright 的差異
|
||
|
||
| 面向 | Python Playwright | Claude Code Plugin |
|
||
|------|-------------------|---------------------|
|
||
| 呼叫方式 | 你寫 code | 對 Claude 講話 |
|
||
| 互動來源 | Selector / Locator | Accessibility tree |
|
||
| 適用場景 | 長期腳本、CI 測試、爬蟲 | 探索式操作、一次性自動化、Agent workflow |
|
||
| 版本管理 | `pip install playwright` | `npx @playwright/mcp@latest`（自動拉最新） |
|
||
| 瀏覽器 | 自己跑 `playwright install` | MCP 首次啟動時安裝 |
|
||
|
||
兩者可以並存：Python 版適合放進專案 repo 作正式測試；Plugin 版適合讓 Claude 臨場幫你跑 demo、除錯、擷取內容。
|
||
|
||
## 常用檢查與移除
|
||
|
||
```bash
|
||
# 檢查安裝狀態
|
||
claude plugin list
|
||
|
||
# 檢視 plugin metadata
|
||
cat ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/playwright/.claude-plugin/plugin.json
|
||
cat ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/playwright/.mcp.json
|
||
|
||
# 手動測試 MCP server（會占用 terminal，Ctrl-C 結束）
|
||
npx @playwright/mcp@latest --help
|
||
```
|
||
|
||
移除：
|
||
|
||
```bash
|
||
claude plugin uninstall playwright@claude-plugins-official
|
||
```
|
||
|
||
或在 Claude Code 對話中：
|
||
|
||
```text
|
||
/plugin uninstall playwright@claude-plugins-official
|
||
```
|
||
|
||
## 備註
|
||
|
||
- Plugin 本體沒有綁版本號（顯示為 `unknown`），能力跟著 `@playwright/mcp@latest` 走，等同「滾動更新」。要鎖版本需自己 fork 並改 `.mcp.json` 的 `@playwright/mcp@x.y.z`。
|
||
- MCP server 是 per-session 啟動的，開啟新的 Claude Code session 才會生效；安裝後記得重啟。
|
||
- 若對話中沒看到 `browser_*` 工具，檢查 `claude plugin list` 是否顯示 `enabled`，並確認 `node`/`npx` 在 PATH 裡。
|