internal: Adding visual regression testing

.github/actions/setup-build-cache/action.yml

@@ -0,0 +1,14 @@
+name: Setup Build Cache
+description: Restores the build cache from GitHub Actions cache
+
+runs:
+  using: composite
+  steps:
+    - name: Restore build cache
+      uses: actions/cache@v4
+      with:
+        path: .build-cache
+        key: build-cache-v2-${{ runner.os }}-${{ github.sha }}
+        restore-keys: |
+          build-cache-v2-${{ runner.os }}-
+

.github/workflows/ci.yml

@@ -8,11 +8,12 @@ on:
   workflow_dispatch:
 
 jobs:
-  test:
-    name: Test Build
+  lint:
+    name: Lint & Checks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout code
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -23,13 +24,8 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Restore build cache
-        uses: actions/cache@v4
-        with:
-          path: .build-cache
-          key: build-cache-v1-${{ runner.os }}-${{ hashFiles('openapi/**/*.yaml', 'changelog/entries/**/*.md', 'package.json', 'pnpm-lock.yaml', 'scripts/**/*.{mjs,ts}', 'docs/**/*.{md,mdx}', 'src/**/*.{ts,tsx,js,jsx}', 'docusaurus.config.ts', 'sidebars.ts') }}
-          restore-keys: |
-            build-cache-v1-${{ runner.os }}-
+      - name: Setup build cache
+        uses: ./.github/actions/setup-build-cache
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -45,5 +41,45 @@ jobs:
             echo "No usage of support@glean.com found"
           fi
 
-      - name: Test build website
-        run: pnpm build 
+  build:
+    name: Build Site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up mise
+        uses: jdx/mise-action@v2
+        with:
+          cache: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup build cache
+        uses: ./.github/actions/setup-build-cache
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build website
+        run: pnpm build
+        env:
+          VERBOSE: "true"
+
+      - name: Upload build artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: build
+          path: build/
+          retention-days: 1
+
+  visual-regression:
+    name: Visual Regression Tests
+    needs: build
+    if: github.event_name == 'pull_request'
+    uses: ./.github/workflows/visual-regression.yml
+    with:
+      commit-sha: ${{ github.event.pull_request.head.sha }}

.github/workflows/update-visual-snapshots.yml

@@ -0,0 +1,47 @@
+name: Update Visual Snapshots
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update-snapshots:
+    name: Update Visual Regression Snapshots
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up mise
+        uses: jdx/mise-action@v2
+        with:
+          cache: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Build the website
+        run: pnpm build
+
+      - name: Update snapshots
+        run: pnpm test:visual:update
+
+      - name: Commit snapshots
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add tests/visual-regression/__snapshots__/
+          git diff --staged --quiet || git commit -m "Update visual regression snapshots [skip ci]"
+          git push origin HEAD:${{ github.ref_name }}
+

.github/workflows/visual-regression.yml

