web-corders-vrt

インストール不要・npxで使える、 Webページのビジュアルリグレッションテスト (VRT) を行うCLIツール。

開発マシンのブラウザを利用して、本番環境と開発環境のスクリーンショットの差分を検出する。

テスト結果は

• diff画像
• 人間向けHTMLレポート
• LLM/Claude向けJSONレポート

で出力される。

セットアップ

初回のみ Playwright のブラウザが必要:

npx playwright install chromium #通常はインストール済みのChromeが使われるはず

init コマンドで本番ドメインを指定すると、Claude Codeのスキルファイル (.claude/skills/web-corders-vrt/SKILL.md) を自動生成する

npx web-corders-vrt init --refDomain https://example.com

Claude Code連携

initで生成される .claude/skills/web-corders-vrt/SKILL.md に確認手順が記載される。 以降はCaludeに「VRTして」「差分がないようにして」とか言うだけで使ってくれる。はず。

手動での使い方

npx web-corders-vrt run \
  --reference https://production.com \
  --after http://localhost:3000 \
  --paths /,/about,/pricing

• --reference — リファレンスのプロトコル+ドメイン（本番環境）
• --after — 比較するプロトコル+ドメイン（開発 / プレビュー環境）
• --paths — テスト対象のページパス（カンマ区切り）

実行すると ./vrt-results/ 以下にタイムスタンプ付きのディレクトリが生成され、スクリーンショット・diff画像・レポートが保存される。

出力

vrt-results/2026-02-28T10-00-00/
├── report.json          # JSON レポート（Claude/LLM向け）
├── report.html          # HTML レポート（人間向け・ブラウザで開く）
└── screenshots/
    ├── top--sp--reference.png
    ├── top--sp--after.png
    ├── top--sp--diff.png
    ├── top--pc--reference.png
    ├── top--pc--after.png
    └── top--pc--diff.png

JSON レポートの構造

{
  "version": "1.0",
  "summary": {
    "totalTests": 4,
    "passed": 3,
    "failed": 1,
    "overallStatus": "fail",
  },
  "results": [
    {
      "page": { "path": "/about", "name": "about" },
      "viewport": { "type": "sp", "width": 375, "height": 812 },
      "status": "fail",
      "comparison": {
        "diffPercentage": 2.35,
        "diffPixelCount": 12040,
      },
    },
  ],
}

オプション一覧

| オプション | デフォルト | 説明 | | -------------------- | ---------- | ----------------------------------------------------------------------- | | --reference <url> | （必須） | リファレンスURL（本番環境） | | --after <url> | （必須） | 比較先URL（開発環境 / ステージング） | | --paths <paths> | （必須） | テスト対象のページパス（カンマ区切り） | | --threshold <n> | 0.1 | 差分許容率（%）。これ以下の差分はPASS扱い | | --hide <selectors> | — | 非表示にするCSSセレクタ（カンマ区切り）。例: .ad-banner,.cookie-popup |

ビューポートはSP（375x812）とPC（1440x900）の2種類で固定。フルページスクリーンショットを取得し、結果は ./vrt-results/ に出力される。

実用的な例

動的要素を隠してテスト

テスト対象外にしたい要素を非表示にする。

npx web-corders-vrt run \
  --reference https://example.com \
  --after http://localhost:3000 \
  --paths / \
  --hide ".cookie-banner,.ad-slot,[data-testid='live-chat']"

Next.jsツールバーはデフォルトで非表示。

差分許容率を緩めに設定

フォントレンダリング差異などを無視したい場合:

npx web-corders-vrt run \
  --reference https://example.com \
  --after http://localhost:3000 \
  --paths / \
  --threshold 1

広告・計測系スクリプトのブロック

以下のドメインへのリクエストは自動的にブロックされる。見た目のテストに不要であり、ページ読み込み速度を改善するため。

• googletagmanager.com
• google-analytics.com
• googleadservices.com
• googlesyndication.com
• doubleclick.net
• facebook.net / fbcdn.net
• analytics.yahoo.co.jp
• clarity.ms
• hotjar.com
• newrelic.com
• sentry.io
• datadoghq.com

動作環境

• Node.js 18 以上
• Playwright Chromium（npx playwright install chromium でインストール）