Playwright MCP より手軽な公式 CLI — コマンド3つでセットアップ

ども！最近Playwrightの話をいろんな文脈で聞くようになって、ちょっと混乱していた龍ちゃんです。

この記事を読むと:

Playwright の3パッケージ（テストランナー / MCP / CLI）の使い分けがわかる
コマンド3つで CLI が動くようになる
chromium vs chrome のハマりポイントを踏まずに済む

「Playwright MCP」「Playwright CLI」「Playwright テスト」…全部Playwrightなんですけど、それぞれ別パッケージで用途が違うんですよね。僕自身、チーム内で話していて「あれ、どのPlaywrightの話してる？」ってなったことがあったので、今回はまずそこを整理します。

んで、整理したうえで一番お手軽な「Playwright CLI」のセットアップを最小手順で紹介していきます。

1 Playwright の3つの顔 — まず整理しよう
2 最小セットアップ — これだけで動く
- 2.1 セットアップ手順（コマンド3つ）
- 2.2 エラーが出たら
  - 2.2.1 「Browser “chrome” is not installed」系のエラー
  - 2.2.2 「Failed to move to new namespace」エラー（DevContainer / Docker 環境）
3 基本操作 — snapshot 駆動でページを操る
4 まとめ
5 参考リンク

Playwright の3つの顔 — まず整理しよう

ちょっと内部で話していて混乱したので、ここで整理していきます。

テストランナーとしての Playwright

開発者が一番馴染みのあるやつです。E2Eテストを書いて自動実行する、テストフレームワークとしてのPlaywright。

npx playwright test

パッケージは@playwright/test。「Playwrightって何？」って聞かれたら、多くの人がこれを思い浮かべるんじゃないでしょうか。

MCP としての Playwright

AIエージェントにブラウザ操作をさせるためのプロトコルです。JSON-RPCでツール定義をやり取りする仕組みで、ChatGPTやClaude Desktopみたいなチャット型AI向け。

パッケージは@playwright/mcp。以前の記事でセットアップ方法を紹介しました。便利なんですけど、トークン消費が重いという課題もあるんですよね。

CLI としての Playwright（今回の主役）

シェルコマンドでブラウザを直接操作するやつです。Claude CodeやCursorみたいなAIコーディングエージェント向け。ファイルシステムにアクセスできる環境が前提になっています。

パッケージは@playwright/cli。MCPと比べて圧倒的に手軽で、コマンド1発でスクショが撮れます。

整理するとこう

種類	パッケージ	用途	誰向け
テストランナー	`@playwright/test`	E2Eテストの自動実行	テストエンジニア
MCP	`@playwright/mcp`	AIにブラウザ操作させる	チャット型AI
CLI	`@playwright/cli`	シェルからブラウザ操作	コーディングエージェント

全部「Playwright」だけど別パッケージ。テストランナーを入れてもCLIは動きません。ここ、地味にハマるポイントです。開発者目線でいえば、CLI一択ですね。（MCPとCLI論争がありましたが、再現性とかの観点でも開発系ならCLI一択だと思っています…）

最小セットアップ — これだけで動く

セットアップ手順（コマンド3つ）

Node.js v18以上が入っている環境なら、以下の3つで動きます。

# 1. ブラウザインストール（※ chromium ではなく chrome）
npx playwright install chrome

# 2. Skill インストール（Claude Code 用の SKILL.md が配置される）
npx @playwright/cli install --skills

# 3. 動作確認
npx @playwright/cli open https://example.com

成功すれば、こんな出力が返ってきます。

### Browser `default` opened with pid XXXXX.
- default:
  - browser-type: chrome
  - user-data-dir: <in-memory>
  - headed: false
---
### Page
- Page URL: https://example.com/
- Page Title: Example Domain
### Snapshot
- [Snapshot](.playwright-cli/page-YYYY-MM-DDTHH-MM-SS.yml)

ここまで出ればOK。 もしエラーが出たら、次のセクションを確認してください。

エラーが出たら

「Browser “chrome” is not installed」系のエラー

