feat: add backstop js test

.github/workflows/backstop.yml

@@ -0,0 +1,51 @@
+name: Visual Regression Tests
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  push:
+    branches: [ "main" ]
+
+jobs:
+  backstop:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install Sphinx dependencies
+        run: |
+          pip install -e .[doc]
+
+      - name: Build Sphinx HTML
+        run: xvfb run make -C doc html
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install BackstopJS
+        run: npm install
+
+      - name: Start HTTP server for docs
+        run: npx http-server doc/_build/html -p 8000 &
+
+      - name: Wait for server
+        run: npx wait-on http://localhost:8000
+
+      - name: Run BackstopJS tests
+        run: npx backstop test || true
+
+      - name: Upload Backstop report (if failed)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: backstop-report
+          path: backstop_data/html_report

.gitignore

@@ -167,4 +167,11 @@ doc/source/examples/api/
 # node modules and env
 node_modules/
 .nodeenv/
-package-lock.json
+package-lock.json
+
+# BackstopJS outputs (do not commit)
+backstop_data/bitmaps_test/
+backstop_data/html_report/
+backstop_data/ci_report/
+backstop_data/engine_scripts/cookies.json
+backstop_data/engine_scripts/

backstop.json

@@ -0,0 +1,118 @@
+{
+  "id": "ansys_sphinx_theme_backstop",
+  "viewports": [
+    {
+      "label": "tablet",
+      "width": 1024,
+      "height": 768
+    },
+    {
+      "label": "desktop",
+      "width": 1920,
+      "height": 1080
+    }
+  ],
+  "onBeforeScript": "puppet/onBefore.js",
+  "onReadyScript": "puppet/onReady.js",
+  "scenarios": [
+    {
+      "label": "Ansys Sphinx Theme - Home Page",
+      "cookiePath": "backstop_data/engine_scripts/cookies.json",
+      "url": "https://sphinxdocs.ansys.com/",
+      "referenceUrl": "https://sphinxdocs.ansys.com/",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 20,
+      "hideSelectors": [],
+      "removeSelectors": [],
+      "hoverSelector": "",
+      "clickSelector": "",
+      "postInteractionWait": 0,
+      "selectors": [],
+      "selectorExpansion": true,
+      "expect": 0,
+      "misMatchThreshold" : 0.1,
+      "requireSameDimensions": true
+    },
+    {
+      "label": "Ansys Sphinx Theme - Examples Page-1",
+      "url": "http://localhost:8000/examples/sphinx-design.html",
+      "referenceUrl": "https://sphinxdocs.ansys.com/version/stable/examples/sphinx-design.html",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 20,
+      "misMatchThreshold" : 0.1,
+      "requireSameDimensions": true
+    },
+    {
+      "label": "Ansys Sphinx Theme - Examples Page-2",
+      "url": "http://localhost:8000/examples/api/examples/index.html",
+      "referenceUrl": "https://sphinxdocs.ansys.com/version/stable/examples/api/examples/index.html",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 20,
+      "misMatchThreshold" : 0.1,
+      "requireSameDimensions": true
+    },
+    {
+      "label": "Ansys Sphinx Theme - Examples Page-3",
+      "url": "http://localhost:8000/examples/gallery-examples/sphinx-gallery.html#sphx-glr-examples-gallery-examples-sphinx-gallery-py",
+      "referenceUrl": "https://sphinxdocs.ansys.com/version/stable/examples/gallery-examples/sphinx-gallery.html#sphx-glr-examples-gallery-examples-sphinx-gallery-py",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 20,
+      "misMatchThreshold" : 0.1,
+      "requireSameDimensions": true
+    },
+    {
+      "label": "Ansys Sphinx Theme - Examples Page-4",
+      "url": "http://localhost:8000/examples/nbsphinx/jupyter-notebook.html",
+      "referenceUrl": "https://sphinxdocs.ansys.com/version/stable/examples/nbsphinx/jupyter-notebook.html",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 20,
+      "misMatchThreshold" : 0.1,
+      "requireSameDimensions": true
+    },
+    {
+      "label": "Ansys Sphinx Theme - Examples Page-5",
+      "url": "http://localhost:8000/examples/table.html",
+      "referenceUrl": "https://sphinxdocs.ansys.com/version/stable/examples/table.html",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 20,
+      "misMatchThreshold" : 0.1,
+      "requireSameDimensions": true
+    },
+    {
+      "label": "Ansys Sphinx Theme - Examples Page-6",
+      "url": "http://localhost:8000/examples/admonitions.html",
+      "referenceUrl": "https://sphinxdocs.ansys.com/version/stable/examples/admonitions.html",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 20,
+      "misMatchThreshold" : 0.1,
+      "requireSameDimensions": true
+    }
+  ],
+  "paths": {
+    "bitmaps_reference": "backstop_data/bitmaps_reference",
+    "bitmaps_test": "backstop_data/bitmaps_test",
+    "engine_scripts": "backstop_data/engine_scripts",
+    "html_report": "backstop_data/html_report",
+    "ci_report": "backstop_data/ci_report"
+  },
+  "ci": {
+    "format": "junit",
+    "testReportFileName": "myproject-xunit"
+  },
+  "report": ["browser", "CI"],
+  "engine": "puppeteer",
+  "engineOptions": {
+    "args": ["--no-sandbox"]
+  },
+  "asyncCaptureLimit": 5,
+  "asyncCompareLimit": 50,
+  "debug": false,
+  "debugWindow": false
+}

doc/changelog.d/804.added.md

@@ -0,0 +1 @@
+Add backstop js test

package.json

@@ -8,6 +8,7 @@
     },
     "devDependencies": {
         "autoprefixer": "^10.4.21",
+        "backstopjs": "^6.3.25",
         "postcss": "^8.5.3",
         "postcss-cli": "^11.0.0",
         "postcss-import": "^16.1.0",