@@ -119,26 +119,29 @@ The `visual` project runs `*.visual.test.tsx` in Chromium, using the feature
119119project's Clerk and MSW setup. Tests and their fixtures live in Mosaic, beside
120120the feature they cover. They do not import Swingset stories or fixtures.
121121
122+ Baselines come from CI, not from your machine. Fonts and Chromium draw slightly
123+ differently on each operating system, so every baseline is captured in one
124+ digest-pinned Playwright image. The ` Mosaic Visual Tests ` job builds the
125+ workspace on the runner, then runs the ` visual ` project inside that image.
126+
127+ To add or change a baseline, push the change and wait for the job. When
128+ screenshots differ, it uploads
129+ ` mosaic-visual-failure-artifacts-<run-id>-<run-attempt> ` with actual, expected,
130+ and diff images under ` .vitest/attachments/ ` . Review them, then copy the actual
131+ images into place and commit them:
132+
122133``` bash
123- pnpm --filter @clerk/mosaic test:visual
124- pnpm --filter @clerk/mosaic test:visual:update
134+ pnpm --filter @clerk/mosaic test:visual:pull < run-id>
125135```
126136
127- Both commands build and run the same pinned Linux image that CI uses, so they
128- require Docker. Dependencies are cached in an image layer keyed on the lockfile,
129- so a rerun after a source change only rebuilds the packages. The first command compares
130- screenshots without changing baselines. The second replaces Linux baselines and deletes ones no test produced.
131- Review the images and commit the expected baselines under each test's
132- ` __screenshots__/ ` directory.
133- Failed comparisons write actual, expected, and diff images under
134- ` packages/mosaic/.vitest/attachments/ ` .
135-
136- Use these package commands for screenshots. Calling Vitest directly bypasses
137- the pinned image and the command's explicit snapshot update policy.
137+ ` test:visual ` runs the comparison itself. It needs a Linux x64 install of the
138+ workspace, so it only runs in CI.
138139
139140Add a screenshot only when it covers a distinct layout or visual state that the
140- existing ones miss. Capture the dialog or popup locator, not ` page ` , so page
141- padding and unrelated content stay out of the baseline.
141+ existing ones miss. Capture the element under test (a dialog, a popup, or the
142+ rendered container), not ` page ` , so page padding and unrelated content stay out
143+ of the baseline. Content taller than the viewport is cut off, so resize the
144+ viewport to the content's height first, as the user profile tests do.
142145
143146The suite fixes the viewport before each test, the bundled Inter font, color
144147scheme, locale, time zone, and device scale, and compares with zero mismatched
@@ -147,16 +150,10 @@ fixture data and avatar fallbacks, and wait for content before capturing the
147150page so portaled menus and overlays are included.
148151
149152Baselines include the browser and operating system in their filenames. The
150- ` Mosaic Visual Tests ` job compares screenshots on the same pinned Linux image
151- as the local commands. Its comparison is advisory, so visual differences do
152- not block the rest of CI; they appear as a warning and in the job summary. On a
153- failed comparison, download
154- ` mosaic-visual-failure-artifacts-<run-id>-<run-attempt> ` from the GitHub Actions
155- run and review the images in ` .vitest/attachments/ ` .
156-
157- Review the actual, expected, and diff images, then run
158- ` pnpm --filter @clerk/mosaic test:visual:update ` and commit the approved
159- baselines. Rerun the CI job at the same commit to verify the result.
153+ job's comparison is advisory: screenshot differences appear as a warning and in
154+ the job summary without blocking the rest of CI. A failed build or a comparison
155+ that crashes before producing images still fails the job. Rerun the job after
156+ pulling baselines to confirm it reports no differences.
160157
161158## Feature tests
162159
0 commit comments