visualdiff

visualdiff

visualdiff は SnapDiff のビジュアルテスト API をラップします。UI の変更が意図したとおりかを検証したり、2 つのページ（またはページと保存済みのベースライン）を比較したり、任意の URL のスクリーンショットをキャプチャしたり、生の HTML/CSS をそのまま画像にレンダリングしたりできます。1 つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーの両方を利用できます。

API キーが必要です。SnapDiff ダッシュボードから取得したキーを SNAPDIFF_API_KEY に設定してください。キーが設定されていない場合、リクエストを送信する前に呼び出しが失敗します。API のベース URL は SNAPDIFF_API_URL で上書きできます。設定されていない場合、呼び出し先は https://api.snapdiff.ai/v1 です。

インストール

npx @reneturcios/visualdiff screenshot https://example.com

または、コンテナイメージを実行します。

docker run -i -e SNAPDIFF_API_KEY=sk_live_... ghcr.io/cloudcorprecords/visualdiff

コンテナはデフォルトで MCP サーバーを起動します（下記を参照）。CLI として使用するには、CLI 引数を渡します。

CLI

export SNAPDIFF_API_KEY=sk_live_...

visualdiff verify myproj pricing https://staging.example.com/pricing "added a yearly billing toggle"
visualdiff compare https://staging.example.com --before https://www.example.com
visualdiff compare http://localhost:3000 --project myproj --page-name homepage
visualdiff screenshot https://example.com --width 800 --full-page
visualdiff html-to-image "<h1>Hello</h1>" --css "h1 { color: navy; }" --width 1200 --height 630

visualdiff --version

コマンドは上流の JSON ペイロードを出力します。終了コード：成功時は 0、呼び出し失敗時（API キー未設定または上流 API エラーを含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

1 つのバイナリで両方の機能を利用できます。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/visualdiff mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "visualdiff": {
      "command": "npx",
      "args": ["-y", "@reneturcios/visualdiff", "mcp"],
      "env": { "SNAPDIFF_API_KEY": "sk_live_..." }
    }
  }
}

ツール

ツール	入力	返される内容
snapdiff_verify_ui_change	project、page_name、after、intent（すべて必須）。intent_regions、branch、threshold、match_tolerance_percent、ignore_selectors、full_page は省略可能	判定結果（pass、expected_change_detected、unexpected_regression、no_change_detected、needs_human_review のいずれか）、next_action、review_url。保存済みのページベースラインがあるプロジェクトが必要です。
snapdiff_compare_pages	after（必須）。さらに、before、またはベースラインモードの場合は project と page_name。branch、threshold、ignore_selectors、full_page は省略可能	差分率と、差分をハイライトした画像。
snapdiff_capture_screenshot	url（必須）。full_page、dark_mode、selector、width は省略可能	ページのスクリーンショット。
snapdiff_html_to_image	html（必須）。css、width、height は省略可能	レンダリングされた画像（OG カード、ソーシャル画像、メールヘッダー）。

各ツールは、ベース URL 配下のツールごとのエンドポイントに、API キーを Bearer トークンとして指定して POST で送信されます。指定されていない省略可能な引数は、リクエスト本文から完全に除外されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。