web-corders-vrt 0.1.3 → 0.1.5

package/src/reporters/terminal.ts

@@ -12,7 +12,7 @@ export function printTerminalReport(report: VrtReport): void {
   console.log("=".repeat(50));
   console.log("");
   console.log(
-    `Comparing: ${chalk.cyan(meta.beforeUrl)}  vs  ${chalk.cyan(meta.afterUrl)}`,
+    `Comparing: ${chalk.cyan(meta.referenceUrl)}  vs  ${chalk.cyan(meta.afterUrl)}`,
   );
   console.log("");
 
@@ -52,22 +52,6 @@ export function printTerminalReport(report: VrtReport): void {
           `    ${vpLabel}  ${chalk.red("❌ FAIL")}  ${chalk.red(diffStr)}  ${chalk.dim(thresholdStr)}`,
         );
 
-        // 差分領域の詳細
-        for (const region of result.diffRegions.slice(0, 5)) {
-          const { boundingBox: bb, locationHint: lh } = region;
-          console.log(
-            chalk.dim(
-              `      → Region ${region.id}: ${bb.width}x${bb.height} at (${bb.x}, ${bb.y}) - ${lh.estimatedElement}`,
-            ),
-          );
-        }
-        if (result.diffRegions.length > 5) {
-          console.log(
-            chalk.dim(
-              `      → ...and ${result.diffRegions.length - 5} more regions`,
-            ),
-          );
-        }
       }
     }
 

