@iqual/playwright-vrt 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# @iqual/playwright-vrt
+
+**Standalone Visual Regression Testing CLI tool using Playwright**
+
+Zero-installation visual regression testing that runs directly in CI/CD. Test visual differences across multiple projects with a single config file.
+
+## Quick Start
+
+## Why Use This?
+
+- **No per-project setup** - Just run `bunx @iqual/playwright-vrt run --test <url>` or `--config <file>`
+- **Smart defaults** - Works without a config file
+- **Flexible** - Use CLI args for quick tests, config files for complex setups
+- **CI/CD optimized** - Caches baselines, auto-detects config changes
+
+**Option 1: Quick test with URL only**:
+
+```json
+{
+  "referenceUrl": "https://production.example.com",
+  "testUrl": "https://staging.example.com",
+  "maxUrls": 25,
+  "exclude": ["**/admin/**"]
+}
+```
+
+```bash
+# Run with config file (includes both URLs)
+bunx @iqual/playwright-vrt run --config ./playwright-vrt.config.json
+
+# Or override test URL from config
+bunx @iqual/playwright-vrt run \
+  --test https://preview-branch.staging.com \
+  --config ./playwright-vrt.config.json
+
+# Or compare production vs staging
+bunx @iqual/playwright-vrt run \
+  --reference https://production.example.com \
+  --test https://staging.example.com
+```
+
+```bash
+# First run: create baseline from test URL
+bunx @iqual/playwright-vrt run --test https://staging.example.com --update-baseline
+
+# Subsequent runs: compare against cached baseline
+bunx @iqual/playwright-vrt run --test https://staging.example.com
+```
+
+**Option 2: Use config file** (`playwright-vrt.config.json`):
+
+That's it! The tool will:
+- Auto-discover URLs from your sitemap (or use defaults)
+- Create baseline screenshots from reference URL (or test URL on first run)
+- Compare against test environment
+- Generate visual diff report in `playwright-report/`
+
+## Features
+
+- ✅ **Zero installation** - Run with `bunx`, no setup needed
+- ✅ **Auto URL discovery** - Sitemap parsing + crawler fallback
+- ✅ **Smart caching** - Reuses URLs and baselines, avoids hitting production
+- ✅ **Multi-viewport** - Test desktop, mobile, tablet simultaneously
+- ✅ **Standard reports** - Playwright HTML reports with visual diffs
+- ✅ **CI/CD ready** - Built for GitHub Actions, GitLab CI, etc.
+
+## Configuration
+
+Full config example (includes URLs + advanced settings):
+
+```json
+{
+  "referenceUrl": "https://production.com",
+  "testUrl": "https://staging.com",
+  "sitemapPath": "/sitemap.xml",
+  "maxUrls": 25,
+  "exclude": ["**/admin/**", "**/user/**"],
+  "include": ["**"],
+  "viewports": [
+    { "name": "desktop", "width": 1920, "height": 1080 },
+    { "name": "mobile", "width": 375, "height": 667 }
+  ],
+  "threshold": {
+    "maxDiffPixels": 100,
+    "maxDiffPixelRatio": 0.01
+  }
+}
+```
+
+## CLI Options
+
+```bash
+bunx @iqual/playwright-vrt run \
+  --test <url>           # Test URL (required if no config)
+  --config <path>        # Config file (required if no --test)
+  --reference <url>      # Reference URL (optional, for comparison)
+  --output <dir>         # Output directory
+  --max-urls <number>    # Limit URLs to test
+  --project <name>       # Test specific viewport only
+  --verbose              # Detailed logging
+  --update-baseline      # Force regenerate URLs and baseline snapshots
+  --clean                # Remove all cached data
+
+Note: If no --reference is provided and no baseline exists, you must use --update-baseline
+```
+
+## Caching & Performance
+
+## Baseline Behavior
+
+The tool requires a **reference URL** or an **existing baseline** to run:
+
+**With explicit reference URL:**
+- Provided via `--reference` flag or `referenceUrl` in config
+- Baseline is created/updated from the reference system
+- Test URL is compared against this baseline
+
+**Without explicit reference URL:**
+- **First run**: You must use `--update-baseline` to create initial baseline from test URL
+- **Subsequent runs**: Compares test URL against cached baseline
+- Fails if no baseline exists and `--update-baseline` not set
+
+This prevents accidentally creating baselines from the wrong environment.
+
+The tool intelligently caches URLs and baseline snapshots based on your **configuration**:
+
+**First run:**
+
+- Collects URLs from sitemap/crawler
+- Creates baseline snapshots from `referenceUrl`
+- Stores cache validation hashes
+- Tests against `testUrl`
+
+**Subsequent runs:**
+
+- Validates cache by checking config and test file hashes
+- If cache is valid: reuses URLs and baseline snapshots
+- If cache is invalid: automatically regenerates (config/test changed)
+- Only tests against `testUrl` (reference system not touched when cache is valid!)
+
+**Automatic cache invalidation:**
+
+The cache is automatically invalidated and regenerated when:
+
+- Configuration changes (URLs, viewports, filters, thresholds, etc.)
+- Test file (`vrt.spec.ts`) changes in the package
+
+The hash is based on the **final merged config object**, not the config file itself.
+
+**Force update:**
+
+```bash
+bunx @iqual/playwright-vrt run --config config.json --update-baseline
+```
+
+This regenerates both URLs and baseline snapshots from the reference system regardless of cache validity.
+
+**Directory structure:**
+
+- `playwright-snapshots/` - Cached URLs + baseline screenshots (cache this in CI!)
+- `playwright-report/` - HTML test report + results
+- `playwright-tmp/` - Temporary test artifacts (auto-cleared)
+
+## GitHub Actions
+
+```yaml
+- uses: oven-sh/setup-bun@v1
+
+# Cache baseline snapshots to avoid hitting production on every run
+- uses: actions/cache@v4
+  with:
+    path: playwright-snapshots
+    key: vrt-baseline-${{ hashFiles('playwright-vrt.config.json') }}
+    restore-keys: vrt-baseline-
+
+- run: |
+    bunx @iqual/playwright-vrt run \
+      --reference https://production.com \
+      --test https://preview-${{ github.event.pull_request.number }}.staging.com
+
+- uses: actions/upload-artifact@v4
+  if: always()
+  with:
+    name: vrt-report
+    path: playwright-report/
+```
+
+## How It Works
+
+1. **Collect URLs** - Parse sitemap or crawl site (cached after first run)
+2. **Filter & limit** - Apply include/exclude patterns, limit to maxUrls
+3. **Create baseline** - Screenshot all URLs from `referenceUrl` (cached after first run)
+4. **Run tests** - Screenshot all URLs from `testUrl` and compare
+5. **Generate report** - Create Playwright HTML report with diffs
+
+All URLs and baseline snapshots are cached in `playwright-snapshots/` to minimize load on your production system.
+
+## Exit Codes
+
+- `0` - All tests passed
+- `1` - Visual differences detected
+- `2` - Configuration or runtime error
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime (for `bunx` command)
+- Or npm/yarn to install globally
+- Playwright `bunx playwright install chromium`

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@iqual/playwright-vrt",
+  "version": "0.1.0",
+  "description": "Standalone Visual Regression Testing CLI tool using Playwright",
+  "type": "module",
+  "bin": {
+    "playwright-vrt": "./src/cli.ts"
+  },
+  "files": [
+    "src/",
+    "tests/",
+    "playwright.config.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run typecheck",
+    "test": "bun run src/cli.ts --help"
+  },
+  "keywords": [
+    "visual-regression",
+    "playwright",
+    "testing",
+    "vrt",
+    "screenshot",
+    "visual-testing",
+    "regression-testing"
+  ],
+  "dependencies": {
+    "@playwright/test": "^1.40.0",
+    "micromatch": "^4.0.5",
+    "playwright": "^1.40.0",
+    "sitemapper": "^3.2.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/micromatch": "^4.0.6",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,54 @@
+import { defineConfig } from '@playwright/test';
+
+// This config is shipped with playwright-vrt package
+// User's config is loaded via environment variables
+
+const vrtConfig = process.env.VRT_CONFIG
+  ? JSON.parse(process.env.VRT_CONFIG)
+  : { viewports: [{ name: 'desktop', width: 1920, height: 1080 }] };
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 1,
+  workers: 2,
+  timeout: 60000,
+
+  // Store snapshots in playwright-snapshots/ for easy caching
+  snapshotDir: './playwright-snapshots',
+
+  // Store temporary test artifacts in playwright-tmp/
+  outputDir: './playwright-tmp',
+
+  reporter: [
+    ['html', {
+      outputFolder: process.env.OUTPUT_DIR || 'playwright-report',
+      open: 'never',
+      noSnippets: true,
+    }],
+    ['json', {
+      outputFile: process.env.OUTPUT_DIR
+        ? `${process.env.OUTPUT_DIR}/results.json`
+        : 'playwright-report/results.json'
+    }],
+    ['list'],
+  ],
+
+  use: {
+    baseURL: process.env.BASE_URL,
+    trace: 'retain-on-failure',
+    screenshot: 'on',
+    launchOptions: {
+      slowMo: 100,
+    },
+  },
+
+  // Create a project for each viewport
+  projects: vrtConfig.viewports.map((vp: any) => ({
+    name: vp.name,
+    use: {
+      viewport: { width: vp.width, height: vp.height },
+      deviceScaleFactor: 1,
+    },
+  })),
+});

