@keboola/design 11.6.1 → 12.0.0

package/README.md

@@ -72,12 +72,22 @@ This is the cheap, low-flakiness base layer for testing stories. Screenshot/visu
 
 **How it's wired:**
 
-- `vitest.config.ts` — a separate Vitest config (browser mode, Playwright Chromium provider) so `pnpm test` stays jsdom-only and browser-free; story tests are opt-in via `test:stories`. It is named `vitest.config.ts` (not `vitest.storybook.config.ts`) so the Storybook "Run tests" button (`@storybook/addon-vitest`) can discover it — the addon only scans `vitest.workspace.*` / `vitest.config.*` / `vite.config.*` names; under any other name it falls back to `vite.config.ts` and crashes the dev server (UT-4243). The jsdom `test` script therefore pins `--config vite.config.ts` explicitly.
+- `vitest.config.ts` — a separate Vitest config (browser mode, Playwright provider, one engine per run — see **Browser engines** below) so `pnpm test` stays jsdom-only and browser-free; story tests are opt-in via `test:stories`. It is named `vitest.config.ts` (not `vitest.storybook.config.ts`) so the Storybook "Run tests" button (`@storybook/addon-vitest`) can discover it — the addon only scans `vitest.workspace.*` / `vitest.config.*` / `vite.config.*` names; under any other name it falls back to `vite.config.ts` and crashes the dev server (UT-4243). The jsdom `test` script therefore pins `--config vite.config.ts` explicitly.
 - `.storybook/vitest.setup.ts` — applies the Storybook `preview` annotations (decorators, globals) so tests render exactly like Storybook.
 - `optimizeDeps.entries` crawls every story up front so Vite optimizes all story dependencies in one pass — without it, a heavy dep (mermaid, codemirror, …) discovered mid-run makes Vite re-optimize and 404 in-flight imports.
 
 **Prerequisites:** build the workspace deps once (`pnpm build --filter='@keboola/design^...'`) and install the browser (`pnpm --filter @keboola/design exec playwright install chromium`).
 
+**Browser engines (UT-5647):** a run executes in one engine, named by `STORY_TEST_BROWSER` — `chromium` (the default, and what the Storybook "Run tests" button uses), `firefox` or `webkit`. Any other value fails the run. To reproduce a Firefox or WebKit failure locally, install that engine once and name it:
+
+```bash
+pnpm --filter @keboola/design exec playwright install webkit
+STORY_TEST_BROWSER=webkit pnpm --filter @keboola/design test:stories
+```
+
+- **Per PR:** Chromium is the `story-tests` job that `Storybook story gate` reads. Firefox and WebKit run beside it as `story-tests-cross-browser`, each on its own runner, and are advisory — the gate does not read them, so its flake rate stays a Chromium number. An engine joins the gate once it has a month of its own flake data under the same bar.
+- **Engine-dependent values:** WebKit snaps lengths to 1/64 px, so an exact computed-style string (`12.6px`) can come back as `12.59375px`. Compare lengths numerically with `toBeCloseTo`, not as strings.
+
 **Adding coverage:** nothing to do — every CSF `*.stories.tsx` is picked up automatically. Add a `play()` to a story to turn it into an interaction test. (MDX docs pages — `src/**/*.mdx` — are not executed as tests; the addon only runs CSF stories.)
 
 #### Writing `play()` interaction tests
@@ -120,7 +130,7 @@ Worked examples: `src/components/Button/Button.stories.tsx` (click + disabled),
 
 **Timing-sensitive:** `HoverCard` is the only test driven by a real `userEvent.hover` past a 200 ms open delay (its `findByText` carries a raised timeout). It passes headlessly today, but it's the most likely flake if CI is slow — `Tooltip` deliberately opens via keyboard focus to avoid this. Watch it when wiring CI.
 
-**Runs in CI per-PR (non-blocking).** The `.github/workflows/storybook-component-tests.yml` workflow runs the full suite, wired into `branch.yml` (the `story-tests` job) and gated on the same `detect-affected` design signal as the Storybook deploy — so it only runs when this package (or something it depends on) changes. It is non-blocking: a red run surfaces in the PR Checks tab but doesn't gate the merge. Browser mode isolates per file by default (~35 s/file on a 2-core runner, ~60 min for all 104), so `vitest.config.ts` sets `isolate: false` + `fileParallelism: false` + `maxWorkers: 1` to reuse one browser context across files, and the workflow caches Vite's optimized deps to skip the ~27 s dep pre-bundling on warm runs — bringing the run down to a few minutes. If the suite ever exceeds ~5-6 min, the documented fallback is sharding across a job matrix (and/or full-suite nightly + changed-stories-only on PR). Tracked in UT-4191. Adding `@storybook/addon-a11y` for per-story accessibility checks is a separate follow-up.
+**Runs in CI per-PR and gates the merge (UT-4864).** The `.github/workflows/storybook-component-tests.yml` workflow runs the full suite, wired into `branch.yml` (the `story-tests` job) and gated on the same `detect-affected` design signal as the Storybook deploy — so it only runs when this package (or something it depends on) changes. The required status check is `Storybook story gate`, not the job itself: a reusable-workflow job publishes its check under a different name depending on whether it ran, so the gate job is what reports on every PR (`scripts/storybookStoryGate.mjs`). Browser mode isolates per file by default (~35 s/file on a 2-core runner — over an hour for the current 157 story files), so `vitest.config.ts` sets `isolate: false` + `fileParallelism: false` + `maxWorkers: 1` to reuse one browser context across files, and the workflow caches Vite's optimized deps to skip the ~27 s dep pre-bundling on warm runs — bringing the run down to a few minutes. If the suite ever exceeds ~5-6 min, the documented fallback is sharding across a job matrix (and/or full-suite nightly + changed-stories-only on PR). Measured over 526 executed runs in the week to 2026-09-17: job wall-clock p50 146 s / p90 161 s, of which the test step itself is 61 s — the rest is runner setup, so the suite has room to roughly quadruple before the budget bites. Sharding is not a free lever, though: `isolate: false` makes the run order-dependent, and resharding changes it. Before touching either, prove the suite still passes shuffled (`vitest run --config vitest.config.ts --sequence.shuffle=true`). Adding `@storybook/addon-a11y` for per-story accessibility checks is a separate follow-up.
 
 #### Story-test coverage (UT-4189)