diff --git a/.github/workflows/refresh-docs.yml b/.github/workflows/refresh-docs.yml index 65019b3..22250fb 100644 --- a/.github/workflows/refresh-docs.yml +++ b/.github/workflows/refresh-docs.yml @@ -105,7 +105,7 @@ jobs: run: scripts/check-built-site.sh - name: Install the browser test runtime if: steps.content.outputs.publish == 'yes' - run: npx playwright install --with-deps chromium + run: npx playwright install --with-deps chromium firefox - name: Check browser interactions if: steps.content.outputs.publish == 'yes' run: npm run test:browser diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index d296e4c..30c1b3b 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -61,7 +61,7 @@ jobs: run: scripts/check-built-site.sh - name: Install the browser test runtime if: matrix.node == '24' - run: npx playwright install --with-deps chromium + run: npx playwright install --with-deps chromium firefox - name: Check browser interactions if: matrix.node == '24' run: npm run test:browser diff --git a/README.md b/README.md index bdaa866..bf97099 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,14 @@ just verify vinext 1.0.1 includes `@vercel/og` 1.0.3 with the Satori SVG-escaping fix and the framework's HarfBuzz runtime support. The `satori` override pins `fflate` 0.7.5 to fix its ZIP64 parsing advisory while Satori pins 0.7.3; remove that override once Satori uses a patched release. The lockfile also keeps `@hono/node-server` and `systeminformation` on patched versions within their existing dependency ranges. -The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. Pull requests stacked on `fix/website-*` branches also run these checks. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks raw-head metadata and share cards, checks that each labelled control's name contains its visible text, and verifies not-found responses and redirects. On Node 24, CI also runs the Playwright Chromium suite (`npm run test:browser`) against the built Worker. It covers journey selection, game completion, search loading and recovery, route announcements, code copying, keyboard-operated comparison controls, catalogue toggles, mobile Escape handling, narrow layouts, and the reported catalogue and retro contrast regressions. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests. These checks do not replace testing with screen readers or native browser zoom. +The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. Pull requests stacked on `fix/website-*` branches also run these checks. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks raw-head metadata and share cards, checks that each labelled control's name contains its visible text, and verifies not-found responses and redirects. On Node 24, CI also runs the Playwright Chromium and Firefox suite (`npm run test:browser`) against the built Worker. It covers journey selection, game completion, search loading and recovery, route announcements, code copying, keyboard-operated comparison controls, catalogue toggles, mobile Escape handling, sidebar search sizing and scrolling, narrow layouts, and the reported catalogue and retro contrast regressions. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium firefox`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests. These checks do not replace testing with screen readers or native browser zoom. + +To run only Firefox, use `npm run test:browser -- --project=firefox`. If the bundled Firefox fails to start on macOS 27 with “Could not find profile folder”, give the test browser separate application data directories ([upstream issue](https://github.com/microsoft/playwright/issues/42768)): + +```sh +mkdir -p work/firefox-app-data work/firefox-local-app-data +MOZ_APP_DATA="$PWD/work/firefox-app-data" MOZ_LOCAL_APP_DATA="$PWD/work/firefox-local-app-data" npm run test:browser +``` ## Documentation source diff --git a/app/components/docs-navigation.tsx b/app/components/docs-navigation.tsx index bf983c0..d8bae51 100644 --- a/app/components/docs-navigation.tsx +++ b/app/components/docs-navigation.tsx @@ -78,7 +78,7 @@ function DocsNavigation({ { setQuery(e.target.value); loadSearch(); }} diff --git a/app/globals.css b/app/globals.css index f624d04..007b0c4 100644 --- a/app/globals.css +++ b/app/globals.css @@ -1639,16 +1639,19 @@ html { } .guide-sidebar[data-slot='sidebar'] { width: auto; + min-width: 0; height: auto; - padding: 0 21px; + padding: 0; } .desktop-docs-nav { position: sticky; top: 90px; max-height: calc(100vh - 90px); overflow: auto; - padding: 25px 0; + /* Keep the scrollbar at the panel edge and inset content inside it. */ + padding: 0 21px 25px; scrollbar-width: thin; + scrollbar-gutter: stable; /* Keeps a focused link clear of the sticky search above it. */ scroll-padding-top: 112px; } @@ -1659,6 +1662,10 @@ html { padding-bottom: 4px; background: #f6f8fc; } +.desktop-docs-nav .guide-search { + /* The top inset stays opaque when the navigation scrolls underneath. */ + padding-top: 25px; +} .guide-search-field [data-slot='input'] { min-width: 0; font-size: 0.875rem; diff --git a/justfile b/justfile index cebfdab..04e47ac 100644 --- a/justfile +++ b/justfile @@ -65,7 +65,7 @@ build: _installed npm run build @echo "▸ Built. Config at {{wrangler_config}}" -# Install Chromium once with `npx playwright install chromium`. +# Install browsers once with `npx playwright install chromium firefox`. [doc("Run browser interaction checks against the built Worker")] browser: _built npm run test:browser diff --git a/playwright.config.ts b/playwright.config.ts index 50c908e..66aa926 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -10,7 +10,10 @@ export default defineConfig({ baseURL: 'http://127.0.0.1:4320', trace: 'retain-on-failure', }, - projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }], + projects: [ + { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, + { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, + ], webServer: { command: 'npm start -- --ip 127.0.0.1 --port 4320 --log-level error', url: 'http://127.0.0.1:4320', diff --git a/tests/browser/docs-sidebar.spec.ts b/tests/browser/docs-sidebar.spec.ts new file mode 100644 index 0000000..2a609e1 --- /dev/null +++ b/tests/browser/docs-sidebar.spec.ts @@ -0,0 +1,87 @@ +import { test, expect } from '@playwright/test'; + +test.beforeEach(async ({ context, page }) => { + await context.route('**/*', (route) => + new URL(route.request().url()).hostname === '127.0.0.1' + ? route.continue() + : route.abort(), + ); + await page.emulateMedia({ reducedMotion: 'reduce' }); +}); + +for (const width of [761, 1150, 1151, 1920]) { + test(`desktop docs search fits the sidebar and stays inset when scrolling at ${width}px`, async ({ + page, + }) => { + await page.setViewportSize({ width, height: 900 }); + await page.goto('/docs/watch'); + const sidebar = page.getByRole('complementary', { + name: 'Documentation navigation', + }); + const scrollArea = sidebar.locator('.desktop-docs-nav'); + const search = sidebar.getByRole('textbox', { + name: 'Search documentation', + }); + await expect(search).toBeVisible(); + + const placeholder = await search.evaluate((input: HTMLInputElement) => { + const style = getComputedStyle(input); + const context = document.createElement('canvas').getContext('2d')!; + context.font = `${style.fontWeight} ${style.fontSize} ${style.fontFamily}`; + return { + textWidth: context.measureText(input.placeholder).width, + availableWidth: + input.clientWidth - + parseFloat(style.paddingLeft) - + parseFloat(style.paddingRight), + }; + }); + expect( + placeholder.textWidth, + 'the entire placeholder is readable', + ).toBeLessThanOrEqual(placeholder.availableWidth); + + const sidebarBox = (await sidebar.boundingBox())!; + const scrollBox = (await scrollArea.boundingBox())!; + const field = scrollArea.locator('.guide-search-field'); + const fieldBox = (await field.boundingBox())!; + // The scroll track belongs at the panel edge, with padding inside it. + expect(scrollBox.x).toBeCloseTo(sidebarBox.x, 0); + expect( + sidebarBox.x + sidebarBox.width - scrollBox.x - scrollBox.width, + ).toBeLessThanOrEqual(1); + expect(fieldBox.x - sidebarBox.x).toBeGreaterThanOrEqual(16); + expect( + sidebarBox.x + sidebarBox.width - fieldBox.x - fieldBox.width, + ).toBeGreaterThanOrEqual(16); + expect( + await scrollArea.evaluate( + (element) => element.scrollWidth - element.clientWidth, + ), + ).toBe(0); + + await scrollArea.evaluate((element) => { + element.scrollTop = 400; + }); + expect( + await scrollArea.evaluate((element) => element.scrollTop), + ).toBeGreaterThan(0); + await expect(search).toBeInViewport({ ratio: 1 }); + const scrolledFieldBox = (await field.boundingBox())!; + expect( + scrolledFieldBox.y, + 'search keeps its top inset while links scroll', + ).toBeCloseTo(fieldBox.y, 0); + + await search.fill('rollback'); + await expect(sidebar.locator('.docs-search-result').first()).toBeVisible(); + const clear = sidebar.getByRole('button', { name: 'Clear search' }); + await expect(clear).toBeInViewport({ ratio: 1 }); + await clear.click(); + await expect(search).toBeEmpty(); + await expect(search).toBeFocused(); + expect( + await page.evaluate(() => document.documentElement.scrollWidth), + ).toBeLessThanOrEqual(width); + }); +} diff --git a/tests/browser/site.spec.ts b/tests/browser/site.spec.ts index 4c6cc16..63cf0a7 100644 --- a/tests/browser/site.spec.ts +++ b/tests/browser/site.spec.ts @@ -106,8 +106,10 @@ test('client-side documentation navigation announces the new page title', async test('code copying writes the actual example to the clipboard', async ({ page, context, + browserName, }) => { - await context.grantPermissions(['clipboard-read', 'clipboard-write']); + if (browserName === 'chromium') + await context.grantPermissions(['clipboard-read', 'clipboard-write']); await page.goto('/docs/watch'); const block = page.locator('.doc-code').first(); const code = await block.locator('code').innerText(); @@ -122,7 +124,16 @@ test('code copying writes the actual example to the clipboard', async ({ 'aria-label', 'Copied code example 1', ); - expect(await page.evaluate(() => navigator.clipboard.readText())).toBe(code); + if (browserName === 'chromium') { + expect(await page.evaluate(() => navigator.clipboard.readText())).toBe(code); + } else { + // Firefox does not expose clipboard permissions to Playwright. Paste + // through a user gesture to verify the real clipboard without a mock. + const search = page.getByRole('textbox', { name: 'Search documentation' }); + await search.focus(); + await search.press('ControlOrMeta+V'); + await expect(search).toHaveValue(code.replace(/[\r\n]/g, '')); + } }); test('mobile Escape clears search, then closes the menu, then exits retro mode', async ({