[test] Add a visual regression fixture for the DocSearch modal

test/regressions/AppSearchFixture.tsx

@@ -0,0 +1,64 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import CssBaseline from '@mui/material/CssBaseline';
+import { ThemeProvider } from '@mui/material/styles';
+import { getTheme } from '@mui/internal-core-docs/branding';
+import { UserLanguageProvider } from '@mui/internal-core-docs/i18n';
+import PageContext from '@mui/internal-core-docs/PageContext';
+import { AppSearch } from '@mui/internal-core-docs/AppLayout/components/AppSearch';
+
+// DocSearch ships its own stylesheet, and every release is free to restyle the
+// markup our `AppSearch` overrides target. Two regressions slipped through the
+// v4 -> v5 bump that way, and the v3 -> v4 one broke dark mode, so both schemes
+// are covered. `fixtures/AppSearch/` holds one route per scheme.
+//
+// `index.test.js` drives the rest (see the `AppSearch` block): it seeds the
+// stored recent searches, opens the modal, stubs the search request and
+// declares the `docsearch` layer order. Opening a fixture by hand in
+// `test:regressions:dev` therefore shows the closed button only.
+
+// `AppSearch` reads `productId`/`productCategoryId` off the context, and
+// `PageContext` has no default value.
+const pageContext = {
+  activePage: null,
+  pages: [],
+  productId: 'material-ui',
+  productCategoryId: 'core',
+  productIdentifier: { metadata: '', name: 'Material UI', versions: [] },
+  activePageParents: [],
+} as unknown as React.ContextType<typeof PageContext>;
+
+export default function AppSearchFixture({ mode }: { mode: 'light' | 'dark' }) {
+  return (
+    // The docs theme, so `AppSearch` styles against `theme.vars` and its dark
+    // block keys off `[data-mui-color-scheme="dark"]` exactly as in production.
+    // The storage key is per scheme: the route loop reuses one page, and a mode
+    // persisted by one route would otherwise carry into the other.
+    <ThemeProvider
+      theme={getTheme('ltr')}
+      defaultMode={mode}
+      modeStorageKey={`docsearch-regression-${mode}`}
+      disableTransitionOnChange
+    >
+      {/*
+        `TestViewer` sets `box-sizing: content-box` on purpose, to catch
+        components that rely on the docs' reset. DocSearch is one: it sets
+        `border-box` on the modal subtree, and with the layer order corrected
+        our `content-box` now outranks it and the modal overflows. The docs
+        render `CssBaseline`, so render it here too.
+      */}
+      <CssBaseline />
+      {/* `useUserLanguage` defaults to an empty string, which makes every
+          `t(...)` call fall back to an ellipsis. */}
+      <UserLanguageProvider defaultUserLanguage="en">
+        <PageContext.Provider value={pageContext}>
+          {/* `TestViewer`'s own surface comes from the default theme, so the
+              dark button would otherwise sit on a light background. */}
+          <Box sx={{ bgcolor: 'background.default', p: 1 }}>
+            <AppSearch sx={{ minWidth: { sm: 160 } }} />
+          </Box>
+        </PageContext.Provider>
+      </UserLanguageProvider>
+    </ThemeProvider>
+  );
+}

test/regressions/algoliaSearchStub.js

