screenshot-local

スクリーンショットのローカル撮影 — shot-scraper

概要

shot-scraperを使って、ローカルの開発サーバーや静的HTMLファイルのスクリーンショットを撮影します。shot-scraperはpipxでインストールするPlaywrightラッパーです。複数の画像を扱う場合は、単発のコマンドよりも、コミット済みのshots.ymlを優先してください。リポジトリから再生成できるキャプチャは最新の状態を保てますが、手動で撮影したものはUIが変更された時点で古くなります。

インストール

pipx install shot-scraper     # brew install pipx / apt install pipx first
shot-scraper install          # downloads Chromium
shot-scraper --version

インストール後にcommand not foundと表示される場合、pipxがPATHに含まれていません。pipx ensurepathを実行してから、シェルを再度開いてください。

コマンド一覧

サブコマンド	用途
shot-scraper URL	スクリーンショットを1枚撮影
shot-scraper multi shots.yml	YAMLから一括撮影
shot-scraper pdf URL	PDFとしてエクスポート
shot-scraper auth URL auth.json	再利用するログインセッションを保存
shot-scraper accessibility URL	アクセシビリティツリーをJSONとして出力

フラグ	用途
-o	出力ファイル名（標準出力には-）
-w / -h	ビューポートの幅／高さ。ページ全体を撮影する場合は-hを省略
-s / --selector-all	一致する最初の要素／すべての要素を撮影
-p	セレクターの周囲の余白（px）
--retina	デバイスのピクセル比を2倍に設定
--quality N	品質NでJPEGとして保存
--wait N / --wait-for "expr"	Nミリ秒間待機／JavaScript式が真になるまで待機
-j "js"	撮影前にJSを実行。モーダルを閉じる、状態を設定するなど
-a auth.json	保存済みの認証コンテキストを再利用
-i / --devtools	撮影を対話的にデバッグするため、ブラウザーを開く

すべてのフラグとYAMLキーについては、**reference/COMMAND-REFERENCE.md**を参照してください。上流のドキュメント：https://shot-scraper.datasette.io/.

ユーザーから指定がない場合に使う寸法：

用途	幅	高さ
READMEのヒーロー画像	1280	800
ドキュメントのスクリーンショット	1200	省略（ページ全体）
ソーシャル／OG画像	1200	630
モバイル／タブレット	375 / 768	812 / 1024

実行例

単発の撮影：

shot-scraper http://localhost:3000 -o homepage.png
shot-scraper index.html -o preview.png
shot-scraper http://localhost:3000 -w 1200 -h 630 -o og.png
shot-scraper http://localhost:3000 -s ".hero" -p 20 --retina -o [email protected]
shot-scraper http://localhost:3000 --wait-for "document.querySelector('.loaded')" -o app.png

プロジェクトのスクリーンショットを設定するには、ルーター設定、ページファイル、またはナビゲーションを確認して実際のルートと開発サーバーのポートを特定し、記録する価値のある状態（空の状態より、内容が表示された状態が望ましい）を選びます。shots.ymlを作成してから、shot-scraper multi shots.ymlを実行してください。初回の実行では、タイミングやセレクターの調整が必要になることがあります。生成された画像を開き、意図したUIが表示されていることを確認してから、作業完了を報告してください。

✅ 寸法を明示し、SPAの待機処理を指定し、出力先をディレクトリにして、一時的なブラウザーUIを除去：

- url: http://localhost:3000
  output: screenshots/homepage.png
  width: 1280
  height: 800

- url: http://localhost:3000/dashboard
  output: screenshots/dashboard.png
  width: 1280
  height: 900
  wait: 2000
  javascript: |
    document.querySelector('.toast-notification')?.remove()

❌ ローディングスピナーを撮影し、マシンによって異なる自動生成ファイル名でリポジトリのルートに出力：

- url: http://localhost:3000/dashboard

✅ 寸法を固定したOG画像。-wと-hを両方指定し、--retinaは省略：

shot-scraper http://localhost:3000 -w 1200 -h 630 -o og.png

❌ 指定寸法に--retinaを使用すると、1200×630が必要な場所に2400×1260のファイルが出力されます。カードの表示が崩れるまで問題に気付けません：

shot-scraper http://localhost:3000 -w 1200 -h 630 --retina -o og.png

