Claude Code で Playwright CLI を使いこなす：導入ハードルと解消法まとめ

はじめに

「Claude Code にブラウザ操作させたい」と思ったとき、選択肢は主に2つあります。Playwright MCP と Playwright CLI です。

MCP はセットアップが分かりやすい反面、ページの構造データ（アクセシビリティツリー）を丸ごと AI の作業メモリに載せるため、数ページ操作するだけで AI が扱えるテキスト量（トークン）を圧迫します。一方の Playwright CLI（@playwright/cli）はディスクベースで出力するためトークン消費が約4分の1で済みますが、導入時に「あれ、動かない」「何が違うの？」とつまずくポイントがいくつかあります。

この記事では、Playwright CLI を Claude Code で実際に動かして見つけた導入ハードルとその解消法を整理します。セットアップからスキル同期の落とし穴まで、ハマりやすいポイントを先回りして潰していきましょう。

環境・前提条件

• Node.js 18 以上
• npm（グローバルインストールに使用）
• Claude Code（Bash ツール経由で CLI を実行）
• 検証バージョン：@playwright/cli v0.1.1 → v0.1.4 / Playwright 本体 1.59.1

ハードル1：3つの「Playwright」を混同する

最初のハードルはツールの混同です。「Playwright」と名の付くものが3種類あり、検索してもどれの情報か判別しにくい状況です。

ツール	パッケージ名	主な用途	主なユーザー
Playwright Test CLI	@playwright/test	E2Eテストの実行・レポート	開発者・QAエンジニア
Playwright MCP	@playwright/mcp	ブラウザ操作（MCP経由）	AI エージェント全般
Playwright CLI	@playwright/cli	ブラウザ操作（CLI経由）	コーディングエージェント

Playwright CLI は 2026年初頭に Microsoft がリリースしたAIコーディングエージェント専用のブラウザ操作ツールです。従来の npx playwright test とは設計思想が根本的に異なります。

テスト用 CLI はテストファイルを実行して結果レポートを返しますが、Playwright CLI は click e6、fill e16 "text" のように個別コマンドで逐次操作します。出力は YAML ベースのアクセシビリティツリーで、LLM が構造を理解しやすい形式です。

解消法: CLAUDE.md に「Playwright CLI = @playwright/cli、テスト = npx playwright test、MCP = @playwright/mcp」と判断基準を明記しておくと、Claude Code の混乱を防げます。

ハードル2：install --skills を知らない

何が起きるか

Playwright CLI のセットアップは npm install -g @playwright/cli@latest でインストールした後、ワークスペースで playwright-cli install を実行します。これで .playwright/ ディレクトリが作成され、ブラウザが検出されて使えるようになります。

ここで多くの人が見落とすのが --skills フラグです。

# ワークスペース初期化のみ（最低限動く）
playwright-cli install

# スキルも一緒にインストール（推奨）
playwright-cli install --skills

--skills を付けると .claude/skills/playwright-cli/ 以下に SKILL.md と9本のリファレンスドキュメントが生成されます。Claude Code はこれを読むことで、50以上あるコマンドの使い方や落とし穴を理解できます。

スキルなしだとどうなるか

公式 README には「Skills-less operation」でも動くと書かれています。確かに --help を読めば基本操作はできます。しかし実際に比較すると、スキルの有無で Claude Code の精度に明らかな差が出ました。

項目	スキルなし	スキルあり
allowed-tools 設定	なし（手動設定が必要）	自動設定済み
コマンド用法の参照先	--help のみ	SKILL.md + 9本のリファレンス
run-code 構文の理解	間違いやすい	正しい構文が明記されている
落とし穴の事前知識	なし	ドキュメントに記載あり

解消法: 初回セットアップ時に必ず playwright-cli install --skills を実行してください。

ハードル3：バージョンアップ後にスキルを再同期し忘れる

何が起きるか

@playwright/cli を v0.1.1 → v0.1.4 にアップデートした後、install --skills を再実行せずに使い続けていたところ、スキルが v0.1.1 時点のまま古くなっていました。後から install --skills を再実行したら、内容が大きく変わりました。

項目	再実行前（v0.1.1 時点）	再実行後（v0.1.4 時点）
SKILL.md 行数	278	328（+50行）
リファレンスファイル数	7	9（+2本）
MD5 ハッシュ	bd87af47	d7f743f2

追加されていた内容の例です。