@@ -0,0 +1,137 @@
+// Canned Algolia response for the `AppSearch/SearchModal*` fixtures.
+//
+// The results screen is where the hit markup lives -- highlighted matches,
+// breadcrumbs, the tree connector between a section and its children -- so it
+// needs hits. Serving them from a stub rather than the live index keeps the
+// screenshots from churning every time the docs are recrawled, and keeps the
+// suite off the network.
+//
+// Shaped like a real `/1/indexes/*/queries` response: `_snippetResult` carries
+// the `<mark>` tags DocSearch renders, `_highlightResult.hierarchy.lvl0` is what
+// it groups the sections by, and `productId`/`productCategoryId` are the extra
+// attributes `AppSearch` requests for its product chip.
+const hit = ({ objectID, type, hierarchy, content = null, snippet, url }) => ({
+  objectID,
+  type,
+  content,
+  url,
+  url_without_anchor: url.split('#')[0],
+  anchor: null,
+  hierarchy: {
+    lvl0: null,
+    lvl1: null,
+    lvl2: null,
+    lvl3: null,
+    lvl4: null,
+    lvl5: null,
+    lvl6: null,
+    ...hierarchy,
+  },
+  productId: 'material-ui',
+  productCategoryId: 'core',
+  _highlightResult: {
+    hierarchy: { lvl0: { value: hierarchy.lvl0, matchLevel: 'none', matchedWords: [] } },
+  },
+  _snippetResult: snippet,
+});
+
+const HITS = [
+  hit({
+    objectID: 'components-card',
+    type: 'lvl1',
+    hierarchy: { lvl0: 'Components', lvl1: 'Card' },
+    snippet: { hierarchy: { lvl1: { value: '<mark>Card</mark>', matchLevel: 'full' } } },
+    url: 'https://mui.com/material-ui/react-card/',
+  }),
+  hit({
+    objectID: 'components-card-basics',
+    type: 'lvl2',
+    hierarchy: { lvl0: 'Components', lvl1: 'Card', lvl2: 'Basic card' },
+    snippet: { hierarchy: { lvl2: { value: 'Basic <mark>card</mark>', matchLevel: 'full' } } },
+    url: 'https://mui.com/material-ui/react-card/#basic-card',
+  }),
+  hit({
+    objectID: 'components-card-media',
+    type: 'lvl2',
+    hierarchy: { lvl0: 'Components', lvl1: 'Card', lvl2: 'Media' },
+    snippet: { hierarchy: { lvl2: { value: 'Media', matchLevel: 'none' } } },
+    url: 'https://mui.com/material-ui/react-card/#media',
+  }),
+  hit({
+    objectID: 'api-card',
+    type: 'lvl1',
+    hierarchy: { lvl0: 'Component API', lvl1: 'Card API' },
+    snippet: { hierarchy: { lvl1: { value: '<mark>Card</mark> API', matchLevel: 'full' } } },
+    url: 'https://mui.com/material-ui/api/card/',
+  }),
+  hit({
+    objectID: 'api-card-props',
+    type: 'content',
+    hierarchy: { lvl0: 'Component API', lvl1: 'Card API' },
+    // Long on purpose. Below 768px DocSearch lets the title and the path wrap
+    // instead of truncating, and a string that fits on one line would render
+    // the same either way, leaving the narrow capture with nothing to catch.
+    content:
+      'The content of the card, which renders inside a Paper surface and accepts any children you pass to it, including a card header, card media and card actions.',
+    snippet: {
+      content: {
+        value:
+          'The content of the <mark>card</mark>, which renders inside a Paper surface and accepts any children you pass to it, including a <mark>card</mark> header, <mark>card</mark> media and <mark>card</mark> actions.',
+        matchLevel: 'full',
+      },
+    },
+    url: 'https://mui.com/material-ui/api/card/#props',
+  }),
+];
+
+const RESPONSE = {
+  results: [
+    {
+      hits: HITS,
+      nbHits: HITS.length,
+      page: 0,
+      nbPages: 1,
+      hitsPerPage: 40,
+      exhaustiveNbHits: true,
+      query: 'card',
+      params: '',
+      index: 'material-ui-regressions',
+      processingTimeMS: 1,
+      queryID: 'regression',
+    },
+  ],
+};
+
+const CORS = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-headers': '*',
+  'access-control-allow-methods': 'GET,POST,OPTIONS',
+};
+
+const isAlgolia = (url) =>
+  url.hostname.endsWith('.algolia.net') || url.hostname.endsWith('.algolianet.com');
+
+/**
+ * Answer the search request the modal fires, so the results screen renders the
+ * same hits on every run.
+ *
+ * @param {import('@playwright/test').Page} page
+ */
+export async function stubAlgoliaSearch(page) {
+  await page.route(isAlgolia, (route) =>
+    route.fulfill(
+      route.request().method() === 'OPTIONS'
+        ? { status: 204, headers: CORS }
+        : {
+            status: 200,
+            headers: { ...CORS, 'content-type': 'application/json' },
+            body: JSON.stringify(RESPONSE),
+          },
+    ),
+  );
+}
+
+/** @param {import('@playwright/test').Page} page */
+export async function unstubAlgoliaSearch(page) {
+  await page.unroute(isAlgolia);
+}

test/regressions/docsearchFixtureData.js

