@usefragments/core 1.0.0

package/src/preview/comparison.test.ts

@@ -0,0 +1,559 @@
+import { describe, expect, it } from "vitest";
+import {
+  comparePreviewToDesign,
+  buildPreviewComparisonArtifactPayload,
+  buildPreviewDesignComparisonEvidence,
+  buildPreviewDesignReferenceFromReport,
+  formatPreviewComparisonFinding,
+  getPreviewComparisonSignals,
+  getPreviewComparisonRegionOverlays,
+  resolvePreviewComparisonThresholds,
+} from "./index";
+
+describe("preview design comparison", () => {
+  it("passes when image, dimensions, and styles are within tolerance", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Button / Primary",
+        nodeUrl: "https://www.figma.com/design/abc/System?node-id=1%3A2",
+        size: { width: 120, height: 40 },
+        styles: {
+          backgroundColor: "#006adc",
+          borderRadius: "8px",
+          fontSize: "14px",
+        },
+      },
+      preview: {
+        kind: "preview",
+        label: "Button / primary",
+        componentKey: "Button",
+        variantId: "primary",
+        size: { width: 120.5, height: 40 },
+        styles: {
+          backgroundColor: "rgb(0, 106, 220)",
+          borderRadius: "8px",
+          fontSize: "14px",
+        },
+      },
+      imageDiff: {
+        diffPercentage: 0.2,
+        changedRegions: [],
+        diffImageUrl: "/diffs/button-primary.png",
+      },
+    });
+
+    expect(report.status).toBe("pass");
+    expect(report.score).toBeGreaterThanOrEqual(90);
+    expect(report.findings).toEqual([]);
+    expect(report.image?.match).toBe(true);
+    expect(report.image?.diffImageUrl).toBe("/diffs/button-primary.png");
+    expect(report.dimensions?.match).toBe(true);
+    expect(report.styles?.match).toBe(true);
+    expect(getPreviewComparisonSignals(report)).toEqual([
+      {
+        id: "image",
+        label: "Image diff",
+        status: "pass",
+        value: "0.2% changed",
+        detail: "0 changed regions; threshold 1%.",
+      },
+      {
+        id: "dimensions",
+        label: "Size",
+        status: "pass",
+        value: "+0.5 x 0 px",
+        detail: "120 x 40 design, 120.5 x 40 preview; tolerance +/-1px.",
+      },
+      {
+        id: "styles",
+        label: "Styles",
+        status: "pass",
+        value: "3/3 matched",
+        detail: "All checked computed styles are within tolerance.",
+      },
+    ]);
+  });
+
+  it("fails when visual diff exceeds threshold and explains changed regions", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Card",
+        size: { width: 320, height: 220 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Card",
+        componentKey: "Card",
+        size: { width: 336, height: 220 },
+      },
+      imageDiff: {
+        diffPercentage: 4.75,
+        changedRegions: [{ x: 24, y: 16, width: 120, height: 48 }],
+      },
+      thresholds: {
+        imageDiffPercentage: 1,
+      },
+    });
+
+    expect(report.status).toBe("fail");
+    expect(report.image?.match).toBe(false);
+    expect(report.dimensions?.match).toBe(false);
+    expect(report.findings).toMatchObject([
+      {
+        code: "image-diff-threshold-exceeded",
+        severity: "error",
+        bounds: { x: 24, y: 16, width: 120, height: 48 },
+      },
+      {
+        code: "dimension-mismatch",
+        severity: "warning",
+      },
+    ]);
+    expect(getPreviewComparisonSignals(report)).toMatchObject([
+      {
+        id: "image",
+        status: "fail",
+        value: "4.75% changed",
+      },
+      {
+        id: "dimensions",
+        status: "review",
+        value: "+16 x 0 px",
+      },
+      {
+        id: "styles",
+        status: "missing",
+        value: "No styles",
+      },
+    ]);
+    expect(getPreviewComparisonRegionOverlays(report)).toEqual([
+      {
+        x: 24,
+        y: 16,
+        width: 120,
+        height: 48,
+        label: "Changed region x 24 y 16 width 120 height 48",
+        leftPercent: 7.14,
+        topPercent: 7.27,
+        widthPercent: 35.71,
+        heightPercent: 21.82,
+      },
+    ]);
+  });
+
+  it("clips direct comparison overlays to the comparison source", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Card",
+        size: { width: 100, height: 80 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Card",
+        componentKey: "Card",
+        size: { width: 100, height: 80 },
+      },
+      imageDiff: {
+        diffPercentage: 0.2,
+        changedRegions: [
+          { x: 90, y: 70, width: 20, height: 20 },
+          { x: 110, y: 10, width: 10, height: 10 },
+        ],
+      },
+    });
+
+    expect(getPreviewComparisonRegionOverlays(report)).toEqual([
+      {
+        x: 90,
+        y: 70,
+        width: 20,
+        height: 20,
+        label: "Changed region x 90 y 70 width 20 height 20",
+        leftPercent: 90,
+        topPercent: 87.5,
+        widthPercent: 10,
+        heightPercent: 12.5,
+      },
+    ]);
+  });
+
+  it("compares style values with color and numeric tolerance", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Input",
+        styles: {
+          backgroundColor: "#fff8",
+          borderColor: "#d0d5dd",
+          borderRadius: "6px",
+          padding: "12px",
+        },
+      },
+      preview: {
+        kind: "preview",
+        label: "Input",
+        componentKey: "Input",
+        styles: {
+          backgroundColor: "rgb(255 255 255 / 53%)",
+          borderColor: "rgb(210, 215, 222)",
+          borderRadius: "9px",
+          padding: "12.5px",
+        },
+      },
+    });
+
+    expect(report.status).toBe("review");
+    expect(report.styles?.properties).toEqual([
+      {
+        property: "backgroundColor",
+        design: "#fff8",
+        preview: "rgb(255 255 255 / 53%)",
+        match: true,
+      },
+      {
+        property: "borderColor",
+        design: "#d0d5dd",
+        preview: "rgb(210, 215, 222)",
+        match: true,
+      },
+      {
+        property: "borderRadius",
+        design: "6px",
+        preview: "9px",
+        match: false,
+      },
+      {
+        property: "padding",
+        design: "12px",
+        preview: "12.5px",
+        match: true,
+      },
+    ]);
+  });
+
+  it("marks reports incomplete when adapters provide no comparison signals", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Empty",
+      },
+      preview: {
+        kind: "preview",
+        label: "Empty",
+        componentKey: "Empty",
+      },
+    });
+
+    expect(report.status).toBe("incomplete");
+    expect(report.score).toBeNull();
+    expect(report.findings).toMatchObject([
+      {
+        code: "missing-comparison-signal",
+        severity: "warning",
+      },
+    ]);
+  });
+
+  it("builds manifest-ready comparison evidence from a live report", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Button / Primary",
+        fileKey: "file123",
+        nodeId: "1:2",
+        nodeUrl: "https://www.figma.com/design/file123/System?node-id=1%3A2",
+        imageDataUrl: "data:image/png;base64,figma",
+        size: { width: 120, height: 40 },
+        styles: {
+          backgroundColor: "#006adc",
+          ignored: undefined,
+        },
+      },
+      preview: {
+        kind: "preview",
+        label: "Button / Primary",
+        componentKey: "Button",
+        variantId: "primary",
+        theme: "light",
+        viewport: { width: 120, height: 40 },
+        imageDataUrl: "data:image/png;base64,preview",
+        size: { width: 120, height: 40 },
+        styles: {
+          backgroundColor: "rgb(0, 106, 220)",
+        },
+        capturedAt: "2026-05-24T00:00:00.000Z",
+      },
+      imageDiff: {
+        diffPercentage: 0.2,
+        diffImageDataUrl: "data:image/png;base64,diff",
+        diffPixelCount: 96,
+        totalPixels: 4800,
+        changedRegions: [{ x: 10, y: 8, width: 20, height: 12 }],
+      },
+    });
+
+    expect(buildPreviewDesignComparisonEvidence(report)).toEqual({
+      state: {
+        variantId: "primary",
+        theme: "light",
+        viewport: { width: 120, height: 40 },
+      },
+      previewImageUrl: "data:image/png;base64,preview",
+      previewSize: { width: 120, height: 40 },
+      designStyles: {
+        backgroundColor: "#006adc",
+      },
+      previewStyles: {
+        backgroundColor: "rgb(0, 106, 220)",
+      },
+      diffImageUrl: "data:image/png;base64,diff",
+      diffPercentage: 0.2,
+      diffPixelCount: 96,
+      totalPixels: 4800,
+      changedRegions: [{ x: 10, y: 8, width: 20, height: 12 }],
+      capturedAt: "2026-05-24T00:00:00.000Z",
+    });
+    expect(buildPreviewDesignReferenceFromReport(report)).toEqual({
+      provider: "figma",
+      label: "Button / Primary",
+      nodeUrl: "https://www.figma.com/design/file123/System?node-id=1%3A2",
+      fileKey: "file123",
+      nodeId: "1:2",
+      imageUrl: "data:image/png;base64,figma",
+      size: { width: 120, height: 40 },
+      comparison: buildPreviewDesignComparisonEvidence(report),
+    });
+
+    expect(
+      buildPreviewComparisonArtifactPayload({
+        report,
+        assets: {
+          rendered: "Button-rendered.png",
+          figma: "Button-figma.png",
+          diff: "Button-diff.png",
+        },
+      })
+    ).toMatchObject({
+      target: {
+        componentKey: "Button",
+        variantId: "primary",
+        designReferenceScope: "variant",
+      },
+      report,
+      designReference: {
+        imageUrl: "Button-figma.png",
+        comparison: {
+          previewImageUrl: "Button-rendered.png",
+          diffImageUrl: "Button-diff.png",
+        },
+      },
+      comparisonEvidence: {
+        previewImageUrl: "Button-rendered.png",
+        diffImageUrl: "Button-diff.png",
+      },
+    });
+  });
+
+  it("does not persist stale comparison context as reusable evidence", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Card",
+        size: { width: 320, height: 220 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Card",
+        componentKey: "Card",
+        size: { width: 320, height: 220 },
+      },
+      context: {
+        scope: "component",
+        captured: { theme: "light" },
+        active: { theme: "dark" },
+        stale: true,
+        staleReasons: ["theme"],
+      },
+    });
+
+    expect(buildPreviewDesignComparisonEvidence(report)).toBeNull();
+    expect(buildPreviewDesignReferenceFromReport(report)).toEqual({
+      provider: "figma",
+      label: "Card",
+      size: { width: 320, height: 220 },
+    });
+    expect(
+      buildPreviewComparisonArtifactPayload({
+        report,
+        designReference: {
+          provider: "figma",
+          label: "Card",
+          comparison: {
+            diffPercentage: 0.1,
+            previewImageUrl: "stale-rendered.png",
+          },
+        },
+      })
+    ).toEqual({
+      target: {
+        componentKey: "Card",
+        designReferenceScope: "component",
+      },
+      report,
+      designReference: {
+        provider: "figma",
+        label: "Card",
+      },
+    });
+  });
+
+  it("formats comparison findings for terminal and machine surfaces", () => {
+    expect(
+      formatPreviewComparisonFinding({
+        code: "style-mismatch",
+        severity: "warning",
+        message: "borderRadius differs between Figma and the preview.",
+        property: "borderRadius",
+      })
+    ).toBe("WARNING: borderRadius: borderRadius differs between Figma and the preview.");
+  });
+
+  it("normalizes invalid comparison thresholds before scoring", () => {
+    const thresholds = resolvePreviewComparisonThresholds({
+      imageDiffPercentage: -1,
+      dimensionPx: Number.NaN,
+      numericPx: Number.NEGATIVE_INFINITY,
+      colorChannel: 300,
+      alpha: 2,
+    });
+
+    expect(thresholds).toEqual({
+      imageDiffPercentage: 1,
+      dimensionPx: 1,
+      numericPx: 1,
+      colorChannel: 5,
+      alpha: 0.05,
+    });
+
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Badge",
+        size: { width: 80, height: 24 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Badge",
+        componentKey: "Badge",
+        size: { width: 80, height: 24 },
+      },
+      imageDiff: {
+        diffPercentage: 0.5,
+      },
+      thresholds: {
+        imageDiffPercentage: -1,
+        dimensionPx: Number.NaN,
+      },
+    });
+
+    expect(report.thresholds.imageDiffPercentage).toBe(1);
+    expect(report.thresholds.dimensionPx).toBe(1);
+    expect(report.status).toBe("pass");
+  });
+
+  it("preserves valid zero thresholds for strict comparisons", () => {
+    expect(
+      resolvePreviewComparisonThresholds({
+        imageDiffPercentage: 0,
+        dimensionPx: 0,
+        numericPx: 0,
+        colorChannel: 0,
+        alpha: 0,
+      })
+    ).toEqual({
+      imageDiffPercentage: 0,
+      dimensionPx: 0,
+      numericPx: 0,
+      colorChannel: 0,
+      alpha: 0,
+    });
+  });
+
+  it("skips invalid runtime comparison signals before scoring", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Runtime input",
+        size: { width: 120, height: 40 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Runtime input",
+        componentKey: "RuntimeInput",
+        size: { width: 120, height: 40 },
+      },
+      imageDiff: {
+        diffPercentage: Number.NaN,
+      },
+    });
+
+    expect(report.image).toBeUndefined();
+    expect(report.dimensions?.match).toBe(true);
+    expect(report.status).toBe("review");
+    expect(report.findings).toMatchObject([
+      {
+        code: "invalid-comparison-signal",
+        severity: "warning",
+      },
+    ]);
+  });
+
+  it("omits invalid optional image evidence from runtime reports", () => {
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Runtime image",
+        size: { width: 120, height: 40 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Runtime image",
+        componentKey: "RuntimeImage",
+        size: { width: 120, height: 40 },
+      },
+      imageDiff: {
+        diffPercentage: 0.2,
+        diffPixelCount: 5000,
+        totalPixels: 4800,
+        changedRegions: [
+          { x: 4, y: 4, width: 12, height: 8 },
+          { x: -1, y: 0, width: 12, height: 8 },
+        ],
+      },
+    });
+
+    expect(report.image).toMatchObject({
+      diffPercentage: 0.2,
+      changedRegions: [{ x: 4, y: 4, width: 12, height: 8 }],
+    });
+    expect(report.image?.diffPixelCount).toBeUndefined();
+    expect(report.image?.totalPixels).toBeUndefined();
+    expect(report.status).toBe("review");
+    expect(report.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: "invalid-comparison-signal",
+          message:
+            "Image diff pixel counts must be whole numbers with changed pixels less than or equal to total pixels.",
+        }),
+        expect.objectContaining({
+          code: "invalid-comparison-signal",
+          message: "Changed regions must use finite non-negative coordinates and positive sizes.",
+        }),
+      ])
+    );
+  });
+});