✅ ドキュメントのページ全体を撮影。コンテンツに合わせて高さが決まるよう、意図的に-hを省略：

shot-scraper http://localhost:3000/docs -w 1200 -o docs.png

❌ ドキュメントページで-hを固定すると、800pxより下がすべて切り取られ、欠けたセクションが最初から書かれていなかったように見えます：

shot-scraper http://localhost:3000/docs -w 1200 -h 800 -o docs.png

プロジェクトの種類別スターター設定（SPA、Storybook、レスポンシブ表示の一括撮影、静的サイト、認証）については、**reference/TEMPLATES.md**を参照してください。

失敗モード

• 「Connection refused」 — そのポートで何も稼働していません。開発サーバーを起動し（npm run dev &）、curl -I http://localhost:3000で確認するか、ライフサイクルの管理をYAMLのserver:キーを通じてshot-scraperに任せてください。
• ページが真っ白、または読み込み中のスピナーが表示される — 撮影時にSPAのハイドレーションが完了していませんでした。固定の--wait 3000よりも、--wait-for "document.querySelector('.content')"を使ってください。高速なノートPCで調整した固定待機時間では、低速なCIランナーで失敗するためです。
• 画像が空、または別の要素が表示される — セレクターが何も見つけられなかったか、コンテンツが画面下部で遅延読み込みされています。別のセレクターを推測するのではなく、-iで再現して実際のページを確認してください。
• 負荷の高いページでタイムアウトする — --timeout 30000に引き上げてください。デフォルトのタイムアウトは、Next.jsの開発サーバーが初回リクエストでルートをコンパイルする時間より短く設定されています。
• ローカルでは成功するが、CIでは失敗する — ランナーでshot-scraper installが実行されておらず、ブラウザーエンジンがありません。CIの独立したステップとしてエンジンをインストールしてください。

注意点

• shot-scraper installは、別途実行が必要な2つ目のステップです。 pipx install shot-scraperだけではブラウザーエンジンがインストールされないため、新しいマシンで最初のキャプチャが失敗します。
• --qualityを指定すると、出力拡張子にかかわらず形式がJPEGになります。 --quality 80 -o hero.pngを実行すると、.pngという名前のファイルにJPEGデータが書き込まれます（1.9.1で確認済み）。正しいPNGが必要な場合は、--qualityを省略してください。
• --retinaで2倍になるのは出力ピクセル数であり、レイアウトではありません。 -w 1200 --retinaを指定すると幅2400pxのファイルが生成され、1200×630のOG画像のような固定サイズの用途では問題になります。README用の画像には使えますが、仕様で寸法が決まっている画像には使わないでください。
• shots.yml内のショットごとのauth:キーは無視されます。 ショット自体は成功しますが、ログアウト状態で実行されるため、認証情報の不足ではなくページの不具合のように見えます。代わりにバッチ全体に認証情報を渡してください：shot-scraper multi shots.yml -a auth.json。
• -hを省略すると、高さがコンテンツに合わせて変わるため、同じルートを2回キャプチャしてもサイズが異なる場合があります。 変更前後を比較する場合は、明示的に-hを設定してください。
• YAMLのserver:プロセスはmultiの実行全体にわたって稼働し、最後に停止します（--leave-serverを指定すると稼働を続けます）。 1つのserver:エントリーでバッチ全体をカバーします。ショットごとに繰り返しても、サーバーが追加で起動することはありません。
• ページ全体のキャプチャでは、小さな問題を見落としやすくなります。 幅1200pxの画像を見て、12pxのラベル、コントラストの問題、セルのはみ出しを判断するのは推測にすぎません。-s <selector>（および-pのパディング）で領域をキャプチャするか、PNGを切り抜いてから確認してください。モデルは、拡大して確認できる領域で最も効果的に視覚的な作業を行います。
• スクリーンショットはきれいに差分比較できません。 アンチエイリアスやフォントのレンダリングによってPNGの差分にノイズが生じるため、shot-scraperはドキュメント用の成果物に使い、リグレッションを検出する目的にはPercy、Chromatic、またはPlaywrightのtoHaveScreenshotを使ってください。

CI

GitHub Actionsのワークフローでソースの変更時にスクリーンショットを再生成し、変更をコミットして戻してください。ワークフロー全体、コスト管理、およびserver:キーのパターンについては、**reference/CI-INTEGRATION.md**を参照してください。