package/src/schemas.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 export const cliOptionsSchema = z.object({
-  before: z.string().url("--before must be a valid URL"),
+  reference: z.string().url("--reference must be a valid URL"),
   after: z.string().url("--after must be a valid URL"),
   paths: z.string().transform((val) => val.split(",").map((p) => p.trim())),
   threshold: z.coerce.number().min(0).max(100).default(0.1),

package/src/templates/SKILL-TEMPLATE.md

@@ -0,0 +1,35 @@
+---
+name: web-corders-vrt
+description: WEB用VRT(Visual Regression Test)ツール。本番ドメインとローカル開発またはプレビュードメインの間で、特定パスのビジュアル差分を検出する。
+---
+
+## 使い方
+
+```bash
+npx web-corders-vrt run \
+  --reference ${referenceDomain} \
+  --after <開発環境のドメイン|ユーザーから指示がない場合はhttp://localhost:3000> \
+  --paths <テスト対象のパス（カンマ区切り）> \
+```
+
+## 手順
+
+1. ユーザーから比較対象のドメインを指定された場合、それに従う。指示がない場合、afterは開発サーバーとし、起動していなければ `npm run dev` で起動して待機する。ここで起動したドメインとプロトコルをafterのドメインとする。
+2. 上記のコマンドでVRTを実行する（`--paths` はタスクに応じて設定する）
+3. `./vrt-results/` 内の最新ディレクトリにある `report.json` を読む
+4. `status: "fail"` のテスト結果に注目する
+5. 該当するdiff画像（`*--diff.png`）をReadツールで視覚的に確認する
+6. diff画像から修正すべきCSSやHTMLの場所を特定する
+7. ソースコードを修正する
+8. 再度VRTを実行して修正が反映されたことを確認する
+
+## オプション
+
+| オプション           | 説明                                        |
+| -------------------- | ------------------------------------------- |
+| `--reference <url>`  | リファレンスプロトコル+ドメイン（本番環境） |
+| `--after <url>`      | 比較先Uプロトコル+ドメイン（開発環境）      |
+| `--paths <paths>`    | テスト対象のページパス（カンマ区切り）      |
+| `--threshold <n>`    | 差分許容率（%）。デフォルト: 0.1            |
+| `--hide <selectors>` | 非表示にするCSSセレクタ（カンマ区切り）     |
+| `--no-open`          | HTMLレポートをブラウザで開かない            |

package/src/templates/report.html

@@ -13,7 +13,7 @@
       <h1>web-corders-vrt</h1>
       <div class="meta">
         {{TIMESTAMP}} | Duration: {{DURATION}}s<br />
-        Before: {{BEFORE_URL}} → After: {{AFTER_URL}}
+        Reference: {{REFERENCE_URL}} → After: {{AFTER_URL}}
       </div>
     </div>
     <div class="summary">

package/src/templates/types.d.ts

@@ -6,3 +6,7 @@ declare module "*.css" {
   const content: string;
   export default content;
 }
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/types.ts

@@ -3,7 +3,7 @@ export interface VrtReport {
   version: "1.0";
   meta: {
     timestamp: string;
-    beforeUrl: string;
+    referenceUrl: string;
     afterUrl: string;
     duration: number;
     command: string;
@@ -24,7 +24,7 @@ export interface VrtTestResult {
     path: string;
     name: string;
     url: {
-      before: string;
+      reference: string;
       after: string;
     };
   };
@@ -42,47 +42,24 @@ export interface VrtTestResult {
     dimensions: {
       width: number;
       height: number;
-      beforeHeight: number;
+      referenceHeight: number;
       afterHeight: number;
     };
   };
-  diffRegions: VrtDiffRegion[];
   screenshots: {
-    before: string;
+    reference: string;
     after: string;
     diff: string;
   };
   error?: string;
 }
 
-/** 差分が検出された領域 */
-export interface VrtDiffRegion {
-  id: number;
-  boundingBox: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-  };
-  diffPixelCount: number;
-  diffPercentageInRegion: number;
-  locationHint: {
-    verticalPosition: VerticalPosition;
-    horizontalPosition: HorizontalPosition;
-    fromTopPx: number;
-    fromLeftPx: number;
-    estimatedElement: string;
-  };
-}
-
 export type ViewportType = "sp" | "pc";
 export type TestStatus = "pass" | "fail" | "error";
-export type VerticalPosition = "top" | "upper" | "middle" | "lower" | "bottom";
-export type HorizontalPosition = "left" | "center" | "right" | "full-width";
 
 /** CLI実行時の解決済みオプション */
 export interface ResolvedOptions {
-  beforeUrl: string;
+  referenceUrl: string;
   afterUrl: string;
   paths: string[];
   threshold: number;
@@ -111,7 +88,7 @@ export interface ComparisonResult {
   dimensions: {
     width: number;
     height: number;
-    beforeHeight: number;
+    referenceHeight: number;
     afterHeight: number;
   };
 }

package/test/comparator.test.ts

@@ -85,7 +85,7 @@ describe("compareImages", () => {
   });
 
   it("一部だけ異なる画像の場合、差分率が正しく計算される", () => {
-    const before = createSolidPng(100, 100, 255, 255, 255);
+    const reference = createSolidPng(100, 100, 255, 255, 255);
     // 右下10x10だけ赤にする
     const after = createPngWithRegion(100, 100, 255, 255, 255, {
       x: 90,
@@ -97,7 +97,7 @@ describe("compareImages", () => {
       b: 0,
     });
 
-    const result = compareImages(before, after);
+    const result = compareImages(reference, after);
 
     expect(result.diffCount).toBeGreaterThan(0);
     // 10*10=100 / 100*100=10000 = 1%
@@ -112,14 +112,14 @@ describe("compareImages", () => {
 
     expect(result.dimensions.width).toBe(100);
     expect(result.dimensions.height).toBe(100);
-    expect(result.dimensions.beforeHeight).toBe(50);
+    expect(result.dimensions.referenceHeight).toBe(50);
     expect(result.dimensions.afterHeight).toBe(100);
     // 白でパディングされるので一部は同じ、拡張部分も白=白で差分なし
     expect(result.diffCount).toBe(0);
   });
 
   it("threshold以下の差分はpassになる", () => {
-    const before = createSolidPng(100, 100, 255, 255, 255);
+    const reference = createSolidPng(100, 100, 255, 255, 255);
     // 1ピクセルだけ微妙に違う
     const afterPng = new PNG({ width: 100, height: 100 });
     for (let i = 0; i < afterPng.data.length; i += 4) {
@@ -132,7 +132,7 @@ describe("compareImages", () => {
     afterPng.data[0] = 200;
     const after = PNG.sync.write(afterPng);
 
-    const result = compareImages(before, after, 1.0); // threshold 1%
+    const result = compareImages(reference, after, 1.0); // threshold 1%
     // 1px / 10000px = 0.01% < 1%
     expect(result.passed).toBe(true);
   });

package/tsup.config.ts

@@ -12,6 +12,7 @@ export default defineConfig({
   loader: {
     ".html": "text",
     ".css": "text",
+    ".md": "text",
   },
   banner: {
     js: "#!/usr/bin/env node",

package/src/core/region-detector.ts

@@ -1,277 +0,0 @@
-import { PNG } from "pngjs";
-import type {
-  VrtDiffRegion,
-  VerticalPosition,
-  HorizontalPosition,
-} from "../types.js";
-
-export interface RegionDetectorOptions {
-  /** この面積(px)未満の領域は無視する */
-  minRegionSize?: number;
-  /** この距離(px)以下の差分ピクセルを同一領域としてマージする */
-  mergingDistance?: number;
-}
-
-/**
- * diff画像から差分領域を検出し、座標・位置ヒントを返す。
- * Connected Component Labeling + bounding box 方式。
- */
-export function detectDiffRegions(
-  diffImageBuffer: Buffer,
-  options: RegionDetectorOptions = {},
-): VrtDiffRegion[] {
-  const { minRegionSize = 10, mergingDistance = 50 } = options;
-
-  const png = PNG.sync.read(diffImageBuffer);
-  const { width, height, data } = png;
-
-  // 1. diff ピクセル（赤色）の座標を収集
-  const diffPixels: Array<{ x: number; y: number }> = [];
-  for (let y = 0; y < height; y++) {
-    for (let x = 0; x < width; x++) {
-      const idx = (y * width + x) * 4;
-      const r = data[idx];
-      const g = data[idx + 1];
-      const b = data[idx + 2];
-      const a = data[idx + 3];
-
-      // pixelmatch の diffColor [255, 0, 0] または diffColorAlt [0, 200, 0] を検出
-      if (
-        a > 100 &&
-        ((r > 200 && g < 100 && b < 100) || (r < 100 && g > 150 && b < 100))
-      ) {
-        diffPixels.push({ x, y });
-      }
-    }
-  }
-
-  if (diffPixels.length === 0) {
-    return [];
-  }
-
-  // 2. グリッドベースのクラスタリング（高速化のため）
-  const clusters = clusterPixels(diffPixels, mergingDistance);
-
-  // 3. 各クラスタの bounding box を計算し、フィルタリング
-  const regions: VrtDiffRegion[] = clusters
-    .map((cluster, idx) => {
-      let minX = Infinity;
-      let maxX = -Infinity;
-      let minY = Infinity;
-      let maxY = -Infinity;
-      for (const p of cluster) {
-        if (p.x < minX) minX = p.x;
-        if (p.x > maxX) maxX = p.x;
-        if (p.y < minY) minY = p.y;
-        if (p.y > maxY) maxY = p.y;
-      }
-      const regionWidth = maxX - minX + 1;
-      const regionHeight = maxY - minY + 1;
-
-      return {
-        id: idx + 1,
-        boundingBox: {
-          x: minX,
-          y: minY,
-          width: regionWidth,
-          height: regionHeight,
-        },
-        diffPixelCount: cluster.length,
-        diffPercentageInRegion:
-          (cluster.length / (regionWidth * regionHeight)) * 100,
-        locationHint: estimatePosition(
-          minX,
-          minY,
-          regionWidth,
-          regionHeight,
-          width,
-          height,
-        ),
-      };
-    })
-    .filter((r) => r.diffPixelCount >= minRegionSize)
-    .sort((a, b) => b.diffPixelCount - a.diffPixelCount);
-
-  // IDを振り直す
-  return regions.map((r, i) => ({ ...r, id: i + 1 }));
-}
-
-/**
- * ピクセルをグリッドベースでクラスタリングする。
- * mergingDistance をセルサイズとしてグリッドに分割し、
- * 隣接セルのピクセルを同一クラスタとしてマージする。
- */
-function clusterPixels(
-  pixels: Array<{ x: number; y: number }>,
-  distance: number,
-): Array<Array<{ x: number; y: number }>> {
-  const cellSize = Math.max(distance, 1);
-  const grid = new Map<string, Array<{ x: number; y: number }>>();
-
-  // グリッドに割り当て
-  for (const p of pixels) {
-    const cellX = Math.floor(p.x / cellSize);
-    const cellY = Math.floor(p.y / cellSize);
-    const key = `${cellX},${cellY}`;
-    if (!grid.has(key)) {
-      grid.set(key, []);
-    }
-    grid.get(key)!.push(p);
-  }
-
-  // Union-Find でセルをクラスタリング
-  const cellKeys = Array.from(grid.keys());
-  const parent = new Map<string, string>();
-
-  function find(key: string): string {
-    if (!parent.has(key)) parent.set(key, key);
-    // 反復的にルートを探索
-    let root = key;
-    while (parent.get(root) !== root) {
-      root = parent.get(root)!;
-    }
-    // パス圧縮
-    let current = key;
-    while (current !== root) {
-      const next = parent.get(current)!;
-      parent.set(current, root);
-      current = next;
-    }
-    return root;
-  }
-
-  function union(a: string, b: string): void {
-    const ra = find(a);
-    const rb = find(b);
-    if (ra !== rb) parent.set(ra, rb);
-  }
-
-  // 隣接セルをマージ
-  for (const key of cellKeys) {
-    const [cx, cy] = key.split(",").map(Number);
-    for (let dx = -1; dx <= 1; dx++) {
-      for (let dy = -1; dy <= 1; dy++) {
-        if (dx === 0 && dy === 0) continue;
-        const neighborKey = `${cx + dx},${cy + dy}`;
-        if (grid.has(neighborKey)) {
-          union(key, neighborKey);
-        }
-      }
-    }
-  }
-
-  // クラスタごとにピクセルを集約
-  const clusters = new Map<string, Array<{ x: number; y: number }>>();
-  for (const key of cellKeys) {
-    const root = find(key);
-    if (!clusters.has(root)) {
-      clusters.set(root, []);
-    }
-    clusters.get(root)!.push(...grid.get(key)!);
-  }
-
-  return Array.from(clusters.values());
-}
-
-/**
- * 差分領域の位置から、CSSの修正箇所を推定するヒントを生成する。
- */
-function estimatePosition(
-  x: number,
-  y: number,
-  regionWidth: number,
-  regionHeight: number,
-  pageWidth: number,
-  pageHeight: number,
-): VrtDiffRegion["locationHint"] {
-  // 垂直位置の推定
-  const centerY = y + regionHeight / 2;
-  const yRatio = centerY / pageHeight;
-  let verticalPosition: VerticalPosition;
-  if (yRatio < 0.1) verticalPosition = "top";
-  else if (yRatio < 0.3) verticalPosition = "upper";
-  else if (yRatio < 0.7) verticalPosition = "middle";
-  else if (yRatio < 0.9) verticalPosition = "lower";
-  else verticalPosition = "bottom";
-
-  // 水平位置の推定
-  const centerX = x + regionWidth / 2;
-  const widthRatio = regionWidth / pageWidth;
-  let horizontalPosition: HorizontalPosition;
-  if (widthRatio > 0.8) {
-    horizontalPosition = "full-width";
-  } else if (centerX < pageWidth * 0.33) {
-    horizontalPosition = "left";
-  } else if (centerX > pageWidth * 0.67) {
-    horizontalPosition = "right";
-  } else {
-    horizontalPosition = "center";
-  }
-
-  // 要素の推定
-  const estimatedElement = guessElement(
-    verticalPosition,
-    horizontalPosition,
-    regionWidth,
-    regionHeight,
-    pageWidth,
-    y,
-  );
-
-  return {
-    verticalPosition,
-    horizontalPosition,
-    fromTopPx: y,
-    fromLeftPx: x,
-    estimatedElement,
-  };
-}
-
-/**
- * 位置とサイズから、可能性のあるUI要素を推測する。
- */
-function guessElement(
-  vPos: VerticalPosition,
-  hPos: HorizontalPosition,
-  width: number,
-  height: number,
-  pageWidth: number,
-  fromTop: number,
-): string {
-  // ページ最上部の全幅要素 → ヘッダー/ナビゲーション
-  if (vPos === "top" && hPos === "full-width" && fromTop < 100) {
-    return "Likely a header or navigation bar";
-  }
-
-  // ページ最下部の全幅要素 → フッター
-  if (vPos === "bottom" && hPos === "full-width") {
-    return "Likely a footer";
-  }
-
-  // 上部の大きな要素 → ヒーローセクション
-  if (vPos === "upper" && hPos === "full-width" && height > 200) {
-    return "Likely a hero section or banner";
-  }
-
-  // 小さなボタンサイズ
-  if (width < 200 && height < 60) {
-    return "Likely a button or small UI element";
-  }
-
-  // 横長の細い要素 → テキスト行
-  if (width > pageWidth * 0.5 && height < 40) {
-    return "Likely a text line or heading";
-  }
-
-  // カードサイズ
-  if (width > 200 && width < 500 && height > 100 && height < 400) {
-    return "Likely a card or content block";
-  }
-
-  // 画像サイズ
-  if (width > 100 && height > 100 && width < pageWidth * 0.8) {
-    return "Likely an image or media element";
-  }
-
-  return `UI element at ~${fromTop}px from top`;
-}

package/test/region-detector.test.ts

@@ -1,147 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { PNG } from "pngjs";
-import { detectDiffRegions } from "../src/core/region-detector.js";
-
-/**
- * pixelmatchが出力するような diff画像を手動で生成する。
- * 指定領域を赤 (255, 0, 0) にし、残りを半透明にする。
- */
-function createDiffImage(
-  width: number,
-  height: number,
-  regions: Array<{ x: number; y: number; w: number; h: number }>,
-): Buffer {
-  const png = new PNG({ width, height });
-
-  // 背景を半透明に
-  for (let i = 0; i < png.data.length; i += 4) {
-    png.data[i] = 0;
-    png.data[i + 1] = 0;
-    png.data[i + 2] = 0;
-    png.data[i + 3] = 25; // alpha 0.1 * 255 ≈ 25
-  }
-
-  // 差分領域を赤にする
-  for (const region of regions) {
-    for (let y = region.y; y < region.y + region.h && y < height; y++) {
-      for (let x = region.x; x < region.x + region.w && x < width; x++) {
-        const idx = (y * width + x) * 4;
-        png.data[idx] = 255; // R
-        png.data[idx + 1] = 0; // G
-        png.data[idx + 2] = 0; // B
-        png.data[idx + 3] = 255; // A
-      }
-    }
-  }
-
-  return PNG.sync.write(png);
-}
-
-describe("detectDiffRegions", () => {
-  it("差分がない画像からは領域を検出しない", () => {
-    const png = new PNG({ width: 100, height: 100 });
-    for (let i = 0; i < png.data.length; i += 4) {
-      png.data[i] = 0;
-      png.data[i + 1] = 0;
-      png.data[i + 2] = 0;
-      png.data[i + 3] = 25;
-    }
-    const buffer = PNG.sync.write(png);
-
-    const regions = detectDiffRegions(buffer);
-    expect(regions).toHaveLength(0);
-  });
-
-  it("単一の差分領域を正しく検出する", () => {
-    const diffImage = createDiffImage(200, 200, [
-      { x: 50, y: 50, w: 40, h: 30 },
-    ]);
-
-    const regions = detectDiffRegions(diffImage, { minRegionSize: 1 });
-
-    expect(regions.length).toBeGreaterThanOrEqual(1);
-    const region = regions[0];
-
-    // bounding box が概ね正しい
-    expect(region.boundingBox.x).toBeGreaterThanOrEqual(50);
-    expect(region.boundingBox.y).toBeGreaterThanOrEqual(50);
-    expect(region.boundingBox.x + region.boundingBox.width).toBeLessThanOrEqual(
-      100,
-    );
-    expect(
-      region.boundingBox.y + region.boundingBox.height,
-    ).toBeLessThanOrEqual(90);
-  });
-
-  it("離れた2つの差分領域を別々に検出する", () => {
-    const diffImage = createDiffImage(400, 400, [
-      { x: 10, y: 10, w: 30, h: 30 },
-      { x: 350, y: 350, w: 30, h: 30 },
-    ]);
-
-    const regions = detectDiffRegions(diffImage, {
-      minRegionSize: 1,
-      mergingDistance: 20, // 離れてるのでマージされない
-    });
-
-    expect(regions.length).toBe(2);
-  });
-
-  it("近い差分領域はマージされる", () => {
-    const diffImage = createDiffImage(200, 200, [
-      { x: 10, y: 10, w: 20, h: 20 },
-      { x: 40, y: 10, w: 20, h: 20 }, // 10px しか離れてない
-    ]);
-
-    const regions = detectDiffRegions(diffImage, {
-      minRegionSize: 1,
-      mergingDistance: 50, // 50px 以下はマージ
-    });
-
-    expect(regions.length).toBe(1);
-  });
-
-  it("locationHint が正しく設定される", () => {
-    // ページ上部にフル幅の差分
-    const diffImage = createDiffImage(1440, 900, [
-      { x: 0, y: 10, w: 1440, h: 60 },
-    ]);
-
-    const regions = detectDiffRegions(diffImage, { minRegionSize: 1 });
-
-    expect(regions.length).toBeGreaterThanOrEqual(1);
-    const hint = regions[0].locationHint;
-    expect(hint.verticalPosition).toBe("top");
-    expect(hint.horizontalPosition).toBe("full-width");
-    expect(hint.estimatedElement).toContain("header");
-  });
-
-  it("小さすぎる差分はminRegionSizeでフィルタされる", () => {
-    const diffImage = createDiffImage(200, 200, [
-      { x: 50, y: 50, w: 2, h: 2 }, // 4ピクセルしかない
-    ]);
-
-    const regions = detectDiffRegions(diffImage, { minRegionSize: 10 });
-    expect(regions).toHaveLength(0);
-  });
-
-  it("IDが大きい差分順に振られる", () => {
-    const diffImage = createDiffImage(400, 400, [
-      { x: 10, y: 10, w: 10, h: 10 }, // 100px
-      { x: 300, y: 300, w: 50, h: 50 }, // 2500px
-    ]);
-
-    const regions = detectDiffRegions(diffImage, {
-      minRegionSize: 1,
-      mergingDistance: 20,
-    });
-
-    expect(regions.length).toBe(2);
-    // 大きい差分が先（id=1）
-    expect(regions[0].diffPixelCount).toBeGreaterThan(
-      regions[1].diffPixelCount,
-    );
-    expect(regions[0].id).toBe(1);
-    expect(regions[1].id).toBe(2);
-  });
-});