package/src/cli.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env bun
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { loadConfig, validateConfig, type CLIOptions } from './config';
+import { collectURLs } from './collect';
+import { runVisualTests, printResults, hasExistingSnapshots } from './runner';
+import { createHash } from 'crypto';
+
+/**
+ * Compute SHA-256 hash of a file
+ */
+function computeFileHash(filePath: string): string {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Compute SHA-256 hash of a config object
+ */
+function computeConfigHash(config: any): string {
+  // Create a stable JSON representation (sorted keys)
+  const configStr = JSON.stringify(config, Object.keys(config).sort());
+  return createHash('sha256').update(configStr).digest('hex');
+}
+
+/**
+ * Check if cache is valid by comparing stored hashes
+ */
+function isCacheValid(snapshotDir: string, config: any): boolean {
+  const hashFile = path.join(snapshotDir, '.cache-hash.json');
+
+  if (!fs.existsSync(hashFile)) {
+    return false;
+  }
+
+  try {
+    const stored = JSON.parse(fs.readFileSync(hashFile, 'utf-8'));
+    const packageDir = path.join(__dirname, '..');
+    const testFilePath = path.join(packageDir, 'tests', 'vrt.spec.ts');
+
+    const currentHashes = {
+      config: computeConfigHash(config),
+      testFile: fs.existsSync(testFilePath) ? computeFileHash(testFilePath) : '',
+    };
+
+    // Log cache timestamp
+    console.log(`   Cache timestamp: ${stored.timestamp}`);
+
+    return stored.config === currentHashes.config &&
+           stored.testFile === currentHashes.testFile;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Save current config and test file hashes to cache
+ */
+function saveCacheHashes(snapshotDir: string, config: any): void {
+  const packageDir = path.join(__dirname, '..');
+  const testFilePath = path.join(packageDir, 'tests', 'vrt.spec.ts');
+
+  const hashes = {
+    config: computeConfigHash(config),
+    testFile: fs.existsSync(testFilePath) ? computeFileHash(testFilePath) : '',
+    timestamp: new Date().toISOString(),
+  };
+
+  const hashFile = path.join(snapshotDir, '.cache-hash.json');
+  fs.writeFileSync(hashFile, JSON.stringify(hashes, null, 2), 'utf-8');
+}
+
+async function main() {
+  const args = parseArgs();
+
+  // Either --config or --test is required
+  if (!args.config && !args.test) {
+    console.error('Error: Either --config or --test is required');
+    printUsage();
+    process.exit(2);
+  }
+
+  try {
+    // Load and validate configuration
+    let config;
+    let configPath: string | undefined;
+
+    if (args.config) {
+      // Load from config file
+      configPath = path.resolve(args.config);
+      config = await loadConfig(configPath);
+    } else {
+      // Use defaults
+      const { DEFAULT_CONFIG } = await import('./config');
+      config = { ...DEFAULT_CONFIG } as any;
+    }
+
+    // Override with CLI args
+    if (args.test) config.testUrl = args.test;
+    if (args.reference) config.referenceUrl = args.reference;
+
+    let hasExplicitReference = true;
+
+    // If no reference URL set, default to test URL
+    if (!config.referenceUrl && config.testUrl) {
+      config.referenceUrl = config.testUrl;
+      hasExplicitReference = false;
+    }
+
+    if (args.maxUrls) config.maxUrls = args.maxUrls;
+
+    validateConfig(config);
+
+    console.log('🚀 Starting Visual Regression Testing');
+    console.log(`   Reference: ${config.referenceUrl}`);
+    console.log(`   Test: ${config.testUrl}`);
+
+    // Create snapshot directory for URLs and snapshots
+    const snapshotDir = path.resolve('playwright-snapshots');
+    const outputDir = path.resolve(args.output || 'playwright-report');
+
+    if (!fs.existsSync(snapshotDir)) {
+      fs.mkdirSync(snapshotDir, { recursive: true });
+    }
+
+    if (args.verbose) {
+      console.log(`📁 Snapshots: ${snapshotDir}`);
+      console.log(`📁 Output: ${outputDir}`);
+    }
+
+    // Check if URLs already exist (unless --update-baseline)
+    const urlsPath = path.join(snapshotDir, 'urls.json');
+    let urls: string[] = [];
+
+    // Check cache validity based on config object and test file hashes
+    const cacheValid = isCacheValid(snapshotDir, config);
+    const shouldRegenerate = args.updateBaseline || !cacheValid;
+
+    if (!hasExplicitReference && !cacheValid && !args.updateBaseline) {
+      console.error('\n❌ Error: No baseline snapshots found and no reference URL provided.');
+      console.error('   Either:');
+      console.error('   1. Provide --reference <url> to create baseline from a reference system');
+      console.error('   2. Use --update-baseline to create baseline from test URL');
+      console.error('   3. Add referenceUrl to your config file\n');
+      process.exit(2);
+    }
+
+    if (fs.existsSync(urlsPath) && !shouldRegenerate) {
+      // Load existing URLs
+      console.log('\n📋 Using cached URLs from previous run');
+      urls = JSON.parse(fs.readFileSync(urlsPath, 'utf-8'));
+      console.log(`✓ Loaded ${urls.length} URLs from cache`);
+
+      if (args.verbose) {
+        console.log('   (Use --update-baseline to regenerate URLs)');
+      }
+    } else {
+      // Collect URLs from sitemap/crawler
+      if (args.updateBaseline) {
+        console.log('\n🔄 Updating baseline (regenerating URLs)...');
+      } else if (!cacheValid && fs.existsSync(urlsPath)) {
+        console.log('\n🔄 Config or test file changed, regenerating URLs...');
+      } else {
+        console.log('\n🔍 Collecting URLs (first run)...');
+      }
+
+      console.log(`   Source: ${config.referenceUrl}${config.sitemapPath || '/sitemap.xml'}`);
+      const urlResult = await collectURLs(config);
+
+      console.log(`✓ Found ${urlResult.total} URLs, filtered to ${urlResult.filtered}, using top ${urlResult.urls.length}`);
+      console.log(`  Source: ${urlResult.source}`);
+
+      urls = urlResult.urls;
+
+      // Save URLs to snapshot directory (co-located with snapshots for easy caching)
+      fs.writeFileSync(urlsPath, JSON.stringify(urls, null, 2), 'utf-8');
+
+      // Save cache hashes based on final config object
+      saveCacheHashes(snapshotDir, config);
+    }
+
+    if (urls.length === 0) {
+      throw new Error('No URLs found to test');
+    }
+
+    if (args.verbose) {
+      console.log('\n📝 URLs to test:');
+      urls.forEach((url, i) => console.log(`  ${i + 1}. ${url}`));
+    }
+
+    // Run visual regression tests using shipped Playwright config and tests
+    const results = await runVisualTests({
+      config,
+      outputDir,
+      verbose: args.verbose,
+      project: args.project,
+      updateBaseline: shouldRegenerate,
+      hasExplicitReference,
+      headed: args.headed,
+    });
+
+    // Print results
+    printResults(results, config);
+
+    // Report location
+    const reportPath = path.join(outputDir, 'index.html');
+    console.log(`\n📊 Report: ${reportPath}`);
+
+    if (args.verbose) {
+      console.log(`📁 Snapshots: ${snapshotDir}`);
+    }
+
+    // Exit with appropriate code
+    process.exit(results.failed > 0 ? 1 : 0);
+  } catch (error) {
+    console.error('\n❌ Error:', error instanceof Error ? error.message : error);
+    if (args.verbose && error instanceof Error) {
+      console.error(error.stack);
+    }
+    process.exit(2);
+  }
+}
+
+function parseArgs(): CLIOptions {
+  const args: CLIOptions = {
+    config: '',
+  };
+
+  for (let i = 2; i < process.argv.length; i++) {
+    const arg = process.argv[i];
+    const next = process.argv[i + 1];
+
+    switch (arg) {
+      case '--reference':
+        args.reference = next;
+        i++;
+        break;
+      case '--test':
+        args.test = next;
+        i++;
+        break;
+      case '--config':
+        args.config = next;
+        i++;
+        break;
+      case '--output':
+        args.output = next;
+        i++;
+        break;
+      case '--max-urls':
+        args.maxUrls = parseInt(next, 10);
+        i++;
+        break;
+      case '--project':
+        args.project = next;
+        i++;
+        break;
+      case '--verbose':
+        args.verbose = true;
+        break;
+      case '--headed':
+        args.headed = true;
+        break;
+      case '--update-baseline':
+        args.updateBaseline = true;
+        break;
+      case '--clean':
+        // Clean snapshots and reports
+        console.log('🗑️  Cleaning...');
+        ['playwright-snapshots', 'playwright-report', 'playwright-tmp'].forEach(dir => {
+          const fullPath = path.resolve(dir);
+          if (fs.existsSync(fullPath)) {
+            fs.rmSync(fullPath, { recursive: true, force: true });
+            console.log(`   Removed: ${dir}/`);
+          }
+        });
+        console.log('✓ Clean complete');
+        process.exit(0);
+        break;
+      case '--help':
+      case '-h':
+        printUsage();
+        process.exit(0);
+        break;
+    }
+  }
+
+  return args;
+}
+
+function printUsage(): void {
+  console.log(`
+Usage: playwright-vrt run [options]
+
+Required (one of):
+  --test <url>           Test URL
+  --config <path>        Path to config file with testUrl/referenceUrl
+
+Optional:
+  --reference <url>      Reference URL (defaults to --test URL or config)
+  --output <dir>         Output directory (default: ./playwright-report)
+  --max-urls <number>    Override config maxUrls
+  --project <name>       Playwright project to run (default: all)
+  --verbose              Detailed logging
+  --headed               Run browser in headed mode (visible)
+  --update-baseline      Force regenerate URLs and baseline snapshots
+  --clean                Clean playwright-snapshots/ and playwright-report/
+  --help, -h             Show this help message
+
+Examples:
+  # Minimal - compare staging against itself (first run creates baseline)
+  bunx playwright-vrt run --test https://staging.example.com
+
+  # Compare staging against production
+  bunx playwright-vrt run \\
+    --reference https://production.com \\
+    --test https://staging.com
+
+  # With config file only (contains testUrl and referenceUrl)
+  bunx playwright-vrt run --config ./playwright-vrt.config.json
+
+  # With config file + URL override
+  bunx playwright-vrt run \\
+    --test https://preview-123.staging.com \\
+    --config ./playwright-vrt.config.json
+
+Directories:
+  playwright-snapshots/  Baseline snapshots and URLs (cache this!)
+  playwright-report/     HTML test report
+  playwright-tmp/        Temporary test artifacts (cleared on each run)
+
+  Clean with: playwright-vrt run --clean
+  Or manually: rm -rf playwright-snapshots playwright-report playwright-tmp
+`);
+}
+
+// Run the CLI
+main();

package/src/collect.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env bun
+
+import Sitemapper from 'sitemapper';
+import micromatch from 'micromatch';
+import { chromium } from 'playwright';
+import type { VRTConfig } from './config';
+
+export interface URLCollectionResult {
+  urls: string[];
+  source: 'sitemap' | 'crawl';
+  total: number;
+  filtered: number;
+}
+
+export async function collectURLs(config: VRTConfig): Promise<URLCollectionResult> {
+  let urls: string[] = [];
+  let source: 'sitemap' | 'crawl' = 'sitemap';
+
+  // Try sitemap first
+  try {
+    urls = await collectFromSitemap(config.referenceUrl, config.sitemapPath || '/sitemap.xml');
+  } catch (error) {
+    console.warn('⚠️ Sitemap fetch failed, falling back to crawler');
+    // Fallback to crawling
+    urls = await crawlWebsite(config.referenceUrl, config.crawlOptions);
+    source = 'crawl';
+  }
+
+  const totalUrls = urls.length;
+
+  // Filter URLs
+  urls = filterURLs(urls, config.referenceUrl, config.include || ['*'], config.exclude || []);
+
+  // Remove duplicate URLs but keep order
+  urls = Array.from(new Set(urls));
+
+  // Limit to maxUrls
+  const maxUrls = config.maxUrls || 25;
+  const filteredCount = urls.length;
+  urls = urls.slice(0, maxUrls);
+
+  return {
+    urls,
+    source,
+    total: totalUrls,
+    filtered: filteredCount,
+  };
+}
+
+async function collectFromSitemap(baseUrl: string, sitemapPath: string): Promise<string[]> {
+  const sitemapUrl = new URL(sitemapPath, baseUrl).toString();
+
+  const sitemap = new Sitemapper({
+    url: sitemapUrl,
+    timeout: 15000,
+  });
+
+  const { sites } = await sitemap.fetch();
+
+  if (!sites || sites.length === 0) {
+    throw new Error('No URLs found in sitemap');
+  }
+
+  return sites;
+}
+
+async function crawlWebsite(
+  baseUrl: string,
+  options?: VRTConfig['crawlOptions']
+): Promise<string[]> {
+  const urls = new Set<string>();
+
+  console.log('   Using crawler (homepage links only)...');
+
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+
+  const baseUrlObj = new URL(baseUrl);
+
+  try {
+    // Visit the homepage
+    await page.goto(baseUrl, {
+      waitUntil: 'networkidle',
+      timeout: 30000
+    });
+
+    // Add the homepage itself, by adding the current page URL
+    urls.add(page.url());
+
+    // Extract all links from the page
+    const links = await page.evaluate(() => {
+      // @ts-ignore - runs in browser context
+      const anchors = Array.from(document.querySelectorAll('a[href]'));
+      // @ts-ignore - runs in browser context
+      return anchors.map(a => (a as HTMLAnchorElement).href);
+    });
+
+    // Filter links to same domain and add to set
+    for (const link of links) {
+      try {
+        const linkUrl = new URL(link);
+
+        // Only include links from the same domain
+        if (linkUrl.hostname === baseUrlObj.hostname) {
+          // Normalize URL (remove hash)
+          linkUrl.hash = '';
+          const normalizedUrl = linkUrl.toString();
+
+          if (options?.removeTrailingSlash) {
+            // Remove trailing slash for consistency (except for root)
+            const cleanUrl = normalizedUrl.endsWith('/') && normalizedUrl !== baseUrl + '/'
+              ? normalizedUrl.slice(0, -1)
+              : normalizedUrl;
+            urls.add(cleanUrl);
+          } else {
+            urls.add(normalizedUrl);
+          }
+        }
+      } catch {
+        // Skip invalid URLs
+      }
+    }
+
+    console.log(`   Found ${urls.size} URLs from homepage`);
+
+  } catch (error) {
+    console.error('   Crawler error:', error instanceof Error ? error.message : error);
+    // At minimum, return the base URL
+    urls.add(baseUrl);
+  } finally {
+    await browser.close();
+  }
+
+  return Array.from(urls);
+}
+
+function filterURLs(urls: string[], baseUrl: string, include: string[], exclude: string[]): string[] {
+  return urls.filter((url) => {
+    // Convert URL to path for pattern matching
+    const urlObj = new URL(url);
+    const path = urlObj.pathname + urlObj.search;
+
+    // Filter URLs that don't match the reference URL domain
+    const baseObj = new URL(baseUrl);
+    if (urlObj.hostname !== baseObj.hostname) {
+      return false;
+    }
+
+    // Also match against full URL for more flexibility
+    const fullUrl = url;
+
+    // Check if excluded
+    if (exclude.length > 0) {
+      if (micromatch.isMatch(path, exclude, {bash: true})) {
+        return false;
+      }
+    }
+
+    // Check if included
+    if (include.length > 0) {
+      return micromatch.isMatch(path, include, {bash: true});
+    }
+
+    return true;
+  });
+}
+
+export function saveURLs(urls: string[], filepath: string): void {
+  const content = JSON.stringify(urls, null, 2);
+  Bun.write(filepath, content);
+}

package/src/config.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+
+export interface VRTConfig {
+  referenceUrl: string;
+  testUrl: string;
+  sitemapPath?: string;
+  maxUrls?: number;
+  exclude?: string[];
+  include?: string[];
+  crawlOptions?: {
+    maxDepth?: number;
+    removeTrailingSlash?: boolean;
+  };
+  viewports?: Array<{
+    name: string;
+    width: number;
+    height: number;
+  }>;
+  threshold?: {
+    maxDiffPixels?: number;
+    maxDiffPixelRatio?: number;
+  };
+}
+
+export interface CLIOptions {
+  reference?: string;
+  test?: string;
+  config: string;
+  output?: string;
+  maxUrls?: number;
+  project?: string;
+  verbose?: boolean;
+  identifier?: string;
+  updateBaseline?: boolean;
+  headed?: boolean;
+}
+
+export const DEFAULT_CONFIG: Partial<VRTConfig> = {
+  sitemapPath: '/sitemap.xml',
+  maxUrls: 25,
+  exclude: [],
+  include: ['*'],
+  crawlOptions: {
+    maxDepth: 1,
+    removeTrailingSlash: true,
+  },
+  viewports: [
+    { name: 'desktop', width: 1920, height: 1080 },
+    { name: 'mobile', width: 375, height: 667 },
+  ],
+  threshold: {
+    maxDiffPixels: 100,
+    maxDiffPixelRatio: 0.01,
+  },
+};
+
+export async function loadConfig(configPath: string): Promise<VRTConfig> {
+  try {
+    const file = Bun.file(configPath);
+    const config = await file.json();
+
+    // Merge with defaults
+    return {
+      ...DEFAULT_CONFIG,
+      ...config,
+      crawlOptions: {
+        ...DEFAULT_CONFIG.crawlOptions,
+        ...config.crawlOptions,
+      },
+      viewports: config.viewports || DEFAULT_CONFIG.viewports,
+      threshold: {
+        ...DEFAULT_CONFIG.threshold,
+        ...config.threshold,
+      },
+    };
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      throw new Error(`Config file not found: ${configPath}`);
+    }
+    throw error;
+  }
+}
+
+export function validateConfig(config: VRTConfig): void {
+  // Validate required URLs
+  if (!config.testUrl) {
+    throw new Error('testUrl is required');
+  }
+  if (!config.referenceUrl) {
+    throw new Error('referenceUrl is required');
+  }
+
+  // Validate URL format
+  try {
+    new URL(config.referenceUrl);
+    new URL(config.testUrl);
+  } catch {
+    throw new Error('Invalid URL format in referenceUrl or testUrl');
+  }
+
+  // Validate viewports
+  if (!config.viewports || config.viewports.length === 0) {
+    throw new Error('At least one viewport must be defined');
+  }
+
+  for (const vp of config.viewports) {
+    if (!vp.name || vp.width <= 0 || vp.height <= 0) {
+      throw new Error(`Invalid viewport configuration: ${JSON.stringify(vp)}`);
+    }
+  }
+
+  // Validate threshold
+  if (config.threshold) {
+    if (config.threshold.maxDiffPixelRatio &&
+        (config.threshold.maxDiffPixelRatio < 0 || config.threshold.maxDiffPixelRatio > 1)) {
+      throw new Error('maxDiffPixelRatio must be between 0 and 1');
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import './cli.ts';

package/src/runner.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env bun
+
+import { spawn } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import type { VRTConfig } from './config';
+
+export interface TestResults {
+  passed: number;
+  failed: number;
+  total: number;
+  exitCode: number;
+}
+
+export interface RunnerOptions {
+  config: VRTConfig;
+  outputDir: string;
+  verbose?: boolean;
+  project?: string;
+  updateBaseline?: boolean;
+  hasExplicitReference?: boolean;
+  headed?: boolean;
+}
+
+/**
+ * Check if baseline snapshots already exist and are valid
+ */
+export function hasExistingSnapshots(snapshotDir: string): boolean {
+  if (!fs.existsSync(snapshotDir)) {
+    return false;
+  }
+
+  // Recursively check for any .png files
+  function hasSnapshotFiles(dir: string): boolean {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (hasSnapshotFiles(fullPath)) {
+          return true;
+        }
+      } else if (entry.name.endsWith('.png')) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  return hasSnapshotFiles(snapshotDir);
+}
+
+/**
+ * Run Playwright tests using the shipped config and test files
+ * Much simpler than the old approach - just exec playwright
+ */
+export async function runVisualTests(options: RunnerOptions): Promise<TestResults> {
+  const { config, outputDir, verbose, project, updateBaseline, hasExplicitReference, headed } = options;
+
+  // Find the playwright-vrt package directory
+  const packageDir = path.join(__dirname, '..');
+  const playwrightConfigPath = path.join(packageDir, 'playwright.config.ts');
+  const snapshotDir = path.join(process.cwd(), 'playwright-snapshots');
+
+  // Check if baseline snapshots already exist (look for any .png files in snapshots)
+  const hasBaseline = !updateBaseline && hasExistingSnapshots(snapshotDir);
+
+  if (hasBaseline) {
+    console.log('\n📸 Using existing baseline snapshots');
+    if (verbose) {
+      console.log('   (Use --update-baseline to regenerate from reference URL)');
+    }
+  } else {
+    if (updateBaseline) {
+      console.log('\n🔄 Updating baseline snapshots...');
+    } else {
+      console.log('\n📸 Creating baseline snapshots (first run)...');
+    }
+    console.log(`   Source: ${config.referenceUrl}`);
+
+    // Step 1: Create baseline screenshots
+    await runPlaywright({
+      configPath: playwrightConfigPath,
+      baseURL: config.referenceUrl,
+      vrtConfig: config,
+      outputDir,
+      updateSnapshots: true,
+      verbose: true,
+      project,
+      headed,
+    });
+
+    console.log('✓ Baseline created');
+  }
+
+  console.log(`\n🧪 Testing ${config.testUrl}`);
+
+  // Step 2: Run tests against test URL
+  const exitCode = await runPlaywright({
+    configPath: playwrightConfigPath,
+    baseURL: config.testUrl,
+    vrtConfig: config,
+    outputDir,
+    updateSnapshots: false,
+    verbose: true,
+    project,
+    headed,
+  });
+
+  // Parse results
+  const results = await parseResults(outputDir);
+  results.exitCode = exitCode;
+
+  return results;
+}
+
+interface PlaywrightRunOptions {
+  configPath: string;
+  baseURL: string;
+  vrtConfig: VRTConfig;
+  outputDir: string;
+  updateSnapshots: boolean;
+  verbose?: boolean;
+  project?: string;
+  headed?: boolean;
+}
+
+async function runPlaywright(options: PlaywrightRunOptions): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const args = ['playwright', 'test', '--config', options.configPath];
+
+    if (options.updateSnapshots) {
+      args.push('--update-snapshots');
+    }
+
+    if (options.project) {
+      args.push('--project', options.project);
+    }
+
+    if (options.headed) {
+      args.push('--headed');
+    }
+
+    const env = {
+      ...process.env,
+      BASE_URL: options.baseURL,
+      VRT_CONFIG: JSON.stringify(options.vrtConfig),
+      OUTPUT_DIR: options.outputDir,
+    };
+
+    const proc = spawn('bunx', args, {
+      env,
+      stdio: options.verbose ? 'inherit' : 'pipe',
+      shell: true,
+      cwd: process.cwd(),
+    });    let stdout = '';
+    let stderr = '';
+
+    if (!options.verbose) {
+      proc.stdout?.on('data', (data) => {
+        stdout += data.toString();
+      });
+      proc.stderr?.on('data', (data) => {
+        stderr += data.toString();
+      });
+    }
+
+    proc.on('close', (code) => {
+      const exitCode = code || 0;
+
+      // For baseline creation (update-snapshots), always succeed
+      if (options.updateSnapshots) {
+        resolve(0);
+      } else {
+        // For actual tests, return the exit code
+        resolve(exitCode);
+      }
+    });
+
+    proc.on('error', (error) => {
+      reject(new Error(`Failed to run Playwright: ${error.message}`));
+    });
+  });
+}
+
+async function parseResults(outputDir: string): Promise<TestResults> {
+  const resultsPath = path.join(outputDir, 'results.json');
+
+  try {
+    const file = Bun.file(resultsPath);
+    const results = await file.json();
+
+    let passed = 0;
+    let failed = 0;
+    let total = 0;
+
+    // Parse Playwright JSON results
+    if (results.suites) {
+      for (const suite of results.suites) {
+        if (suite.specs) {
+          for (const spec of suite.specs) {
+            total++;
+            if (spec.ok) {
+              passed++;
+            } else {
+              failed++;
+            }
+          }
+        }
+      }
+    }
+
+    return { passed, failed, total, exitCode: 0 };
+  } catch {
+    return { passed: 0, failed: 0, total: 0, exitCode: 1 };
+  }
+}
+
+export function printResults(results: TestResults, config: VRTConfig): void {
+  console.log('\n📊 Test Results:');
+  console.log(`   Total: ${results.total}`);
+  console.log(`   Passed: ${results.passed}`);
+  console.log(`   Failed: ${results.failed}`);
+
+  if (results.failed > 0) {
+    console.log(`\n❌ ${results.failed} visual difference(s) detected`);
+  } else if (results.total > 0) {
+    console.log('\n✅ All visual tests passed');
+  }
+}

package/src/workspace.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Workspace manages the .playwright-vrt/ directory
+ * This is persistent between runs for debugging and caching
+ */
+export class Workspace {
+  private readonly dir: string;
+
+  constructor(baseDir?: string) {
+    // Use .playwright-vrt in current directory (or specified base)
+    this.dir = path.join(baseDir || process.cwd(), '.playwright-vrt');
+
+    // Create workspace directory
+    fs.mkdirSync(this.dir, { recursive: true });
+  }
+
+  getPath(file: string = ''): string {
+    return file ? path.join(this.dir, file) : this.dir;
+  }
+
+  writeFile(filename: string, content: string): void {
+    const filePath = this.getPath(filename);
+    const dir = path.dirname(filePath);
+
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(filePath, content, 'utf-8');
+  }
+
+  readFile(filename: string): string {
+    const filePath = this.getPath(filename);
+    return fs.readFileSync(filePath, 'utf-8');
+  }
+
+  exists(filename: string): boolean {
+    return fs.existsSync(this.getPath(filename));
+  }
+
+  writeJSON(filename: string, data: any): void {
+    this.writeFile(filename, JSON.stringify(data, null, 2));
+  }
+
+  readJSON(filename: string): any {
+    return JSON.parse(this.readFile(filename));
+  }
+
+  // Manual cleanup - workspace is persistent by default
+  clean(): void {
+    if (fs.existsSync(this.dir)) {
+      fs.rmSync(this.dir, { recursive: true, force: true });
+      console.log(`🗑️  Cleaned workspace: ${this.dir}`);
+    }
+  }
+
+  info(): void {
+    console.log(`📁 Workspace: ${this.dir}`);
+  }
+}

package/tests/vrt.css

@@ -0,0 +1,13 @@
+*, *::before, *::after {
+  animation-duration: 0s !important;
+  animation-delay: 0s !important;
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+  scroll-behavior: auto !important;
+}
+#drupal-live-announce {
+  display: none !important;
+}
+#cookiebanner, #usercentrics-root, #CybotCookiebotDialog, #klaro, .cc-compliance {
+  display: none !important;
+}