@@ -0,0 +1,59 @@
+// Shared by the `AppSearch/SearchModal*` fixtures, `index.test.js` and
+// `vite.config.mts`, so the index name that keys DocSearch's storage is
+// declared once.
+export const INDEX_NAME = 'material-ui-regressions';
+
+export const recentSearchesKey = `__DOCSEARCH_RECENT_SEARCHES__${INDEX_NAME}`;
+export const favoriteSearchesKey = `__DOCSEARCH_FAVORITE_SEARCHES__${INDEX_NAME}`;
+
+// Shaped like what DocSearch persists: a hit minus `_highlightResult` and
+// `_snippetResult`, plus the `pathname`/`as`/`userLanguage` that `AppSearch`'s
+// `transformItems` adds. Seeding these gives the start screen a hit list
+// without a network round-trip, which is where the section headings and the
+// result cards have to line up.
+export const RECENT_SEARCHES = [
+  {
+    objectID: 'regression-card',
+    content: null,
+    url: 'https://mui.com/material-ui/react-card/',
+    url_without_anchor: 'https://mui.com/material-ui/react-card/',
+    type: 'lvl1',
+    anchor: null,
+    hierarchy: {
+      lvl0: 'Components',
+      lvl1: 'Card',
+      lvl2: null,
+      lvl3: null,
+      lvl4: null,
+      lvl5: null,
+      lvl6: null,
+    },
+    productId: 'material-ui',
+    productCategoryId: 'core',
+    pathname: '/material-ui/react-card/',
+    as: '/material-ui/react-card/',
+    userLanguage: 'en',
+  },
+  {
+    objectID: 'regression-breakpoints',
+    content: null,
+    url: 'https://mui.com/material-ui/customization/breakpoints/',
+    url_without_anchor: 'https://mui.com/material-ui/customization/breakpoints/',
+    type: 'lvl2',
+    anchor: null,
+    hierarchy: {
+      lvl0: 'Customization',
+      lvl1: 'Breakpoints',
+      lvl2: 'Default breakpoints',
+      lvl3: null,
+      lvl4: null,
+      lvl5: null,
+      lvl6: null,
+    },
+    productId: 'material-ui',
+    productCategoryId: 'core',
+    pathname: '/material-ui/customization/breakpoints/',
+    as: '/material-ui/customization/breakpoints/',
+    userLanguage: 'en',
+  },
+];

test/regressions/fixtures/AppSearch/SearchModal.tsx

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import AppSearchFixture from '../../AppSearchFixture';
+
+export default function SearchModal() {
+  return <AppSearchFixture mode="light" />;
+}

test/regressions/fixtures/AppSearch/SearchModalDark.tsx

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import AppSearchFixture from '../../AppSearchFixture';
+
+export default function SearchModalDark() {
+  return <AppSearchFixture mode="dark" />;
+}

test/regressions/index.test.js

@@ -5,6 +5,8 @@ import { chromium } from '@playwright/test';
 import { describe, test as base, afterAll } from 'vitest';
 import { recordA11y, WCAG_TAGS, GLOBAL_DISABLED_RULES } from './a11y/axe';
 import { A11Y_RULES, DEFAULT_VIEWPORT, SCREENSHOT_RULES, getConfig, parseRoute } from './demoMeta';
+import { stubAlgoliaSearch, unstubAlgoliaSearch } from './algoliaSearchStub';
+import { favoriteSearchesKey, recentSearchesKey, RECENT_SEARCHES } from './docsearchFixtureData';
 
 const currentDirectory = url.fileURLToPath(new URL('.', import.meta.url));
 const AXE_SCRIPT = path.resolve(currentDirectory, '../../node_modules/axe-core/axe.min.js');
@@ -300,6 +302,102 @@ async function main() {
       });
     });
 