• allowed-tools の拡張（Bash(playwright-cli:*) → Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)）
• fill --submit オプションのドキュメント
• CSS セレクタや Playwright ロケータ（getByRole 等）による要素指定のドキュメント
• snapshot --depth、--filename、要素指定の統合ドキュメント
• 新規リファレンス：playwright-tests.md（テストデバッグ統合）、element-attributes.md（属性検査）

なぜ見落としやすいか

npm install -g @playwright/cli@latest でパッケージ自体は更新されますが、ワークスペース内のスキルファイルは自動では更新されません。install --skills は手動で再実行する必要があります。特にアルファ版の今は、v0.1.1 → v0.1.4 のようなマイナーバージョンでもスキル内容が大幅に変わるため、再同期を忘れると Claude Code が古い情報で動くことになります。

解消法: @playwright/cli をアップデートしたら、セットで playwright-cli install --skills を実行してください。

実際に動かしてみる：3つのシナリオ

ハードルを越えたら、何ができるのか。3つの実用シナリオで示します。

シナリオ1：ログインフローのスモークテスト

テストサイト（the-internet.herokuapp.com）でログイン操作を自動化する例です。

playwright-cli open https://the-internet.herokuapp.com/login
playwright-cli snapshot --depth=5           # ref 番号を取得
playwright-cli fill e16 "tomsmith"          # ユーザー名入力
playwright-cli fill e20 "SuperSecretPassword!" --submit  # パスワード + Enter
playwright-cli snapshot --depth=3           # 結果確認
# → "You logged into a secure area!" / URL: /secure

5つのコマンドでログインの成功確認まで完了します。Claude Code に「このサイトのログインをテストして」と指示するだけで、スキルがあればこの流れを自律的に実行してくれます。

シナリオ2：壊れた画像のデバッグ

playwright-cli goto https://the-internet.herokuapp.com/broken_images
playwright-cli console error    # → asdf.jpg, hjkl.jpg の 404 エラーを即特定
playwright-cli network          # → 404 レスポンスの詳細を確認

console error と network の2コマンドで、壊れた画像のファイル名と HTTP ステータスを特定できます。DevTools を開いて手動で確認するより速い場面が多いです。

シナリオ3：API モックによるフロントエンド開発

バックエンドが未完成でも、フロントエンドの動作確認ができます。

# JSON レスポンスのモック
playwright-cli route "**/api/users" \
  --body='[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]' \
  --content-type=application/json

# 設定内容の確認
playwright-cli route-list

# モックが効いた状態でページを開く
playwright-cli goto https://localhost:3000
playwright-cli snapshot --depth=5  # モックデータが表示されることを確認

route コマンドは --body、--status、--content-type、--header でレスポンスを自由にカスタマイズできます。不要になったら playwright-cli unroute で一括解除も可能です。

CLI と MCP、どちらを選ぶか

公式 README では以下の棲み分けが示されています。

項目	CLI (@playwright/cli)	MCP (@playwright/mcp)
向いている用途	コーディングエージェント（大量のコード＋限られたコンテキスト）	永続的な状態管理、豊富なイントロスペクション
トークン効率	高い（ディスクベース出力）	低い（ツールスキーマ＋アクセシビリティツリーをコンテキストに載せる）
セットアップ	npm install -g のみ	サーバー起動＋設定が必要

Claude Code のようにファイルシステムへのアクセスがあるコーディングエージェントでは、CLI の方がトークン効率・セットアップの簡便さの両面で有利です。

一方、Claude Desktop やカスタムチャット UI のようにサンドボックス環境で動くエージェントでは MCP が適しています。

まとめ

Playwright CLI を Claude Code で活用するためのポイントを整理します。

• 3つの Playwright を混同しない：CLI（@playwright/cli）は AI コーディングエージェント専用。テスト実行用（@playwright/test）、MCP（@playwright/mcp）とは別物です
• install --skills を必ず実行する：スキルの有無で Claude Code の操作精度が大きく変わります。初回セットアップ時に忘れずに
• バージョンアップ後はスキルを再同期する：npm install -g でパッケージを更新しても、ワークスペースのスキルは自動更新されません。アップデート後に install --skills を忘れずに

まだ v0.1.x のアルファ版ですが、開発は非常にアクティブで、マイナーバージョンでもスキル内容が大幅に変わります。進化の速いツールだからこそ、バージョンアップ後の install --skills による再同期が導入のカギになります。

同じツールを導入しようとしている方の参考になれば幸いです。

参考リンク

• @playwright/cli — GitHub / npm
• @playwright/mcp — npm
• Playwright 公式サイト