[codex] Manage visual regression baselines from CI (#1294)

* test: manage visual regression baselines from CI

Move screenshot tests and tracked baselines under a dedicated visual test tree, split visual test scripts from regular browser tests, and add CI-owned baseline update workflows. Guard local --update runs so screenshot baselines are only refreshed by the manual GitHub Actions workflow.

* test: split visual behavior coverage

Move non-screenshot assertions out of the CI-owned visual test tree so regular Vitest browser runs cover them locally. Keep the visual test tree focused on screenshot assertions while preserving the same behavioral coverage in root test modules.

Author: jderochervlk

.github/workflows/pull-request.yml

@@ -54,3 +54,31 @@ jobs:
         run: yarn build:res
       - name: Vitest
         run: yarn ci:test
+  Visual_Regression:
+    runs-on: ubuntu-latest
+    container:
+      # Keep this image tag aligned with package.json's playwright version.
+      image: mcr.microsoft.com/playwright:v1.59.1-noble
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v6.3.0
+        with:
+          node-version-file: ".node-version"
+          cache: yarn
+      - name: Enable Corepack
+        run: corepack enable
+      - name: Install dependencies
+        run: yarn
+      - name: Build ReScript
+        run: yarn build:res
+      - name: Visual regression tests
+        run: yarn ci:test:visual
+      - name: Upload visual regression artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: visual-regression-artifacts
+          path: |
+            apps/docs/.vitest-attachments

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

@@ -0,0 +1,65 @@
+name: Update Visual Regression Screenshots
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  Update_Visual_Screenshots:
+    runs-on: ubuntu-latest
+    container:
+      # Keep this image tag aligned with package.json's playwright version.
+      image: mcr.microsoft.com/playwright:v1.59.1-noble
+    steps:
+      - name: Refuse default branch
+        if: github.ref_name == github.event.repository.default_branch
+        run: |
+          echo "Visual screenshot baselines must be updated from a feature branch."
+          exit 1
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+        with:
+          ref: ${{ github.ref }}
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v6.3.0
+        with:
+          node-version-file: ".node-version"
+          cache: yarn
+      - name: Enable Corepack
+        run: corepack enable
+      - name: Install dependencies
+        run: yarn
+      - name: Build ReScript
+        run: yarn build:res
+      - name: Update visual screenshot baselines
+        run: yarn workspace @rescript-lang/docs ci:test:visual:update
+      - name: Commit changed baselines
+        id: commit-baselines
+        run: |
+          git add apps/docs/__tests__/visual/__screenshots__
+
+          if git diff --cached --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "No visual screenshot baseline changes were produced." >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git commit \
+            -m "test: update visual regression screenshots" \
+            -m "Updated from the GitHub Actions visual baseline workflow."
+
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+      - name: Push changed baselines
+        if: steps.commit-baselines.outputs.changed == 'true'
+        run: git push origin HEAD:${{ github.ref_name }}
+      - name: Summarize changed baselines
+        if: steps.commit-baselines.outputs.changed == 'true'
+        run: |
+          echo "## Visual screenshot baseline changes" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          git diff --name-only HEAD~1 HEAD -- apps/docs/__tests__/visual/__screenshots__ \
+            | sed 's/^/- /' >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -105,7 +105,7 @@ apps/docs/.env.local
 .worktrees
 
 # Vitest screenshots
-!apps/docs/__tests__/__screenshots__/**/*
+!apps/docs/__tests__/**/__screenshots__/**/*
 .vitest-attachments
 apps/docs/.vitest-attachments
 apps/guide/.vitest-attachments

apps/docs/__tests__/BlogArticleBehavior_.test.res

@@ -0,0 +1,47 @@
+open ReactRouter
+open Vitest
+
+@get external textContent: WebAPI.DOMAPI.element => string = "textContent"
+
+let mockAuthor: BlogFrontmatter.author = {
+  username: "test-author",
+  fullname: "Test Author",
+  role: "Developer",
+  imgUrl: "https://rescript-lang.org/brand/rescript-brandmark.svg",
+  social: X("testauthor"),
+}
+
+let mockFrontmatter: BlogFrontmatter.t = {
+  author: mockAuthor,
+  co_authors: [],
+  date: DateStr.fromString("2025-01-15"),
+  previewImg: Nullable.null,
+  articleImg: Nullable.null,
+  title: "Test Blog Post Title",
+  badge: Nullable.null,
+  description: Nullable.Value("A short description of the blog post for testing."),
+}
+
+test("blog article marks body content for DocSearch crawling", async () => {
+  await viewport(1440, 900)
+
+  let _screen = await render(
+    <BrowserRouter>
+      <BlogArticle frontmatter=mockFrontmatter isArchived=false path="/blog/test-article">
+        <p> {React.string("This is the blog post body content for testing.")} </p>
+      </BlogArticle>
+    </BrowserRouter>,
+  )
+
+  switch document->WebAPI.Document.querySelector("article.DocSearch-content") {
+  | Value(_) => ()
+  | Null => failwith("expected blog article body to be marked as DocSearch content")
+  }
+
+  let lvl0 = switch document->WebAPI.Document.querySelector("article .DocSearch-lvl0") {
+  | Value(element) => element
+  | Null => failwith("expected blog article to render a DocSearch lvl0 marker")
+  }
+
+  expect(lvl0->textContent)->toBe("Blog")
+})

apps/docs/__tests__/BreadcrumbsBehavior_.test.res

@@ -0,0 +1,30 @@
+open ReactRouter
+open Vitest
+
+@get external textContent: WebAPI.DOMAPI.element => string = "textContent"
+
+test("breadcrumbs do not repeat the current page crumb when it is already included", async () => {
+  await viewport(1440, 900)
+
+  let apiBreadcrumbs: list<Url.breadcrumb> = list{
+    {Url.name: "Docs", href: "/docs/manual/api"},
+    {Url.name: "API", href: "/docs/manual/api"},
+    {Url.name: "Stdlib", href: "/docs/manual/api/stdlib"},
+  }
+
+  let screen = await render(
+    <MemoryRouter initialEntries=["/docs/manual/api/stdlib"]>
+      <div dataTestId="breadcrumbs-wrapper">
+        <Breadcrumbs crumbs=apiBreadcrumbs />
+      </div>
+    </MemoryRouter>,
+  )
+
+  let _breadcrumbs = await screen->getByTestId("breadcrumbs")
+  let breadcrumbs = switch document->WebAPI.Document.querySelector("[data-testid='breadcrumbs']") {
+  | Value(breadcrumbs) => breadcrumbs
+  | Null => failwith("expected breadcrumbs")
+  }
+
+  expect(breadcrumbs->textContent)->toBe("Docs / API / Stdlib")
+})

apps/docs/__tests__/ButtonBehavior_.test.res

@@ -0,0 +1,18 @@
+open Vitest
+
+test("calls onClick when clicked", async () => {
+  await viewport(1440, 500)
+
+  let handleClick = fn()
+
+  let screen = await render(
+    <div dataTestId="button-wrapper">
+      <Button onClick=handleClick> {React.string("Clickable")} </Button>
+    </div>,
+  )
+
+  let btn = await screen->getByText("Clickable")
+  await btn->click
+
+  expect(handleClick)->toHaveBeenCalled
+})

apps/docs/__tests__/DocsLayoutBehavior_.test.res

@@ -0,0 +1,66 @@
+open ReactRouter
+open Vitest
+
+@get external textContent: WebAPI.DOMAPI.element => string = "textContent"
+
+let mockCategories: array<SidebarNav.Category.t> = [
+  {
+    name: "Overview",
+    items: [
+      {name: "Introduction", href: "/docs/manual/introduction"},
+      {name: "Installation", href: "/docs/manual/installation"},
+    ],
+  },
+  {
+    name: "Language Features",
+    items: [
+      {name: "Primitive Types", href: "/docs/manual/primitive-types"},
+      {name: "Record", href: "/docs/manual/record"},
+      {name: "Object", href: "/docs/manual/object"},
+    ],
+  },
+]
+
+let mockToc: TableOfContents.t = {
+  title: "Introduction",
+  entries: [
+    {header: "What is ReScript", href: "#what-is-rescript"},
+    {header: "Prerequisites", href: "#prerequisites"},
+    {header: "Getting Started", href: "#getting-started"},
+  ],
+}
+
+test("docs layout marks the textual content for DocSearch crawling", async () => {
+  await viewport(1440, 900)
+
+  let screen = await render(
+    <MemoryRouter initialEntries=["/docs/manual/introduction"]>
+      <DocsLayout categories=mockCategories activeToc=mockToc docSearchLvl0="Manual">
+        <div> {React.string("This is the documentation content.")} </div>
+      </DocsLayout>
+    </MemoryRouter>,
+  )
+
+  let _mainContent = await screen->getByTestId("side-layout-children")
+
+  let mainContent = switch document->WebAPI.Document.querySelector(
+    "[data-testid='side-layout-children']",
+  ) {
+  | Value(element) => element
+  | Null => failwith("expected docs layout main content")
+  }
+
+  let className = switch mainContent->WebAPI.Element.getAttribute("class") {
+  | Value(value) => value
+  | Null => ""
+  }
+
+  expect(className->String.includes("DocSearch-content"))->toBe(true)
+
+  let lvl0 = switch document->WebAPI.Document.querySelector(".DocSearch-lvl0") {
+  | Value(element) => element
+  | Null => failwith("expected docs layout to render a DocSearch lvl0 marker")
+  }
+
+  expect(lvl0->textContent)->toBe("Manual")
+})

apps/docs/__tests__/DocsOverviewBehavior_.test.res

@@ -0,0 +1,35 @@
+open ReactRouter
+open Vitest
+
+test("docs overview uses unversioned docs links", async () => {
+  await viewport(1440, 900)
+
+  let _screen = await render(
+    <MemoryRouter initialEntries=["/docs"]>
+      <div dataTestId="docs-overview-wrapper">
+        <DocsOverview.default />
+      </div>
+    </MemoryRouter>,
+  )
+
+  let overviewLink = switch document->WebAPI.Document.querySelector(
+    "a[href='/docs/manual/introduction']",
+  ) {
+  | Value(link) => link
+  | Null => failwith("expected docs overview to link to the unversioned manual introduction")
+  }
+  await element(overviewLink)->toBeVisible
+
+  let genTypeLink = switch document->WebAPI.Document.querySelector(
+    "a[href='/docs/manual/typescript-integration']",
+  ) {
+  | Value(link) => link
+  | Null => failwith("expected docs overview to link to the unversioned GenType docs page")
+  }
+  await element(genTypeLink)->toBeVisible
+
+  switch document->WebAPI.Document.querySelector("a[href*='/docs/manual/v']") {
+  | Value(_) => failwith("expected docs overview to avoid versioned manual links")
+  | Null => ()
+  }
+})