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

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 and execute it after the cloned site is running locally.

// 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.

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.

# .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 (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 and src/app/page.tsx: Core Next.js files rendered during screenshot capture.
• 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}