# Visual QA Diff Process for Cloned Websites: How to Compare Generated Sites Against Originals

> Master the visual QA diff process for cloned websites. JCodesMore's template compares generated sites against originals using Playwright for pixel perfect accuracy across all devices.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-07-20

---

**The JCodesMore AI Website Cloner Template implements visual QA diff by capturing screenshots of both the original target site and the generated Next.js clone, then performing pixel-by-pixel comparisons using Playwright and pixelmatch to identify visual regressions across desktop, tablet, and mobile viewports.**

The **visual QA diff** process ensures that AI-generated website clones maintain pixel-perfect fidelity to their source designs. In the `JCodesMore/ai-website-cloner-template` repository, this validation occurs during the **"Assembly & QA"** phase of the build pipeline, where automated agents verify that the cloned output matches the original site's appearance before final delivery.

## How the Visual QA Diff Process Works

According to the repository's README (lines 94-95), the pipeline reaches the Assembly & QA stage immediately after the parallel build phase completes. Here, the system compares generated pages against the live source using a four-step browser-automation workflow.

### Step 1: Capture Baseline Screenshots from the Original Site

During the **Reconnaissance** phase, the automation agent navigates to the target URL and captures full-page screenshots for every required viewport. These baseline images are stored in `docs/design-references/` and serve as the ground truth for all subsequent comparisons. The agent typically captures three standard viewports:

- **Desktop**: 1440×900 pixels
- **Tablet**: 768×1024 pixels  
- **Mobile**: 375×667 pixels

### Step 2: Generate Screenshots from the Cloned Next.js Application

Once the Next.js application is generated and dependencies installed, the cloned site launches locally via `npm run dev`. The same viewport configurations and interaction states used during reconnaissance are rendered against `http://localhost:3000` (or the configured local port).

### Step 3: Execute Pixel-Level Comparison

The visual QA diff engine loads both image sets into memory and computes differences using `pixelmatch` with a threshold of **0.1** to account for anti-aliasing variations while catching meaningful visual regressions. The comparison generates diff images where mismatched pixels are highlighted in contrasting colors.

### Step 4: Review Diff Reports and Regressions

The system saves diff visualization files adjacent to the original screenshots and outputs a console report listing the total number of mismatched pixels per viewport. Developers use these artifacts to identify whether discrepancies stem from component styling issues, responsive layout breaks, or missing assets.

## Complete Visual QA Diff Implementation with Playwright and Pixelmatch

The following TypeScript implementation reproduces the exact visual QA step used by the template's automation agents. Place this script at [`scripts/visual-qa.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/visual-qa.ts) and execute it after the cloned site is running locally.

```typescript
// scripts/visual-qa.ts
import { chromium } from '@playwright/test';
import pixelmatch from 'pixelmatch';
import { readFileSync, writeFileSync } from 'fs';
import { PNG } from 'pngjs';

// Helper to compare two PNG buffers
function diffImages(imgA: Buffer, imgB: Buffer, outPath: string): number {
  const pngA = PNG.sync.read(imgA);
  const pngB = PNG.sync.read(imgB);
  const { width, height } = pngA;
  const diff = new PNG({ width, height });

  const mismatched = pixelmatch(
    pngA.data,
    pngB.data,
    diff.data,
    width,
    height,
    { threshold: 0.1 }
  );

  writeFileSync(outPath, PNG.sync.write(diff));
  return mismatched;
}

// Main routine – runs for a given URL and a list of viewports
async function runVisualQA(originalUrl: string, localUrl: string): Promise<void> {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  const viewports = [
    { name: 'desktop', width: 1440, height: 900 },
    { name: 'tablet', width: 768, height: 1024 },
    { name: 'mobile', width: 375, height: 667 },
  ];

  for (const vp of viewports) {
    await page.setViewportSize({ width: vp.width, height: vp.height });

    // Capture original site screenshot
    await page.goto(originalUrl, { waitUntil: 'networkidle' });
    const origPath = `tmp/orig-${vp.name}.png`;
    await page.screenshot({ path: origPath, fullPage: true });

    // Capture cloned site screenshot
    await page.goto(localUrl, { waitUntil: 'networkidle' });
    const clonePath = `tmp/clone-${vp.name}.png`;
    await page.screenshot({ path: clonePath, fullPage: true });

    // Generate diff image
    const diffPath = `tmp/diff-${vp.name}.png`;
    const mismatched = diffImages(
      readFileSync(origPath),
      readFileSync(clonePath),
      diffPath
    );

    console.log(
      `${vp.name}: ${mismatched} pixel differences – diff saved to ${diffPath}`
    );
  }

  await browser.close();
}

// Example usage (run after `npm run dev`)
runVisualQA('https://example.com', 'http://localhost:3000');

```

