Add visual regression tests

Author: dansabin

.github/workflows/ci.yml

@@ -30,3 +30,21 @@ jobs:
       - run: npm test
       - run: npm run examples
       - run: npm pack --dry-run
+
+  visual:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm install
+      - run: npx playwright install chromium
+      - run: npm run test:visual
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: visual-regression-results
+          path: test-results/visual

.gitignore

@@ -3,6 +3,7 @@
 /node_modules
 /.vscode
 /dist
+/test-results
 
 
 # Sample Files for Testing

README.md

@@ -78,10 +78,17 @@ The package targets Node.js 20, 22, and 24.
 npm audit --audit-level=high
 npm run build
 npm test
+npm run test:visual
 npm pack --dry-run
 ```
 
-The example integration test compiles real auth and marketing templates with production-shaped data. A later visual regression layer can render those same baseline emails in a browser and compare screenshots when layout changes need full UI coverage.
+The example integration test compiles real auth and marketing templates with production-shaped data. Visual regression tests render the baseline emails in headless Chromium and compare screenshots against approved snapshots.
+
+When an intentional layout change updates the screenshots:
+
+```sh
+npm run test:visual -- --update-snapshots
+```
 
 ## Installation
 

package-lock.json

@@ -28,6 +28,7 @@
     "prepublishOnly": "npm test && npm run build",
     "prepack": "npm run build",
     "test": "vitest run",
+    "test:visual": "playwright test",
     "test:watch": "vitest"
   },
   "bin": {
@@ -39,6 +40,7 @@
     "juice": "^12.1.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@types/node": "^20.14.15",
     "typescript": "^5.5.4",
     "vitest": "^4.1.8"

package.json

@@ -0,0 +1,39 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './test/visual',
+  testMatch: '**/*.visual.ts',
+  outputDir: './test-results/visual',
+  fullyParallel: true,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 1 : 0,
+  reporter: process.env.CI ? [['github'], ['list']] : 'list',
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      threshold: 0.2
+    }
+  },
+  use: {
+    ...devices['Desktop Chrome'],
+    baseURL: 'http://127.0.0.1:4173',
+    viewport: {
+      width: 900,
+      height: 1200
+    }
+  },
+  webServer: {
+    command: 'npm run examples:serve',
+    url: 'http://127.0.0.1:4173',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        browserName: 'chromium'
+      }
+    }
+  ]
+});

playwright.config.ts

@@ -0,0 +1,21 @@
+import { expect, test } from '@playwright/test';
+
+const examples = [
+  'auth-welcome-verify.html',
+  'marketing-product-launch.html',
+  'marketing-feature-roundup.html',
+  'marketing-usage-digest.html',
+  'marketing-upgrade-offer.html'
+];
+
+test.describe('rendered email examples', () => {
+  for (const example of examples) {
+    test(`${example} matches the approved baseline`, async ({ page }) => {
+      await page.goto(`/${example}`);
+      await expect(page.locator('body')).toBeVisible();
+      await expect(page).toHaveScreenshot(`${example}.png`, {
+        fullPage: true
+      });
+    });
+  }
+});