package/tests/vrt.spec.ts

@@ -0,0 +1,53 @@
+import { test, expect } from '@playwright/test';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// Load URLs from playwright-snapshots/ (shared with snapshots for easy caching)
+const urlsPath = join(process.cwd(), 'playwright-snapshots', 'urls.json');
+
+if (!existsSync(urlsPath)) {
+  throw new Error(`URLs file not found at ${urlsPath}. Did you run URL collection?`);
+}
+
+const urls: string[] = JSON.parse(readFileSync(urlsPath, 'utf-8'));
+
+// Load config for threshold settings
+const vrtConfig = process.env.VRT_CONFIG
+  ? JSON.parse(process.env.VRT_CONFIG)
+  : {};
+
+const threshold = vrtConfig.threshold || {
+  maxDiffPixels: 100,
+  maxDiffPixelRatio: 0.01,
+};
+
+// Create a test for each URL
+for (const url of urls) {
+  test(`VRT: ${url}`, async ({ page }) => {
+    // Navigate to the URL
+    const pageUrl = new URL(url);
+    const fullPath = pageUrl.pathname + pageUrl.search;
+    await page.goto(fullPath, {
+      waitUntil: 'networkidle',
+      timeout: 30000
+    });
+
+    // Wait for fonts to load
+    await page.evaluate(() => document.fonts.ready);
+
+    // Wait for animations to settle
+    await page.evaluate(() => new Promise(resolve => requestAnimationFrame(resolve)));
+
+    // Additional stability wait for lazy-loaded content
+    await page.waitForTimeout(250);
+
+    // Take full page screenshot and compare
+    await expect(page).toHaveScreenshot({
+      fullPage: true,
+      maxDiffPixels: threshold.maxDiffPixels,
+      maxDiffPixelRatio: threshold.maxDiffPixelRatio,
+      animations: 'disabled',
+      stylePath: join(process.cwd(), 'tests', 'vrt.css')
+    }, { timeout: 10000 });
+  });
+}