feat: add Playwright for visual regression testing (#1440)

* feat: add Playwright for visual regression testing

* feat: update snapshot path template in Playwright configuration

* chore: change CI workflow to run on macOS and remove unused snapshot path template

* update snapshots

* feat: update visual regression tests to use toHaveScreenshot method

* feat: update screenshot expectation to use maxDiffPixelRatio

* feat: remove threshold from screenshot expectation for homepage test

* feat: add visual regression tests for multiple pages

* feat: update Playwright configuration and enhance visual regression tests

* feat: add Hugo setup to Playwright workflow

* feat: update Playwright workflow to install Hugo via Homebrew

* feat: update visual test pages by commenting out unused entries

.github/workflows/playwright.yml

@@ -0,0 +1,40 @@
+name: Visual Regression Testing with Playwright
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: macos-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: lts/*
+
+    - name: Set up Homebrew
+      uses: Homebrew/actions/setup-homebrew@master
+
+    - name: Hugo setup
+      run: brew install hugo
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Install Playwright Browsers
+      run: npx playwright install --with-deps
+
+    - name: Run Playwright tests
+      run: npx playwright test
+
+    - uses: actions/upload-artifact@v4
+      if: ${{ !cancelled() }}
+      with:
+        name: playwright-report
+        path: playwright-report/
+        retention-days: 30

.gitignore

@@ -22,3 +22,9 @@ $RECYCLE.BIN/
 # Hugo
 .hugo_build.lock
 jsconfig.json
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

package-lock.json

@@ -12,6 +12,8 @@
         "atomic-algolia": "^0.3.19"
       },
       "devDependencies": {
+        "@playwright/test": "^1.50.1",
+        "@types/node": "^22.13.4",
         "concurrently": "^9.1.2",
         "tailwindcss": "^3.4.17"
       }
@@ -1840,6 +1842,32 @@
         "node": ">=14"
       }
     },
+    "node_modules/@playwright/test": {
+      "version": "1.50.1",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.50.1.tgz",
+      "integrity": "sha512-Jii3aBg+CEDpgnuDxEp/h7BimHcUTDlpEtce89xEumlJ5ef2hqepZ+PWp1DDpYC/VO9fmWVI1IlEaoI5fK9FXQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.50.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "22.13.4",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.13.4.tgz",
+      "integrity": "sha512-ywP2X0DYtX3y08eFVx5fNIw7/uIv8hYUKgXoK8oayJlLnKcRfEYCxWMVE1XagUdVtCJlZT1AU4LXEABW+L1Peg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.20.0"
+      }
+    },
     "node_modules/agentkeepalive": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/agentkeepalive/-/agentkeepalive-2.2.0.tgz",
@@ -3140,6 +3168,38 @@
         "node": ">= 6"
       }
     },
+    "node_modules/playwright": {
+      "version": "1.50.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.50.1.tgz",
+      "integrity": "sha512-G8rwsOQJ63XG6BbKj2w5rHeavFjy5zynBA9zsJMMtBoe/Uf757oG12NXz6e6OirF7RCrTVAKFXbLmn1RbL7Qaw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.50.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.50.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.50.1.tgz",
+      "integrity": "sha512-ra9fsNWayuYumt+NiM069M6OkcRb1FZSK8bgi66AtpFoWkg2+y0bJSNmkFrWhMbEBbVKC/EruAHH3g0zmtwGmQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/postcss": {
       "version": "8.4.49",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.49.tgz",
@@ -3799,6 +3859,13 @@
         "node": "*"
       }
     },
+    "node_modules/undici-types": {
+      "version": "6.20.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.20.0.tgz",
+      "integrity": "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/unicode-canonical-property-names-ecmascript": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/unicode-canonical-property-names-ecmascript/-/unicode-canonical-property-names-ecmascript-2.0.0.tgz",

package.json

@@ -30,6 +30,8 @@
   },
   "homepage": "https://github.com/HEIGE-PCloud/DoIt#readme",
   "devDependencies": {
+    "@playwright/test": "^1.50.1",
+    "@types/node": "^22.13.4",
     "concurrently": "^9.1.2",
     "tailwindcss": "^3.4.17"
   },

playwright.config.ts

@@ -0,0 +1,88 @@
+import { defineConfig, devices } from "@playwright/test";
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: "./tests",
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: "100%",
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: "html",
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    // baseURL: 'http://127.0.0.1:3000',
+    headless: true,
+    viewport: { width: 1280, height: 720 },
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: "on-first-retry",
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    },
+
+    /* Test against mobile viewports. */
+    {
+      name: "Mobile Chrome",
+      use: { ...devices["Pixel 5"] },
+    },
+    {
+      name: "Mobile Safari",
+      use: { ...devices["iPhone 12"] },
+    },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  webServer: {
+    command:
+      "hugo server --source=exampleSite --themesDir ../.. -D --disableFastRender --noHTTPCache --disableLiveReload --disableBrowserError --baseURL=http://127.0.0.1:1313",
+    url: "http://127.0.0.1:1313",
+    reuseExistingServer: !process.env.CI,
+  },
+
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.02,
+    },
+  },
+});

tests/visual.spec.ts

@@ -0,0 +1,47 @@
+import { test, expect } from "@playwright/test";
+
+const pages = [
+  "",
+  // "posts",
+  "tags",
+  "categories",
+  "series",
+  "authors",
+  "showcase",
+  "about",
+  "aplayer-tests",
+  "extend-shortcodes-tests",
+  "person-tests",
+  "author-fallback-tests",
+  "friend-link-tests",
+  "related-tests",
+  "author-single-tests",
+  "image-tests",
+  "series-taxonomy-tests",
+  // "bilibili-tests",
+  // "katex-tests",
+  "showcase-tests",
+  "bluesky-tests",
+  // "mapbox-tests",
+  "tab-tests",
+  // "builtin-shortcodes-tests",
+  "markdown-tests",
+  "toc-tests",
+  "codeblock-tests",
+  // "mermaid-tests",
+  "typeit-tests",
+  "echarts-tests",
+  // "music-tests",
+];
+
+pages.forEach((path) => {
+  test(`Visual regression for /${path}`, async ({ page }) => {
+    await page.goto(`http://127.0.0.1:1313/${path}`, {
+      waitUntil: "networkidle",
+    });
+
+    await expect(page).toHaveScreenshot({
+      fullPage: true,
+    });
+  });
+});