ヘッドレスChromeのスクリーンショット|CDPで幅を指定

ヘッドレスChromeのスクリーンショット|CDPで幅を指定

AI エージェントにページの見た目を確かめさせる工程が、スクリーンショットのところで止まるようになりました。

原因は、エージェントが操作する Chrome のタブが、私の使っている Chrome ウィンドウの裏に開いていたことです。

そこで、画面に出ないヘッドレス Chrome を別に起動して撮る経路を足し、保留にしていた PR の目視をそれで済ませました。

途中では、--window-size で幅を 380px にしてもスマホ幅のレイアウトにならず、一度つまずいています。

裏のタブで何が止まるのかと、狭い幅を正しく撮る指定が分かれば、同じ構成で目視が止まる問題は避けられます。

前提(最小限)

私は Claude Code の定期ルーティンで、Chrome 拡張の Claude in Chrome を通してローカルでビルドしたページを撮り、見た目を確かめてから PR をマージしています。

拡張が開くタブは別のウィンドウではなく、私が普段使っている Chrome ウィンドウの中に並ぶタブの 1 つです。

私が別のタブを見ている間、エージェントのタブは裏に回ります。

代わりの経路で使ったのは、Chrome を外から操作・検査するためのプロトコルである CDP(Chrome DevTools Protocol)でした。

裏のタブでは描画が止まり、スクリーンショットが落ちる

2026-09-26 に、エージェントのタブが裏にあるときと表に出したときで、ページの状態を測りました。

測ったもの裏のタブ表に出したタブ
document.visibilityStatehiddenvisible
requestAnimationFrame の 1 秒あたりの回数1 回241 回
window.outerWidth と outerHeight0 と 0ウィンドウの実寸

裏のタブでは、描画の直前に呼ばれる requestAnimationFrame が 1 秒に 1 回しか回っていませんでした。

MDN の Page Visibility API の解説では、ページが hidden になる場面として、タブを切り替えたときとウィンドウを最小化したときが挙げられています。

NO IMAGE

同じページには、多くのブラウザが裏のタブへの requestAnimationFrame の呼び出しを止めるとも書かれています。

この状態でスクリーンショットを撮らせると、CDP のタイムアウト(30 秒)で落ちました。

1 回おきに通ることもありましたが、安定はしませんでした。

一方で、DOM の読み取りや getComputedStyle の数値は、裏のタブでも普通に取れます。

数値は読めても、見た目だけが確かめられないのが裏のタブの状態です。

タブを表に出せば撮れますが、それは私が使っている画面をエージェントが奪うことになります。

なお、裏のタブで setTimeout が間引かれて自動操作が遅くなる話は、別の記事に書きました。

setTimeoutのスロットリングとは?止まる理由と回避策

画面に出ないヘッドレス Chrome で撮る

このため、私の画面を共有する経路とは別に、画面に出ない経路を持つことにしました。

Chrome のヘッドレスモードの公式ドキュメントによると、Chrome 112 からのヘッドレスモードは、ウィンドウを作るものの表示はしません。

ほかの機能は、いまあるものもこれから加わるものも、制限なく使えると書かれています。

旧来のヘッドレスは、Chrome 132 から chrome-headless-shell という別のバイナリに分かれました。

