# How Visual QA and Diff Are Performed in the AI Website Cloning Pipeline

> Learn how Visual QA and Diff work in the AI website cloning pipeline. Discover pixel-by-pixel comparison of screenshots to ensure accurate site replication and identify discrepancies.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: deep-dive
- Published: 2026-07-11

---

**Visual QA and Diff in the JCodesMore/ai-website-cloner-template pipeline are performed during the Assembly & QA phase by merging builder worktrees, capturing a Playwright screenshot of the generated site, and comparing it pixel-by-pixel against the reference image stored in `docs/design-references/` using `pixelmatch`, with failures flagged when mismatch scores exceed configurable thresholds.**

The JCodesMore/ai-website-cloner-template repository implements a rigorous five-phase cloning pipeline (Reconnaissance → Foundation → Component Specs → Parallel Build → Assembly & QA) where **Visual QA and Diff** serve as the final quality gate. This automated validation ensures that AI-generated website clones match their source targets with pixel-level precision before the system marks the task as complete.

## The Assembly & QA Phase

According to the pipeline overview in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) (lines 90-95), the cloning process culminates in the **Assembly & QA** phase. This final stage aggregates outputs from the preceding Parallel Build phase to validate the integrated result. The phase is designed to catch visual regressions and implementation deviations that might have occurred during component generation.

The workflow documentation in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) explicitly states that the cloning process is considered finished only after the Visual QA pass is confirmed (line 426), making this step a mandatory gate before pipeline completion.

## Step-by-Step Visual QA and Diff Implementation

### Worktree Merge and Page Assembly

After **parallel builder agents** finish their assigned components, their individual worktrees are merged into a single unified codebase. The assembled page is then wired to render the complete clone, creating a fully integrated testable artifact that mirrors the intended final output.

### Headless Browser Screenshot Capture

The pipeline launches a **headless browser** using **Playwright** with Chromium to capture a full-page screenshot of the assembled site. This generated screenshot represents the current state of the clone and serves as the test subject for comparison.

### Reference Image Retrieval

During the initial **Reconnaissance** phase, the original target site was captured and stored under `docs/design-references/`. This stored image serves as the **ground-truth** baseline for all visual comparisons, ensuring the clone matches the source design exactly.

### Pixel-Level Comparison with pixelmatch

Both the generated and reference images are fed into **pixelmatch** (or similar diffing libraries) to perform a pixel-by-pixel comparison. The library produces a diff image that highlights any pixel-level deviations and returns a numeric **mismatch score** quantifying the differences.

### Threshold-Based Validation

If the mismatch score exceeds a **configurable threshold**, the pipeline flags the Visual QA as failed. Developers can inspect the generated diff image to understand precisely where the clone deviates from the source. The pipeline proceeds only after manual review confirms the deviation is acceptable or the mismatch score falls below the threshold.

## Implementation Code Example

The following TypeScript implementation demonstrates how the Visual QA and Diff logic is typically executed within the builder scripts:

```typescript
import { chromium } from "playwright";
import pixelmatch from "pixelmatch";
import { readFileSync, writeFileSync } from "fs";
import { PNG } from "pngjs";

async function visualDiff(generatedUrl: string, referencePath: string) {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(generatedUrl);
  
  // Capture generated screenshot
  const screenshot = await page.screenshot({ fullPage: true });
  await browser.close();

  // Load both images
  const imgGenerated = PNG.sync.read(screenshot);
  const imgReference = PNG.sync.read(readFileSync(referencePath));

  // Ensure same dimensions
  const { width, height } = imgGenerated;
  const diff = new PNG({ width, height });

  const mismatch = pixelmatch(
    imgGenerated.data,
    imgReference.data,
    diff.data,
    width,
    height,
    { threshold: 0.1 }
  );

  // Save diff image for inspection
  writeFileSync("diff.png", PNG.sync.write(diff));
  return mismatch; // 0 means perfect match
}

// Usage
const mismatch = await visualDiff(
  "http://localhost:3000",               // URL of the assembled clone
  "docs/design-references/home.png"      // Reference screenshot from inspection
);

if (mismatch > 100) {
  console.error("Visual QA failed – too many pixel differences");
} else {
  console.log("Visual QA passed");
}

```

## Configuration and Key Files

- **[`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** (lines 90-95): Defines the five-phase pipeline overview and specifies the visual diff process within the Assembly & QA step.

- **[`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md)** (line 426): Documents the completion criteria requiring Visual QA pass before the clone is considered finished.

- **`docs/design-references/`**: Directory storing reference screenshots captured during the Reconnaissance phase, used as ground truth for all diff operations.

- **Builder scripts**: Generated agent scripts that invoke Playwright and diff libraries to implement the Visual QA step programmatically.

## Summary

- **Visual QA and Diff** occur in the final Assembly & QA phase of the five-stage pipeline.
- **Playwright** captures generated site screenshots for pixel-perfect comparison.
- Reference images stored in `docs/design-references/` provide the ground truth baseline.
- **`pixelmatch`** performs pixel-level diffing and returns numeric mismatch scores.
- The pipeline completes only after Visual QA passes, as enforced by [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md).

## Frequently Asked Questions

### What tools are used for Visual QA and Diff in the pipeline?

The pipeline uses **Playwright** with Chromium to capture headless browser screenshots of the generated site, and **pixelmatch** to perform pixel-by-pixel comparisons between the generated output and reference images.

### When does Visual QA occur in the cloning process?

Visual QA occurs during the **Assembly & QA** phase, which is the fifth and final stage of the pipeline. This phase executes after the Parallel Build phase completes and all builder agent worktrees have been merged.

### Where are reference screenshots stored?

Reference screenshots are stored in the **`docs/design-references/`** directory. These images are captured during the initial Reconnaissance phase and serve as the ground truth for all subsequent visual comparisons.

### What happens if the visual diff detects significant differences?

If the mismatch score exceeds the configurable threshold, the pipeline flags the Visual QA as failed and blocks progression. Developers must inspect the generated diff image to determine whether the deviations are acceptable or require correction before the pipeline can complete.