# How to Perform Visual QA Diff Comparisons After Cloning a Website

> Learn how to perform visual QA diff comparisons after cloning a website. Use Playwright and pixelmatch to identify visual regressions and ensure accuracy.

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

---

**You perform a visual QA diff by using Playwright to capture screenshots of both the original website and your cloned Next.js application across multiple viewports, then compare them pixel-by-pixel using libraries like `pixelmatch` to identify visual regressions.**

The **JCodesMore/ai-website-cloner-template** generates a full-stack Next.js project that mirrors a target website's design and functionality. After the parallel build phase completes, the pipeline enters the **"Assembly & QA"** stage—where visual QA diff comparisons ensure the cloned output matches the original source pixel-for-pixel according to the repository's [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) (lines 94-95).

## Understanding the Visual QA Diff Pipeline

The visual QA diff is not a single built-in command but rather an automated workflow implemented by agents using standard browser-automation tools. This process occurs during the Assembly & QA phase and relies on three core operations:

- **Capture baseline screenshots** of the original site during the reconnaissance step, stored in `docs/design-references/`
- **Generate comparison screenshots** from the locally running Next.js app after `npm run dev`
- **Execute pixel-level diff comparisons** using image comparison libraries to highlight discrepancies

The comparison targets the entry points defined in [`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), which render the cloned interface that must match the original design.

## Setting Up the Visual QA Diff Workflow

### Capture Baseline Screenshots from the Original Site

During the reconnaissance phase, automation agents navigate to the target URL using Playwright and capture screenshots for every required viewport state. These baseline images are saved to `docs/design-references/` and serve as the ground truth for subsequent comparisons.

### Generate Screenshots from the Cloned Next.js App

After the parallel build phase generates the Next.js components, the script launches the local development server and captures identical viewport screenshots of the rendered application. This ensures you are comparing the generated output against the original under identical conditions.

### Compare Images Using Pixel-Level Diff

The workflow uses `pixelmatch` to perform a pixel-by-pixel comparison between corresponding screenshots. This library calculates the number of mismatched pixels and generates a diff image highlighting visual regressions, enabling precise identification of layout shifts or styling errors.

## Complete Implementation Script

Create [`scripts/visual-qa.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/visual-qa.ts) to automate the visual QA diff process across desktop, tablet, and mobile viewports:

```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) {
  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) {
  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 });

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

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

    // Diff comparison
    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');

```

### Configuring Viewport Coverage

The script tests three critical breakpoints to ensure responsive design fidelity:

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

### Pixel Comparison Threshold

The implementation uses `pixelmatch` with a **threshold of 0.1** to balance sensitivity against anti-aliasing differences. This configuration catches significant visual regressions while ignoring minor rendering variations that occur naturally across different rendering engines.

## Running Visual QA Diff Locally and in CI

### Local Execution

To execute the comparison after building your clone:

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

```

This command sequence starts the Next.js development server and immediately captures screenshots for comparison against the original site.

### CI Pipeline Integration

Add visual QA diff checks to your GitHub Actions workflow to prevent merging visually inaccurate clones:

```yaml
- name: Build cloned application
  run: npm run build

- name: Run visual QA diff
  run: |
    npm run dev &
    sleep 5
    ts-node scripts/visual-qa.ts

```

Configure the script to exit with a non-zero status code when pixel differences exceed your defined threshold, blocking deployment of inaccurate clones.

## Summary

- Visual QA diff occurs during the **Assembly & QA** phase as defined in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) (lines 94-95)
- Baseline screenshots from the original site are stored in `docs/design-references/`
- The comparison uses **Playwright** for screenshot capture and **pixelmatch** with a 0.1 threshold for analysis
- Test across desktop (1440×900), tablet (768×1024), and mobile (375×667) viewports
- Run locally using `npm run dev` followed by the TypeScript execution command
- Integrate into CI pipelines to automatically block merges with visual regressions
- The agent workflow is orchestrated according to specifications in [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md)

## Frequently Asked Questions

### What tools does the AI Website Cloner Template use for visual QA diff?

The template leverages **Playwright** for browser automation and screenshot capture, combined with **pixelmatch** for pixel-level image comparison. Agents orchestrate this workflow according to specifications defined in [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md), typically running the comparison automatically after the parallel build phase completes.

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

The reconnaissance phase stores baseline screenshots in the `docs/design-references/` directory. These images serve as the ground truth when the visual QA diff script compares them against the generated Next.js application running locally on `http://localhost:3000`.

### Can I adjust the sensitivity of the visual QA diff comparison?

Yes. In [`scripts/visual-qa.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/visual-qa.ts), modify the `threshold` parameter in the `pixelmatch` configuration. The default value of `0.1` ignores minor anti-aliasing differences while catching significant visual regressions, but you can increase this value for stricter matching or decrease it to allow for minor rendering variations.

### How do I run visual QA diff checks in a CI environment?

Add a step to your workflow that runs `ts-node scripts/visual-qa.ts` after `npm run build` and starting the development server. Configure the script to exit with a non-zero status code when pixel differences exceed your threshold, ensuring that only visually accurate clones pass the automated checks before deployment.