CI で OpenScreenShot CLI を使うと、実行中のアプリケーションの PNG をレビュー用に保存できます。Chrome 互換ブラウザを用意し、アプリケーションを起動して準備ができるまで待ち、固定の URL とビューポートでキャプチャします。できたファイルは、CI プロバイダーの成果物 (artifact) の仕組みでアップロードします。

環境を再現できるようにする

すでに pnpm を使っているプロジェクトでは、CLI を開発用の依存関係として追加し、マニフェストとロックファイルの変更をコミットします。

pnpm add -D -E openscreenshot

CI では、プロジェクトのロックファイルを固定したまま (frozen lockfile) 依存関係をインストールします。このパッケージは puppeteer-core を使い、ブラウザをダウンロードしないため、ランナーには Chrome または Chromium も必要です。実行ファイルが対応するデフォルトの場所にない場合は、CHROME_PATH を設定します。

キャプチャを比較するときは、ブラウザのバージョン、フォント、ビューポート、アプリケーションのデータ、パッケージのバージョンを固定してください。アプリケーションのコードが変わっていなくても、フォントやブラウザのレンダラーが変わると画像が変わることがあります。

アプリケーションの準備ができてからキャプチャする

プロジェクト独自のコマンドで、開発サーバーまたはプレビュー サーバーを起動します。この例を実行する前に、ルートとその依存先の準備ができるまで待ってください。ポート 4321 は例にすぎず、お使いのアプリケーションに合わせる必要があります。

mkdir -p artifacts
pnpm exec openscreenshot shot http://127.0.0.1:4321 --out artifacts/desktop.png --width 1440 --height 900
pnpm exec openscreenshot shot http://127.0.0.1:4321 --out artifacts/narrow.png --width 390 --height 844

これらのコマンドはビューポートをキャプチャします。ページ全体をレビューするには --full を追加します。CI の成果物アップロードのステップに artifacts/ ディレクトリを渡すと、レビュー担当者はプル リクエストやリリースと並べてファイルを開けます。

CLI はページ移動中にネットワークが落ち着くのを待ちますが、アプリケーション固有の処理が完了したことは保証されません。設定可能なセレクターの待機や、注入するセットアップ スクリプトはありません。通常のルートにアニメーション、変化するコンテンツ、認証が含まれる場合は、決まったデータを使う、安定したレビュー専用のルートを使ってください。

画像をキャプチャできても見た目のテストに合格したわけではない

コマンドは、サーバー エラーや読み込み画面のスクリーンショットを撮った後でも正常に終了することがあります。PNG はレビュー用の成果物として扱ってください。見た目の回帰テストの仕組みには、ベースライン、画像の比較方法、しきい値、意図した変更を承認する手順も必要です。OpenScreenShot の CLI はこれらを提供しません。

狭いスクリーンショットはレスポンシブ レイアウトの確認には役立ちますが、モバイル デバイスのエミュレーションではありません。同様に、スクリーンショットでは操作、アクセシビリティ、API の動作は確認できません。キャプチャのステップと並べて、アプリケーションに関係するチェックも残してください。

パイプラインのトラブルシューティング

Chrome が見つからない: ランナーのイメージにブラウザが含まれていること、CHROME_PATH がその実行ファイルを指していることを確認します。

ページ移動が失敗する、またはタイムアウトする: キャプチャのプロセスからサーバーに到達できること、想定どおりのポートを使っていること、キャプチャ開始前に準備ができていることを確認します。ページ移動のタイムアウトは 30 秒です。

予期しないログイン ページが表示される: CLI は新しいブラウザ セッションを開始します。ローカルのプロファイルは再利用せず、Cookie の注入もできません。

出力ファイルがない: 出力ディレクトリを作成し、コマンドの終了ステータスを調べ、CI の作業ディレクトリから見た成果物のパスを確認します。

フラグと終了コードは、CLI のリファレンス ガイドで説明しています。次にどのページを調べるかを人やエージェントが判断する場合は、MCP でのスクリーンショットの手順を使ってください。