koide
8c109a1d9a
All checks were successful
Deploy Docusaurus Site / deploy (push) Successful in 28s
322 lines
9.5 KiB
Markdown
322 lines
9.5 KiB
Markdown
---
|
||
sidebar_position: 5
|
||
title: ローカルClaude Code + Playwright CLIでブラウザ自動化エージェントを作る
|
||
description: Claude Code + Playwright CLIで安定したブラウザ自動化環境を構築する方法
|
||
hide_table_of_contents: false
|
||
displayed_sidebar: null
|
||
image: ./banner.png
|
||
---
|
||
|
||
# ローカルClaude Code + Playwright CLIで「自分だけのブラウザ自動化エージェント」を作る
|
||
|
||
## はじめに
|
||
|
||
[前回の記事](/tech/dgx-spark-claude-code-local)で、Claude Codeをローカルで動かす方法を紹介しました。
|
||
|
||
今回はその続き。**Playwright CLI**を組み合わせて、ブラウザを自動操作できるエージェントを作ります。
|
||
|
||
### 何ができるようになる？
|
||
|
||
- ✅ 「このサイトの情報を集めて」→ 自動でスクレイピング
|
||
- ✅ 「ログインしてデータをダウンロード」→ 認証も自動
|
||
- ✅ 「このフォームに入力して送信」→ ブラウザ操作を自動化
|
||
- ✅ 「E2Eテストを書いて実行」→ テストコード生成＆実行
|
||
|
||
しかも**完全ローカル**。データはどこにも送られません。
|
||
|
||
## なぜMCPではなくCLI？
|
||
|
||
ブラウザ自動化には2つの方式があります：
|
||
|
||
| 方式 | 特徴 | 成功率 |
|
||
|------|------|--------|
|
||
| Playwright MCP | リアルタイム状態管理 | △ 不安定なことがある |
|
||
| **Playwright CLI + SKILLS** | トークン効率が良い | **◎ 安定して動く** |
|
||
|
||
:::tip CLI方式をおすすめする理由
|
||
1. **トークン効率が良い** - 巨大なツールスキーマやアクセシビリティツリーをコンテキストに読み込まない
|
||
2. **安定している** - シンプルなコマンド実行なので失敗しにくい
|
||
3. **デバッグしやすい** - 同じコマンドを手動でも実行できる
|
||
:::
|
||
|
||
## 前提条件
|
||
|
||
- [Claude Codeのローカル環境](/tech/dgx-spark-claude-code-local)が動作済み
|
||
- Node.js 18以上
|
||
|
||
## セットアップ
|
||
|
||
### Step 1: Playwright CLIをインストール
|
||
|
||
```bash
|
||
npm install -g @playwright/cli@latest
|
||
```
|
||
|
||
確認：
|
||
|
||
```bash
|
||
playwright-cli --help
|
||
```
|
||
|
||
### Step 2: SKILLSをインストール
|
||
|
||
```bash
|
||
playwright-cli install --skills
|
||
```
|
||
|
||
これでClaude Codeが自動的にPlaywright CLIのスキルを認識します。
|
||
|
||
### Step 3: 動作確認
|
||
|
||
```bash
|
||
claude-local # ローカルモデルで起動
|
||
```
|
||
|
||
Claude Codeで：
|
||
|
||
|
||
## スキルを使わせるコツ
|
||
|
||
:::warning Claude Codeがplaywright-cliを使ってくれない？
|
||
デフォルトではClaude Codeは`playwright-cli`の存在を知りません。以下の方法で認識させましょう。
|
||
:::
|
||
|
||
### 方法1: 明示的に指示する
|
||
|
||
プロンプトで**明示的に**`playwright-cli`を指定します：
|
||
|
||
```text
|
||
playwright-cli を使って https://example.com のスクリーンショットを撮って
|
||
```
|
||
|
||
最初に「`playwright-cli --help` を確認して」と言うのも効果的：
|
||
|
||
```text
|
||
playwright-cli --help を確認して、そのコマンドを使ってブラウザ操作をして
|
||
```
|
||
|
||
### 方法2: CLAUDE.mdにスキルを記述
|
||
|
||
プロジェクトのルートに `CLAUDE.md` を作成し、スキルを記述します：
|
||
|
||
```markdown title="CLAUDE.md"
|
||
# プロジェクト設定
|
||
|
||
## ブラウザ操作
|
||
|
||
このプロジェクトではブラウザ操作に **playwright-cli** を使用してください。
|
||
Web検索やFetchではなく、必ず playwright-cli コマンドを使ってください。
|
||
|
||
利用可能なコマンド:
|
||
- playwright-cli open <url> - ブラウザを開く
|
||
- playwright-cli snapshot - ページ構造を取得
|
||
- playwright-cli click <ref> - 要素をクリック
|
||
- playwright-cli type <text> - テキスト入力
|
||
- playwright-cli screenshot - スクリーンショット
|
||
```
|
||
|
||
### 方法3: セッション開始時に宣言
|
||
|
||
Claude Codeを起動したら、最初にこう言います：
|
||
|
||
```text
|
||
このセッションではブラウザ操作に playwright-cli を使います。
|
||
playwright-cli --help で使い方を確認してください。
|
||
```
|
||
|
||
これでClaude Codeが`playwright-cli`の存在を認識し、以降のブラウザ操作で使ってくれます。
|
||
|
||
```text
|
||
> playwright-cli --help を確認して、https://example.com のスクリーンショットを撮って
|
||
```
|
||
|
||
## 公式SKILLSリファレンス
|
||
|
||
Playwright CLIには公式のSKILLSファイルがあります。以下は主要なコマンド：
|
||
|
||
### Quick Start
|
||
|
||
```bash
|
||
playwright-cli open # ブラウザを開く
|
||
playwright-cli goto https://playwright.dev # URLに移動
|
||
playwright-cli click e15 # 要素refでクリック
|
||
playwright-cli type "page.click" # テキスト入力
|
||
playwright-cli press Enter # Enterキー
|
||
playwright-cli screenshot # スクリーンショット
|
||
playwright-cli close # ブラウザを閉じる
|
||
```
|
||
|
||
### Core Commands
|
||
|
||
```bash
|
||
playwright-cli open https://example.com # ページを開く
|
||
playwright-cli goto https://example.com # URLに移動
|
||
playwright-cli type "検索キーワード" # テキスト入力
|
||
playwright-cli click e3 # 要素をクリック（refで指定）
|
||
playwright-cli fill e5 "user@example.com" # 入力欄に値を設定
|
||
playwright-cli select e9 "option-value" # セレクトボックス選択
|
||
playwright-cli check e12 # チェックボックスON
|
||
playwright-cli uncheck e12 # チェックボックスOFF
|
||
playwright-cli upload ./document.pdf # ファイルアップロード
|
||
playwright-cli snapshot # ページ構造を取得
|
||
playwright-cli screenshot # スクリーンショット
|
||
```
|
||
|
||
### Navigation
|
||
|
||
```bash
|
||
playwright-cli go-back # 戻る
|
||
playwright-cli go-forward # 進む
|
||
playwright-cli reload # リロード
|
||
```
|
||
|
||
### Keyboard
|
||
|
||
```bash
|
||
playwright-cli press Enter
|
||
playwright-cli press ArrowDown
|
||
playwright-cli keydown Shift
|
||
playwright-cli keyup Shift
|
||
```
|
||
|
||
### Tabs
|
||
|
||
```bash
|
||
playwright-cli tab-list # タブ一覧
|
||
playwright-cli tab-new # 新しいタブ
|
||
playwright-cli tab-new https://example.com # URLを指定して新しいタブ
|
||
playwright-cli tab-select 0 # タブを選択
|
||
playwright-cli tab-close # タブを閉じる
|
||
```
|
||
|
||
### Storage（Cookie/LocalStorage）
|
||
|
||
```bash
|
||
# 状態の保存・読み込み
|
||
playwright-cli state-save auth.json
|
||
playwright-cli state-load auth.json
|
||
|
||
# Cookie操作
|
||
playwright-cli cookie-list
|
||
playwright-cli cookie-get session_id
|
||
playwright-cli cookie-set session_id abc123
|
||
playwright-cli cookie-clear
|
||
|
||
# LocalStorage操作
|
||
playwright-cli localstorage-list
|
||
playwright-cli localstorage-get theme
|
||
playwright-cli localstorage-set theme dark
|
||
```
|
||
|
||
### Sessions
|
||
|
||
```bash
|
||
playwright-cli list # セッション一覧
|
||
playwright-cli -s=myproject open https://example.com # 特定セッションで操作
|
||
playwright-cli open --persistent # 永続セッション（Cookie保存）
|
||
playwright-cli close-all # 全セッション終了
|
||
playwright-cli kill-all # 強制終了
|
||
```
|
||
|
||
### DevTools
|
||
|
||
```bash
|
||
playwright-cli console # コンソールログ
|
||
playwright-cli network # ネットワークリクエスト
|
||
playwright-cli tracing-start # トレース開始
|
||
playwright-cli tracing-stop # トレース終了
|
||
playwright-cli video-start # 動画記録開始
|
||
playwright-cli video-stop video.webm # 動画記録終了
|
||
```
|
||
|
||
## Snapshots
|
||
|
||
各コマンド実行後、Playwright CLIはページの**スナップショット**を返します：
|
||
|
||
```text
|
||
> playwright-cli goto https://example.com
|
||
Page URL: https://example.com/
|
||
Page Title: Example Domain
|
||
Snapshot: .playwright-cli/page-2026-02-19T13-30-00.yml
|
||
```
|
||
|
||
スナップショットには要素の**ref（e1, e2, e15など）** が含まれており、これを使ってクリックや入力を行います。
|
||
|
||
## 実践例
|
||
|
||
### 例1: フォーム入力
|
||
|
||
```bash
|
||
playwright-cli open https://example.com/form
|
||
playwright-cli snapshot
|
||
playwright-cli fill e1 "user@example.com"
|
||
playwright-cli fill e2 "password123"
|
||
playwright-cli click e3
|
||
playwright-cli snapshot
|
||
playwright-cli close
|
||
```
|
||
|
||
### 例2: 複数タブ操作
|
||
|
||
```bash
|
||
playwright-cli open https://example.com
|
||
playwright-cli tab-new https://example.com/other
|
||
playwright-cli tab-list
|
||
playwright-cli tab-select 0
|
||
playwright-cli snapshot
|
||
playwright-cli close
|
||
```
|
||
|
||
### 例3: 認証状態の保存
|
||
|
||
```bash
|
||
# ログイン後に状態を保存
|
||
playwright-cli state-save auth.json
|
||
|
||
# 次回は状態を読み込んでスキップ
|
||
playwright-cli open --persistent
|
||
playwright-cli state-load auth.json
|
||
```
|
||
|
||
## トラブルシューティング
|
||
|
||
### ブラウザが起動しない
|
||
|
||
```bash
|
||
npx playwright install chromium
|
||
```
|
||
|
||
### セッションが残っている
|
||
|
||
```bash
|
||
playwright-cli kill-all
|
||
```
|
||
|
||
### 要素が見つからない
|
||
|
||
```bash
|
||
playwright-cli snapshot
|
||
```
|
||
|
||
スナップショットで要素のrefを確認。
|
||
|
||
## まとめ
|
||
|
||
**ポイント**：
|
||
|
||
1. **CLI方式を使う** - MCPより安定している
|
||
2. **公式SKILLSを使う** - `playwright-cli install --skills`
|
||
3. **snapshotでref確認** - 要素はe1, e2などのrefで指定
|
||
4. **セッションを活用** - ログイン状態を保持
|
||
|
||
## 参考リンク
|
||
|
||
- [Playwright CLI（Microsoft）](https://github.com/microsoft/playwright-cli)
|
||
- [公式SKILLS](https://raw.githubusercontent.com/microsoft/playwright-cli/main/skills/playwright-cli/SKILL.md)
|
||
- [Playwright公式](https://playwright.dev/)
|
||
- [前回の記事: Claude Codeローカル化](/tech/dgx-spark-claude-code-local)
|
||
|
||
---
|
||
|
||
*この記事は2026年2月時点の情報です。*
|