web-corders-vrt 0.1.1

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsup)",
+      "Bash(node dist/bin/vrt.js --help)",
+      "Bash(node dist/bin/vrt.js run --help)",
+      "Bash(node dist/bin/vrt.js init --help)",
+      "Bash(npm install -D prettier)",
+      "Bash(npx prettier --write .)",
+      "Bash(npm test)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,169 @@
+# web-corders-vrt
+
+Webページのビジュアルリグレッションテスト (VRT) を行うCLIツール。
+
+本番環境と開発環境のスクリーンショットをピクセル単位で比較し、差分を検出する。テスト結果は人間向け（HTMLレポート）とLLM/Claude向け（JSONレポート + diff画像）の両方で出力される。
+
+## セットアップ
+
+インストール不要。`npx` で直接実行できる。初回のみ Playwright のブラウザが必要:
+
+```bash
+npx playwright install chromium
+```
+
+## 基本的な使い方
+
+```bash
+npx vrt run \
+  --before https://example.com \
+  --after http://localhost:3000 \
+  --paths /,/about,/pricing
+```
+
+- `--before` — 比較元URL（本番環境）
+- `--after` — 比較先URL（開発環境 / ステージング）
+- `--paths` — テスト対象のページパス（カンマ区切り）
+
+実行すると `./vrt-results/` 以下にタイムスタンプ付きのディレクトリが生成され、スクリーンショット・diff画像・レポートが保存される。
+
+## 出力
+
+```
+vrt-results/2026-02-28T10-00-00/
+├── report.json          # JSON レポート（Claude/LLM向け）
+├── report.html          # HTML レポート（人間向け・ブラウザで開く）
+└── screenshots/
+    ├── top--sp--before.png
+    ├── top--sp--after.png
+    ├── top--sp--diff.png
+    ├── top--pc--before.png
+    ├── top--pc--after.png
+    └── top--pc--diff.png
+```
+
+### JSON レポートの構造
+
+```jsonc
+{
+  "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,
+      },
+      "diffRegions": [
+        {
+          "id": 1,
+          "boundingBox": { "x": 0, "y": 480, "width": 750, "height": 200 },
+          "locationHint": {
+            "verticalPosition": "upper",
+            "horizontalPosition": "full-width",
+            "fromTopPx": 480,
+            "estimatedElement": "Likely a hero section or banner",
+          },
+        },
+      ],
+    },
+  ],
+}
+```
+
+`diffRegions` の `locationHint` は、差分がページのどの位置にあるかを示す。Claudeがこれを読むことで、修正すべきCSS/HTMLの場所を推定できる。
+
+## オプション一覧
+
+| オプション           | デフォルト | 説明                                                                    |
+| -------------------- | ---------- | ----------------------------------------------------------------------- |
+| `--before <url>`     | （必須）   | 比較元URL（本番環境）                                                   |
+| `--after <url>`      | （必須）   | 比較先URL（開発環境 / ステージング）                                    |
+| `--paths <paths>`    | （必須）   | テスト対象のページパス（カンマ区切り）                                  |
+| `--threshold <n>`    | `0.1`      | 差分許容率（%）。これ以下の差分はPASS扱い                               |
+| `--hide <selectors>` | —          | 非表示にするCSSセレクタ（カンマ区切り）。例: `.ad-banner,.cookie-popup` |
+| `--no-html`          | —          | HTMLレポートを生成しない                                                |
+| `--no-open`          | —          | HTMLレポートをブラウザで自動的に開かない                                |
+
+ビューポートはSP（375x812）とPC（1440x900）の2種類で固定。フルページスクリーンショットを取得し、結果は `./vrt-results/` に出力される。
+
+## 実用的な例
+
+### 動的要素を隠してテスト
+
+広告バナーやクッキー同意バーなど、毎回変わる要素を非表示にする:
+
+```bash
+npx vrt run \
+  --before https://example.com \
+  --after http://localhost:3000 \
+  --paths / \
+  --hide ".cookie-banner,.ad-slot,[data-testid='live-chat']"
+```
+
+### 差分許容率を緩めに設定
+
+フォントレンダリング差異などを無視したい場合:
+
+```bash
+npx vrt run \
+  --before https://example.com \
+  --after http://localhost:3000 \
+  --paths / \
+  --threshold 1
+```
+
+## Claude Code連携
+
+`vrt init` コマンドで、Claude Codeのスキルファイル (`.claude/commands/vrt.md`) を自動生成できる。
+
+```bash
+npx vrt init \
+  --before https://example.com \
+  --after http://localhost:3000 \
+  --paths /,/about,/pricing
+```
+
+生成されたファイルをリポジトリにコミットすると、Claude Code上で `/vrt` コマンドを実行するだけで、VRTの実行 → 結果の読み取り → 差分箇所の特定 → コード修正 → 再テストまでを自律的に行えるようになる。
+
+### スキルファイルの仕組み
+
+生成される `.claude/commands/vrt.md` には以下の手順が記述される:
+
+1. 開発サーバーを起動
+2. VRTコマンドを実行
+3. `report.json` を読んで差分を確認
+4. diff画像を視覚的に確認
+5. `locationHint` からCSS/HTMLの修正箇所を特定
+6. コードを修正
+7. 再度VRTを実行して確認
+
+## 広告・計測系スクリプトのブロック
+
+以下のドメインへのリクエストは自動的にブロックされる。見た目のテストに不要であり、ページ読み込み速度を改善するため。
+
+- `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` でインストール）