CLIのデフォルトブラウザはchrome（Google Chrome Stable）です。テストランナーでよく使うchromiumとは別物で、npx playwright install chromiumで入るブラウザはCLIからは参照されません。

# NG: テストランナー用のChromiumが入る。CLIでは使えない
npx playwright install chromium

# OK: Google Chrome Stableがインストールされる
npx playwright install chrome

テストランナーのPlaywrightに慣れてる人ほどchromiumでいけると思ってハマるので、ここだけ注意です。

「Failed to move to new namespace」エラー（DevContainer / Docker 環境）

コンテナ環境ではChromeのnamespace作成に権限が足りず、起動に失敗することがあります。プロジェクトルートに.playwright/cli.config.jsonを作成して--no-sandboxを設定すれば解決します。

{
  "browser": {
    "launchOptions": {
      "args": ["--no-sandbox", "--disable-setuid-sandbox"]
    }
  }
}

これはDevContainerやDocker環境に限った話なので、ローカル環境で動かしてる人は気にしなくて大丈夫です。

基本操作 — snapshot 駆動でページを操る

CLI はセッションベースで動きます。openでブラウザを開いて、操作して、closeで閉じる。この間、ブラウザの状態は保持されます。

npx @playwright/cli open https://example.com   # セッション開始
# ... ここで色々操作 ...
npx @playwright/cli close                       # セッション終了

では実際にやってみます。

ページ取得 — snapshot でページ構造を見る

openした状態でsnapshotを実行すると、ページの構造がYAML形式で返ってきます。

npx @playwright/cli snapshot

- generic [ref=e2]:
  - heading "Example Domain" [level=1] [ref=e3]
  - paragraph [ref=e4]: This domain is for use in documentation examples...
  - paragraph [ref=e5]:
    - link "Learn more" [ref=e6] [cursor=pointer]:
      - /url: https://iana.org/domains/example

各要素にref=e2、ref=e6みたいな参照IDが振られていますよね。これがCLIの核心機能です。

ref で操作する

snapshotで取得した参照IDを使って、要素を直接操作できます。

# "Learn more" リンク（ref=e6）をクリック
npx @playwright/cli click e6

### Ran Playwright code
await page.getByRole('link', { name: 'Learn more' }).click();

### Page
- Page URL: https://www.iana.org/help/example-domains
- Page Title: Example Domains

コマンド1発でページが遷移しました。snapshot → ref で操作、この繰り返しが CLI の基本です。

スクリーンショットを撮る

スクリーンショットも1コマンドで撮れます。

npx @playwright/cli screenshot --filename=screenshot.png

ひと通り操作が終わったらcloseでセッション終了です。snapshot で構造を見て、ref で操作して、screenshot で結果を確認。この3ステップが CLI の基本ワークフローです。

Claude Code の Skill として使う

セットアップの手順2でnpx @playwright/cli install --skillsを実行していれば、もう準備完了です。.claude/skills/playwright-cli/にSKILL.mdとreferencesディレクトリ（7ファイル）が自動配置されています。

これで「スクショ撮って」「Webページ開いて」みたいな指示をClaude Codeに出すだけで、CLIを呼んでくれるようになります。

前回の記事で「CLI + Skills」パターンを提唱しましたが、あのとき自作していたものが公式サポートになった形ですね。Microsoft が Skill を用意してくれるので、メンテナンスも楽になりました。

まとめ

今回は、Playwrightの3つの顔を整理したうえで、CLI の最小セットアップ手順を紹介しました。

Playwrightは「テストランナー」「MCP」「CLI」の3つがあって全部別パッケージ。AIコーディングエージェントで使うなら CLI が一番お手軽です。セットアップは playwright install chrome → install --skills → open のコマンド3つだけ。

ハマりポイントは chromium じゃなくて chrome が必要なところ。テストランナーに慣れてる人ほど引っかかるので、ここだけ覚えておけば大丈夫です。あと install --skills で Claude Code 用の SKILL.md が公式から自動配置されるのも地味にありがたい。

MCPとCLIのトークン消費比較や、ユースケース別の使い分けについては別記事で詳しく書く予定です。コメント欄で気軽に話しかけてください。