This script orchestrates the browser automation, handles viewport resizing, and computes visual differences using the same `pixelmatch` library referenced in the template's agent specifications.

## Integrating Visual QA into Your Development Workflow

### Local Development Testing

Run the visual QA diff locally immediately after generating a clone to verify styling accuracy before committing changes.

```bash
npm run dev
npx ts-node scripts/visual-qa.ts

```

The command sequence starts the Next.js development server on port 3000, then executes the comparison script against the running instance.

### CI/CD Pipeline Automation

Add the visual QA step to your GitHub Actions workflow (or equivalent CI platform) to block merges that introduce visual regressions.

```yaml

# .github/workflows/ci.yml (excerpt)

- name: Build cloned site
  run: npm run build
  
- name: Start server and run visual QA
  run: |
    npm run start &
    sleep 5
    npx ts-node scripts/visual-qa.ts

```

Setting a threshold for maximum allowed pixel differences ensures the workflow fails when the cloned site deviates beyond acceptable tolerances from the original design.

## Key Files Supporting the Visual QA Process

- **[`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** (lines 94-95): Documents the Assembly & QA pipeline phase where visual comparison occurs.
- **`docs/design-references/`**: Contains baseline screenshots captured during the reconnaissance phase.
- **[`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) and [`src/app/page.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/page.tsx)**: Core Next.js files rendered during screenshot capture.
- **[`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md)**: Defines the skill configuration that triggers the visual QA script automatically after builds complete.

## Summary

- **The visual QA diff process** in `ai-website-cloner-template` validates cloned output by comparing screenshots of the original site against the generated Next.js application.
- **Playwright and pixelmatch** handle browser automation and pixel-level comparison with a 0.1 threshold to filter rendering noise.
- **Three viewport sizes** (desktop, tablet, mobile) ensure responsive fidelity across device types.
- **Baseline screenshots** stored in `docs/design-references/` provide the reference standard for all regression testing.
- **CI integration** enables automated blocking of commits that introduce visual mismatches exceeding defined tolerances.

## Frequently Asked Questions

### What tools does the visual QA diff process use?

The implementation relies on **Playwright** for browser automation and screenshot capture, and **pixelmatch** for high-performance pixel-level image comparison. Alternative libraries like `looks-same` can substitute for pixelmatch if preferred, though the template defaults to pixelmatch for its speed and configurability.

### How does the system handle dynamic content or animations during comparison?

The script waits for the `networkidle` state before capturing screenshots to ensure dynamic content has loaded. For animations, the comparison uses a 0.1 threshold in pixelmatch to ignore minor anti-aliasing differences, though you may need to disable animations or use deterministic states in [`src/app/page.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/page.tsx) to achieve consistent results across runs.

### Can I adjust the sensitivity of the visual diff detection?

Yes. Modify the `threshold` parameter in the `pixelmatch` configuration within [`scripts/visual-qa.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/visual-qa.ts). Lower values (e.g., 0.05) increase sensitivity to catch subtle styling changes, while higher values (e.g., 0.2) allow more tolerance for font rendering differences between environments.

### Where are the original site screenshots stored for comparison?

The reconnaissance agent stores baseline screenshots in the **`docs/design-references/`** directory, as implemented in the template's AGENTS.md skill definition. These files persist in the repository and serve as the reference images during subsequent QA runs.