@@ -0,0 +1,104 @@
+name: Visual Regression Testing
+
+on:
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      commit-sha:
+        description: "Commit SHA"
+        type: string
+        required: false
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check-paths:
+    name: Check Visual File Changes
+    runs-on: ubuntu-latest
+    outputs:
+      should-run: ${{ steps.filter.outputs.visual == 'true' || github.event_name != 'workflow_call' }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check if visual files changed
+        if: github.event_name == 'workflow_call'
+        uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            visual:
+              - 'src/**'
+              - 'docs/**'
+              - 'static/**'
+              - 'docusaurus.config.ts'
+              - 'sidebars.ts'
+              - 'tests/visual-regression/**'
+              - 'playwright.config.ts'
+              - '.github/workflows/visual-regression.yml'
+
+  visual-regression:
+    name: Visual Regression Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    needs: [check-paths]
+    if: needs.check-paths.outputs.should-run == 'true'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up mise
+        uses: jdx/mise-action@v2
+        with:
+          cache: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Restore build cache from CI
+        uses: actions/cache/restore@v4
+        with:
+          path: .build-cache
+          key: build-cache-v2-${{ runner.os }}-${{ inputs.commit-sha || github.event.pull_request.head.sha || github.sha }}
+          restore-keys: |
+            build-cache-v2-${{ runner.os }}-
+
+      - name: Try to download build artifact from CI
+        id: download-artifact
+        if: inputs.commit-sha || github.event.pull_request.head.sha
+        continue-on-error: true
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          workflow: ci.yml
+          name: build
+          path: build/
+          commit: ${{ inputs.commit-sha || github.event.pull_request.head.sha }}
+          search_artifacts: true
+          if_no_artifact_found: warn
+
+      - name: Build the website
+        if: steps.download-artifact.outcome != 'success'
+        run: pnpm build
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Run visual regression tests
+        run: pnpm test:visual
+
+      - name: Upload test results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-test-results
+          path: |
+            playwright-report/
+            test-results/
+          retention-days: 7

.gitignore

@@ -30,3 +30,7 @@ __pycache__/
 
 # Environment variables
 .env
+
+# Playwright
+test-results/
+playwright-report/

package.json

@@ -11,6 +11,8 @@
     "build:legacy": "pnpm run changelog:aggregate && pnpm run generate:rss && docusaurus build",
     "cache:clear": "node scripts/build/cache.mjs clear",
     "cache:stats": "node scripts/build/cache.mjs stats",
+    "cache:prune": "node scripts/build/cache.mjs prune",
+    "cache:size": "node scripts/build/cache.mjs size",
     "cache:validate": "node scripts/build/validate.mjs",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
@@ -31,6 +33,8 @@
     "test": "vitest run",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
+    "test:visual": "playwright test",
+    "test:visual:update": "playwright test --update-snapshots",
     "format:check": "prettier --check .",
     "openapi:regenerate:all": "pnpm run openapi:clean:before:all && pnpm run openapi:transform:all && pnpm run openapi:generate:all && pnpm run openapi:clean:after:all",
     "openapi:regenerate:client": "pnpm run openapi:clean:before:client && pnpm run openapi:transform:client && pnpm run openapi:generate:client && pnpm run openapi:clean:after:client",
@@ -103,24 +107,27 @@
     "zod": "^4.1.11"
   },
   "devDependencies": {
-    "@types/node": "^22.9.0",
-    "@types/nock": "^10.0.2",
     "@docusaurus/faster": "^3.9.2",
     "@docusaurus/module-type-aliases": "^3.9.2",
     "@docusaurus/theme-mermaid": "^3.9.2",
     "@docusaurus/tsconfig": "^3.9.2",
     "@docusaurus/types": "^3.9.2",
+    "@playwright/test": "^1.56.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.8.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
+    "@types/nock": "^10.0.2",
+    "@types/node": "^22.9.0",
     "@types/xml2js": "^0.4.14",
     "@vitejs/plugin-react": "^5.0.4",
     "@vitest/ui": "^3.2.4",
     "chalk": "^5.6.2",
+    "cheerio": "^1.1.2",
     "fast-levenshtein": "^3.0.0",
     "inquirer": "^12.9.6",
     "jsdom": "^26.1.0",
+    "nock": "^14.0.0",
     "npm-run-all": "^4.1.5",
     "open": "^10.1.2",
     "prettier": "^3.6.1",
@@ -130,8 +137,7 @@
     "tsx": "^4.20.6",
     "typescript": "~5.9.2",
     "vitest": "^3.2.4",
-    "xml2js": "^0.6.2",
-    "nock": "^14.0.0"
+    "xml2js": "^0.6.2"
   },
   "browserslist": {
     "production": [

playwright.config.ts

@@ -0,0 +1,46 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/visual-regression',
+
+  fullyParallel: true,
+
+  forbidOnly: !!process.env.CI,
+
+  retries: process.env.CI ? 2 : 0,
+
+  workers: process.env.CI ? 4 : undefined,
+
+  reporter: process.env.CI 
+    ? [
+        ['github'],
+        ['html'],
+        ['list', { printSteps: false }],
+      ]
+    : 'html',
+
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+
+  webServer: {
+    command: 'pnpm serve',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { 
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1280, height: 720 },
+      },
+    },
+  ],
+
+  snapshotPathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
+});
+