+    describe.each(['SearchModal', 'SearchModalDark'])('AppSearch/%s', (fixture) => {
+      // The route belongs in the name so the `-t` filter documented in
+      // `AGENTS.md` reaches this test. Without it a scoped run refreshes only
+      // the closed-button capture the route loop generates, and leaves the
+      // three below stale.
+      test(`should render /regression-AppSearch/${fixture} correctly`, async ({ pooled }) => {
+        const { page } = pooled;
+        // Seed from here rather than from the fixture. The `pooled` fixture
+        // clears storage on acquisition, and navigating to a route the pooled
+        // page already rendered does not remount it, so a seed written on mount
+        // would be gone by the time the modal reads it.
+        await page.evaluate(
+          ([key, favoriteKey, hits]) => {
+            localStorage.setItem(key, JSON.stringify(hits));
+            localStorage.setItem(favoriteKey, '[]');
+          },
+          [recentSearchesKey, favoriteSearchesKey, RECENT_SEARCHES],
+        );
+        await renderFixture(page, `/regression-AppSearch/${fixture}`);
+        // The modal portals to `document.body`, so it lands outside the
+        // testcase element and has to be screenshotted on its own.
+        await page.getByRole('button', { name: /search/i }).click();
+        const modal = await page.waitForSelector('.DocSearch-Modal');
+        // `useLazyCSS` fetches the DocSearch stylesheet and injects it as a
+        // `<style data-href>`. Without it the modal is unstyled.
+        await page.waitForFunction(() =>
+          Boolean(document.querySelector('style[data-href*="docsearch"]')),
+        );
+        // Neither of the waits above says anything about the two areas this
+        // screenshot is for. The stylesheet request starts when `AppSearch`
+        // mounts, well before the modal opens, so that wait can already be
+        // satisfied. The stored searches arrive through autocomplete's async
+        // source pipeline, and the custom start screen is portalled in from an
+        // effect. Wait for one sentinel from each.
+        await page.waitForSelector('.DocSearch-Modal .DocSearch-Hit');
+        await page.waitForSelector('.DocSearch-Modal .DocSearch-NewStartScreenItem');
+        // Rank `docsearch` below `mui`, the way the layer order that
+        // `BrandingCssVarsProvider` declares does in the docs. Without it the
+        // DocSearch stylesheet wins and none of the `AppSearch` overrides
+        // apply. It has to happen here rather than in the fixture: a layer's
+        // position is fixed by where it is first named, emotion prepends its
+        // tags above everything in `<head>`, and it keeps doing so as
+        // components mount — so the only stable point is once the modal has
+        // finished rendering.
+        //
+        // It only inserts `docsearch`: `mui` already ranks first here, because
+        // emotion prepends its tags above the bundle stylesheet and outranks the
+        // order `global.css` declares. Every other layer keeps its position.
+        try {
+          await page.evaluate(() => {
+            const style = document.createElement('style');
+            style.id = 'docsearch-layer-order';
+            style.textContent = '@layer docsearch, mui;';
+            document.head.prepend(style);
+          });
+          await takeScreenshot(page, {
+            testcase: modal,
+            route: `/regression-AppSearch/${fixture}Open`,
+          });
+
+          // The results screen carries the markup the start screen never shows:
+          // highlighted matches, breadcrumbs, and the tree connector between a
+          // section and its children.
+          await stubAlgoliaSearch(page);
+          await page.locator('.DocSearch-Input').fill('card');
+          await page.waitForSelector('.DocSearch-Hit mark');
+          await takeScreenshot(page, {
+            testcase: modal,
+            route: `/regression-AppSearch/${fixture}Results`,
+          });
+
+          // Below 768px DocSearch lets the hit title and path wrap. Cropping to
+          // the modal does not reach that rule -- media queries read the
+          // viewport -- so the width has to change. 767px keeps the modal at
+          // the same width our `max-width` override gives it on desktop, which
+          // leaves the typography as the only thing that differs. The `pooled`
+          // fixture resets the viewport on acquisition, so this does not leak.
+          await page.setViewportSize({ width: 767, height: DEFAULT_VIEWPORT.height });
+          await page.waitForFunction(() => window.matchMedia('(max-width: 768px)').matches);
+          await takeScreenshot(page, {
+            testcase: modal,
+            route: `/regression-AppSearch/${fixture}ResultsNarrow`,
+          });
+        } finally {
+          // Pages are pooled and only the viewport and storage are reset between
+          // tests, so undo the rest ourselves. The layer declaration is inert for
+          // fixtures that put nothing in `docsearch`, but leaving it behind makes
+          // their layer order depend on which test ran first.
+          await unstubAlgoliaSearch(page);
+          await page.evaluate(() => {
+            document.getElementById('docsearch-layer-order')?.remove();
+          });
+        }
+      });
+    });
+
     describe('Autocomplete', () => {
       test('should not close immediately when textbox expands', async ({ pooled }) => {
         const { page } = pooled;