まずはコマンドラインで、フラグを付けて 1 枚撮ってみました。

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --headless=new `
  --screenshot=shot.png --window-size=1280,1400 https://example.com/

2026-10-07 に自分の静的サイトのトップをこの形で撮ると、1.1 秒で PNG ができました。

公式ドキュメントの例は --headless だけですが、私は --headless=new と書いて動かしています。

ヘッドレスのページは、画面に出ていなくても hidden になりません。

2026-10-18 に Windows 11 の Google Chrome 155 で測ると、visibilityState は visible で、requestAnimationFrame は 1 秒に 63 回回っていました。

画面に出ない経路は、私がどのタブを見ているかに左右されません。

--window-size の 380px はスマホ幅にならない

同じコマンドで --window-size=380,1400 にすると、画像は 380px 幅なのに、レイアウトは 500px 前後で組まれていました。

ヒーローの文やヘッダーのボタンが、右側で切れていました。

画像の幅が 380px でも、ページが 380px で組まれたとは限りません。

2026-10-18 にこのブログのトップで試し直しても、カードが 2 列のまま組まれ、右の列が途中で切れた画像になりました。

CDP でつないで同じ指定のページを測ると、innerWidth は 500、outerWidth は 516 でした。

--window-size=1280,1400 のときは outerWidth が 1280、innerWidth が 1264 だったので、この指定はウィンドウの外枠の大きさとして効いています。

380 を渡しても、ウィンドウは 516 までしか縮まなかったことになります。

公式のコマンドラインの説明には --screenshot は --window-size と組み合わせると便利だとありますが、幅の下限には触れていません。

縮まない理由は、まだ確かめられていません。

狭い幅とダークテーマは CDP の端末エミュレーションで指定する

幅は起動時のフラグに任せず、CDP の Emulation ドメインで端末ごとエミュレートすることにしました。

最初の一歩は、--remote-debugging-port=0 と一時フォルダの --user-data-dir を付けて起動することです。

ポートに 0 を渡すと番号を決めずに起動でき、実際の番号はプロファイルフォルダにできる DevToolsActivePort というファイルに書かれます。

1 行目がポート番号、2 行目が /devtools/browser/ で始まるパスで、この 2 つをつなげた WebSocket の URL に接続します。

一時プロファイルにしたのは、私が普段使う Chrome のプロファイルに触らないためでした。

Chrome 136 からの変更で、--remote-debugging-port は既定のデータフォルダに対しては効かなくなり、既定ではない --user-data-dir との組み合わせが必要になっています。

Changes to remote debugging switches to improve security  |  Blog  |  Chrome for Developers

実際に使っているスクリプトからの抜粋です(引数の一部を省いています)。

prof = tempfile.mkdtemp(prefix="headless-shot-")
proc = subprocess.Popen([chrome, "--headless=new", "--disable-gpu", "--hide-scrollbars",
                         "--no-first-run", "--disable-extensions", f"--user-data-dir={prof}",
                         "--remote-debugging-port=0", "about:blank"],
                        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
port_file = os.path.join(prof, "DevToolsActivePort")
# … ファイルができるまで待つ …
port, path = open(port_file, encoding="utf-8").read().split()[:2]
async with websockets.connect(f"ws://127.0.0.1:{port}{path}", max_size=None) as ws:
    ...  # 以降の CDP コマンドはこの接続に送る

撮るたびに Target.createTarget で新しいタブを作り、Target.attachToTarget で得たセッションに Emulation と Page のコマンドを送ります。

CDP の Emulation ドメインの説明では、Emulation.setDeviceMetricsOverride の幅・高さ・deviceScaleFactor・mobile の 4 つが必須です。

mobile を true にすると、viewport の meta タグの扱いやスクロールバー、文字の自動拡大までモバイル向けになります。

2026-10-07 には、幅 380 で mobile を true にすると scrollWidth が 380 になり、スマホ幅のレイアウトで撮れました。

デスクトップ・モバイル・モバイルのダークの 3 枚を続けて撮って、かかったのは 4.6 秒です。

2026-10-18 の計測でも、--window-size=380,1400 のままこの指定を足すと、innerWidth は 380 になりました。

ダークテーマは、Emulation.setEmulatedMedia の features に prefers-color-scheme と dark の組を渡しています。

サイト側のテーマ切り替えが「自動」のときの見た目を、これで撮れます。

撮る部分も、同じスクリプトからの抜粋です(値は 380px のダーク用に書き換えています)。

await cdp.send("Emulation.setDeviceMetricsOverride",
               {"width": 380, "height": 900, "deviceScaleFactor": 1, "mobile": True}, sid)
await cdp.send("Emulation.setEmulatedMedia",
               {"features": [{"name": "prefers-color-scheme", "value": "dark"}]}, sid)
await cdp.send("Page.navigate", {"url": url}, sid)
# … Page.loadEventFired を待つ …
shot = await cdp.send("Page.captureScreenshot",
                      {"format": "png", "captureBeyondViewport": True,
                       "clip": {"x": 0, "y": 0, "width": 380, "height": h, "scale": 1}}, sid)

Python 側の依存は websockets だけで、コメント込みで 200 行に満たない長さに収まりました。

全体を撮るときとビューポートだけ撮るときで clip を使い分ける

Page.captureScreenshot には、ビューポートの外まで撮る captureBeyondViewport と、範囲を切り出す clip があります。

CDP の Page ドメインの説明では、captureBeyondViewport の既定は false です。

2026-10-18 時点の最新版の定義では、この引数に experimental の印が付いています。

ページ全体を撮るときは、captureBeyondViewport を true にして、clip に幅とページの高さを渡しています。

長すぎるページは、高さの上限(既定は 4000px)で切るようにしました。

つまずいたのは、スクロールした位置のビューポートだけを撮ろうとしたときです。

clip に x 0・y 0 を付けたまま撮ると、スクロール後のページが白紙で返ってきました。

clip を外すと、いま見えているビューポートがそのまま撮れました。

白紙になる理由は確かめていないので、ここでは起きたことだけを書いておきます。

保留していた PR の目視に使った

この経路を最初に使ったのは、目視ができずに保留していた PR でした。

静的サイトの記事の末尾にある 4 つの節に、見出しの id と aria-labelledby を付ける変更です。

PR をマージした後の状態(merge ref)をビルドし、記事の末尾をデスクトップ・モバイル・ダークの見た目で撮りました。

ヘッドレスで撮った画像では、崩れは見つかりませんでした。

ただ、aria-labelledby が正しい見出しを指しているかは、画像からは分かりません。

そこで、ビルド後の HTML を数えて確かめました。

576 ページで、aria-labelledby の参照先が無いものと id の重複は、どちらも 0 件でした。

見た目は画像で、属性は数で確かめると分けたことで、PR を止めていた目視の条件を満たせました。

いまは、切り替えの順番を次のように決めています。

  1. Claude in Chrome のタブで visibilityState と requestAnimationFrame の回数を測る
  2. 裏のタブなら screenshot は 1 回だけ試し、タイムアウトしたら繰り返さずにヘッドレスで撮る
  3. ヘッドレスでも撮れなければ getComputedStyle などの数値の確認に切り替え、目視できなかったと記録する

ヘッドレスは毎回まっさらな一時プロファイルで起動するので、ログインが要るページはそのままでは撮れません。

最後に

AI エージェントにユーザーの実ブラウザを借りさせる方式は、ユーザーがタブを切り替えるだけで描画が止まります。

目視の経路は、ユーザーの画面を共有する経路と、画面に出ない経路を分けて持つと止まりません。

ヘッドレスで狭い幅を撮るときは、--window-size ではなく CDP の Emulation.setDeviceMetricsOverride で端末ごと指定するのが確実でした。

画像のサイズが合っていても、scrollWidth を一緒に見ておくと、組まれた幅の食い違いに気づけます。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA