QuantEcon
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 31 additions & 29 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 31 additions & 29 deletions
diff --git a/‎.github/workflows/update-snapshots.yml‎
Lines changed: 1 addition & 3 deletions b/‎.github/workflows/update-snapshots.yml‎
Lines changed: 1 addition & 3 deletions
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 2 deletions b/‎.gitignore‎
Lines changed: 3 additions & 2 deletions
diff --git a/‎docs/developer/visual-testing.md‎
Lines changed: 61 additions & 12 deletions b/‎docs/developer/visual-testing.md‎
Lines changed: 61 additions & 12 deletions
diff --git a/‎playwright.config.ts‎
Lines changed: 9 additions & 5 deletions b/‎playwright.config.ts‎
Lines changed: 9 additions & 5 deletions
@@ -1,43 +1,45 @@
-name: Build Example Project [using jupyter-book]
+name: Build Fixtures Site for Visual Regression Tests
 on:
   push:
     branches:
       - main
   pull_request:
+
+# Visual regression tests run against the curated quantecon-book-theme-fixtures
+# site, pinned to a specific commit so the input doesn't move between theme
+# PRs. To bump the pin, update FIXTURES_SHA below.
+env:
+  FIXTURES_REPO: QuantEcon/quantecon-book-theme-fixtures
+  FIXTURES_SHA: d8ffc17c753ecf45fa25c6062827e1aa9de201b3
+
 jobs:
   tests:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - name: Checkout theme
+        uses: actions/checkout@v6
+
+      - name: Checkout fixtures
         uses: actions/checkout@v6
-      - name: Fetch lecture-python-programming
-        shell: bash -l {0}
-        run: |
-          git clone --branch quantecon-book-theme https://github.com/QuantEcon/lecture-python-programming
-      - name: Setup Anaconda
-        uses: conda-incubator/setup-miniconda@v4
         with:
-          auto-update-conda: true
-          auto-activate-base: true
-          miniconda-version: 'latest'
+          repository: ${{ env.FIXTURES_REPO }}
+          ref: ${{ env.FIXTURES_SHA }}
+          path: fixtures
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
           python-version: "3.13"
-          environment-file: lecture-python-programming/environment.yml
-          activate-environment: lecture-python-programming
-      - name: Install quantecon-book-theme
-        shell: bash -l {0}
-        run: |
-          python -m pip install .
-      - name: Display Conda Environment Versions
-        shell: bash -l {0}
-        run: conda list
-      - name: Display Pip Versions
-        shell: bash -l {0}
-        run: pip list
-      - name: Build HTML
-        shell: bash -l {0}
+          cache: "pip"
+
+      - name: Install fixtures build deps + this PR's theme
         run: |
-          cd lecture-python-programming
-          jb build lectures --path-output ./
+          pip install -r fixtures/requirements.txt
+          pip install .
+
+      - name: Build fixtures site
+        working-directory: fixtures
+        run: jb build . --warningiserror
 
       # Visual Regression Testing
       - name: Setup Node.js
@@ -54,7 +56,7 @@ jobs:
         run: npm run test:visual
         continue-on-error: true
         env:
-          SITE_PATH: lecture-python-programming/_build/html
+          SITE_PATH: fixtures/_build/html
       - name: Upload Playwright Report
         uses: actions/upload-artifact@v7
         if: always()
@@ -83,7 +85,7 @@ jobs:
       - name: Preview Deploy to Netlify
         uses: nwtgck/actions-netlify@v3.0
         with:
-          publish-dir: 'lecture-python-programming/_build/html/'
+          publish-dir: 'fixtures/_build/html/'
           production-branch: main
           github-token: ${{ secrets.GITHUB_TOKEN }}
           deploy-message: "Preview Deploy from GitHub Actions"
 
@@ -4,9 +4,7 @@ on:
     types: [created]
 
 # Snapshots are generated against quantecon-book-theme-fixtures at this
-# pinned SHA. ci.yml will be migrated to the same fixtures repo in #390
-# (it still builds lecture-python-programming on main today); once that
-# lands, keep FIXTURES_SHA in sync between the two workflows.
+# pinned SHA. Keep FIXTURES_SHA in sync with .github/workflows/ci.yml.
 env:
   FIXTURES_REPO: QuantEcon/quantecon-book-theme-fixtures
   FIXTURES_SHA: d8ffc17c753ecf45fa25c6062827e1aa9de201b3
 
@@ -144,8 +144,9 @@ node_modules
 playwright-report/
 test-results/
 
-# Visual test lecture site (cloned by tox -e visual)
-lecture-python-programming/
+# Visual test fixtures site (cloned by tox -e visual, or symlinked locally)
+fixtures
+fixtures/
 
 # macOS visual test snapshots (tox uses macos/ dir, CI uses __snapshots__/)
 tests/visual/macos/
@@ -1,8 +1,16 @@
 # Visual Regression Testing
 
-Playwright-based tests capture screenshots of key pages from a real lecture
-site build and compare them against baseline snapshots to detect unintended
-styling changes.
+Playwright-based tests capture screenshots of pages from the
+[`quantecon-book-theme-fixtures`](https://github.com/QuantEcon/quantecon-book-theme-fixtures)
+site and compare them against baseline snapshots to detect unintended
+styling changes. The fixtures repo is a curated, stable rendering target:
+the landing page, 12 synthetic pages (one per theme surface), and
+real-world lecture captures that previously exposed theme bugs.
+
+The fixtures repo is **pinned to a specific commit** in the theme's CI
+workflows (`FIXTURES_SHA` in `.github/workflows/ci.yml` and
+`.github/workflows/update-snapshots.yml`), so the test input doesn't move
+between theme PRs.
 
 ```{contents}
 :local:
@@ -18,10 +26,18 @@ $ tox -e visual
 ```
 
 This will:
-1. Clone `lecture-python-programming` (if not present)
-2. Build the lecture site with Jupyter Book
-3. Install Playwright and Chromium
-4. Run visual regression tests
+1. Clone `quantecon-book-theme-fixtures` (if not present)
+2. Check out the requested ref — defaults to `main`, overridable via the
+   `FIXTURES_REF` env var (accepts SHA, branch, or tag)
+3. Build the fixtures site with `jb build .`
+4. Install Playwright and Chromium
+5. Run visual regression tests against the build
+
+To pin to the same fixtures commit as CI for local testing:
+
+```console
+$ FIXTURES_REF=<sha-from-ci.yml> tox -e visual
+```
 
 ### Updating Local Baselines
 
@@ -30,11 +46,20 @@ $ tox -e visual-update
 ```
 
 Local baselines are stored in `tests/visual/macos/` (gitignored) and are
-separate from CI baselines in `tests/visual/__snapshots__/`.
+separate from CI baselines in `tests/visual/__snapshots__/`, since
+screenshot rendering differs between macOS and Linux.
 
 ## CI Integration
 
-Visual tests run as part of the `ci.yml` workflow on every push and PR.
+Visual tests run as part of the `ci.yml` workflow on every push and PR:
+
+1. Checks out the fixtures repo at `FIXTURES_SHA`
+2. Installs build deps via `pip install -r fixtures/requirements.txt`
+3. Installs the PR's theme via `pip install .`
+4. Builds the fixtures site with `jb build . --warningiserror`
+5. Runs Playwright against the build
+6. Deploys the fixtures site to Netlify as a PR preview (reviewers can
+   click through every fixture page with this PR's theme applied)
 
 ### Updating CI Baselines via PR Comments
 
@@ -46,14 +71,36 @@ Two commands are available as PR comments:
 | `/update-new-snapshots` | Adds only **missing** baselines — use for new tests |
 
 Both commands:
-- Build the lecture site with the PR's theme changes
+- Check out the fixtures repo at `FIXTURES_SHA`
+- Build the fixtures site with the PR's theme applied
 - Run Playwright on Ubuntu for platform-consistent snapshots
 - Commit updated snapshots to the PR branch
 - Post a summary comment on the PR
 
 The `/update-snapshots` command also uploads a `snapshot-update-diff` artifact
 with before/after images for review.
 
+```{note}
+`issue_comment` workflows always load the workflow file from the **default
+branch**, not from the PR branch. If a PR changes `update-snapshots.yml`
+itself, the new workflow takes effect only after that change has been
+merged to `main`.
+```
+
+## Bumping the fixtures pin
+
+To consume new fixtures (e.g. after a real-world capture is added to the
+fixtures repo):
+
+1. Open a PR on
+   [`quantecon-book-theme-fixtures`](https://github.com/QuantEcon/quantecon-book-theme-fixtures)
+   adding the page. See its `real-world/README.md` for capture conventions.
+2. Once merged, open a follow-up PR on this repo that bumps `FIXTURES_SHA`
+   in both workflow files and (if needed) adds a corresponding test entry
+   in `theme.spec.ts`.
+3. Comment `/update-new-snapshots` on that PR to seed baselines for any
+   newly tested pages.
+
 ## Test Structure
 
 ```
@@ -67,5 +114,7 @@ tests/visual/
 ## Configuration
 
 Visual test configuration is in `playwright.config.ts` at the project root.
-The `tox.ini` `[testenv:visual]` section contains the full environment setup
-including dependencies like `jupyter-book`, `sphinx-exercise`, etc.
+The `tox.ini` `[testenv:visual]` and `[testenv:visual-update]` sections
+contain the full environment setup including the fixtures-repo clone +
+checkout dance and dependencies like `jupyter-book`, `sphinx-exercise`,
+etc.
@@ -3,8 +3,11 @@ import { defineConfig, devices } from "@playwright/test";
 /**
  * Playwright configuration for visual regression testing.
  *
- * Tests are run against a locally served build of lecture-python-programming
- * to verify theme styling hasn't regressed.
+ * Tests are run against a locally served build of the
+ * quantecon-book-theme-fixtures site to verify theme styling hasn't
+ * regressed. The fixtures repo is checked out as a sibling directory
+ * (`fixtures/`) by CI; local users can clone it manually or use
+ * `tox -e visual`, which clones it automatically.
  */
 export default defineConfig({
   testDir: "./tests/visual",
@@ -61,10 +64,11 @@ export default defineConfig({
     ? `{testDir}/{testFileDir}/${process.env.SNAPSHOT_DIR}/{projectName}/{arg}{ext}`
     : "{testDir}/{testFileDir}/__snapshots__/{projectName}/{arg}{ext}",
 
-  // Web server to serve the built lecture site
-  // Path varies: CI uses _build/html, tox uses lectures/_build/html
+  // Web server to serve the built fixtures site.
+  // CI sets SITE_PATH=fixtures/_build/html; local default matches the tox
+  // clone path.
   webServer: {
-    command: `python -m http.server 8000 --directory ${process.env.SITE_PATH || "lecture-python-programming/lectures/_build/html"}`,
+    command: `python -m http.server 8000 --directory ${process.env.SITE_PATH || "fixtures/_build/html"}`,
     url: "http://localhost:8000",
     reuseExistingServer: !process.env.CI,
     timeout: 120 * 1000,