package/bin/vrt.ts

@@ -0,0 +1,77 @@
+import { Command } from "commander";
+import { cliOptionsSchema } from "../src/schemas.js";
+import { runVrt } from "../src/commands/run.js";
+import { runInit } from "../src/commands/init.js";
+import type { ResolvedOptions } from "../src/types.js";
+
+const program = new Command();
+
+program
+  .name("vrt")
+  .description("Visual Regression Testing CLI - Compare web pages visually")
+  .version("0.1.0");
+
+program
+  .command("run")
+  .description("Run visual regression tests")
+  .requiredOption("--before <url>", "Baseline URL (production)")
+  .requiredOption("--after <url>", "Comparison URL (local/staging)")
+  .requiredOption("--paths <paths>", "Page paths to compare (comma-separated)")
+  .option("--threshold <n>", "Diff tolerance percentage", "0.1")
+  .option("--hide <selectors>", "CSS selectors to hide (comma-separated)")
+  .option("--no-html", "Skip HTML report generation")
+  .option("--no-open", "Do not open HTML report in browser")
+  .action(async (rawOptions) => {
+    try {
+      const parsed = cliOptionsSchema.parse(rawOptions);
+
+      const options: ResolvedOptions = {
+        beforeUrl: parsed.before,
+        afterUrl: parsed.after,
+        paths: parsed.paths,
+        threshold: parsed.threshold,
+        hideSelectors: parsed.hide,
+        html: parsed.html,
+        open: parsed.open,
+      };
+
+      const report = await runVrt(options);
+      process.exit(report.summary.overallStatus === "pass" ? 0 : 1);
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(`Error: ${error.message}`);
+      } else {
+        console.error("An unexpected error occurred");
+      }
+      process.exit(2);
+    }
+  });
+
+program
+  .command("init")
+  .description(
+    "Generate .claude/commands/vrt.md skill file for this repository",
+  )
+  .requiredOption("--before <url>", "Baseline URL (production)")
+  .requiredOption("--after <url>", "Comparison URL (local/staging)")
+  .requiredOption("--paths <paths>", "Page paths to compare (comma-separated)")
+  .option("--threshold <n>", "Diff tolerance percentage", "0.1")
+  .option("--hide <selectors>", "CSS selectors to hide (comma-separated)")
+  .action(async (options) => {
+    try {
+      await runInit({
+        before: options.before,
+        after: options.after,
+        paths: options.paths,
+        threshold: parseFloat(options.threshold),
+        hide: options.hide,
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(`Error: ${error.message}`);
+      }
+      process.exit(1);
+    }
+  });
+
+program.parse();