shot-scraperはPlaywrightを土台にしたCLIツールで、Webページのスクリーンショット撮影・PDF生成・動画デモ収録・JavaScriptによるスクレイピングをコマンド1つで行えます。GitHub Actions上でも動くため、ブラウザを手元にインストールせずにドキュメント用画像を自動更新する用途でよく使われています。
実体はclickベースのCLIで、shot_scraper/cli.pyがコマンド群を定義し、内部でplaywright.sync_apiを呼び出してブラウザを起動します。`shot-scraper install`でChromium・Firefox・WebKitなど対応ブラウザ（BROWSERS定数で定義）を用意し、`shot-scraper <URL>`でページを開いてスクリーンショットを保存します。`-s`セレクタ指定、`--javascript`実行、`--wait-for`条件待機、`--retina`/`--scale-factor`などのオプションがclickのデコレータ関数（browser_option、scale_factor_optionsなど）として整理されています。動画デモ機能はshot_scraper/video.pyにあるClickAction・TypeAction・WaitForActionなどのアクションクラス群が、YAMLで書いたストーリーボード（load_storyboard）を順に実行する仕組みです。HTTPエラー時の挙動は`--skip`/`--fail`オプションで制御でき、skip_or_fail関数がステータスコードをチェックします。
- STEP 01
`pip install shot-scraper`でパッケージを入れると、click・PyYAML・pydantic・playwrightなどの依存が一括で入ります。
- STEP 02
`shot-scraper install`を実行すると、Playwright用のChromiumバイナリのダウンロードが始まり、数十MB単位の追加ディスク使用が発生します。
- STEP 03
`shot-scraper https://datasette.io/`を叩くと、カレントディレクトリに`datasette-io.png`という名前のPNGファイルが生成されます。
- STEP 04
同じURLで再実行すると、既存ファイルを上書きせず`datasette-io.1.png`のように連番付きファイルが新たに作られる挙動を確認できます。
- STEP 05
`shot-scraper pdf`や`shot-scraper javascript`、`shot-scraper accessibility`などのサブコマンドを試すと、それぞれPDFファイル・JSON形式の実行結果・アクセシビリティツリーが出力されます。
- STEP 06
tests/run_examples.shを読むと、セレクタ指定・JPEG品質調整・ブラウザ切り替え（chromium/firefox/webkit）など、実運用で使う典型オプションの組み合わせが一覧できます。
指定したURLやローカルHTMLファイルから、PNG・JPEG・WebP形式のスクリーンショット、PDFファイル、JSON形式のJavaScript実行結果・アクセシビリティ情報が手元のファイルとして得られます。ストーリーボードYAMLを使えば、クリックや入力操作を含む動画デモファイルも生成できます。
`shot-scraper install`でPlaywrightのブラウザバイナリを別途ダウンロードする必要があり、単純な`pip install`だけでは動きません。
CI環境（.github/workflows/test.yml）ではChromium・Firefox・WebKitの3ブラウザを個別にインストールしており、実行環境にはそれなりのディスク容量とネットワーク帯域が必要です。
cliのオプションはURLごと・出力形式ごとに多岐にわたるため（セレクタ、待機条件、認証、ビューポートなど）、README記載のクイックスタートだけでは全機能を把握しづらく、docs/以下の個別ページを読む必要があります。
ドキュメント画像の自動生成やニュースサイトのスクリーンショット監視など、定期実行かつコマンド一発で完結させたい用途に向いています。README・pyproject.toml・実際のcli.py・video.py・テストコードの内容が一致しており、コマンド例（tests/run_examples.sh）も具体的で再現性が高いため、実際に動かさなくても機能範囲の判断は十分信頼できます。