# 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 裡。