@@ -119,23 +119,27 @@ 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:
122+ Screenshots are generated and compared only inside one digest-pinned Playwright
123+ image, locally and in CI, because fonts and Chromium draw slightly differently
124+ on each operating system.
132125
133126``` bash
134- pnpm --filter @clerk/mosaic test:visual:pull < run-id>
127+ pnpm --filter @clerk/mosaic test:visual
128+ pnpm --filter @clerk/mosaic test:visual:update
135129```
136130
137- ` test:visual ` runs the comparison itself. It needs a Linux x64 install of the
138- workspace, so it only runs in CI.
131+ Both commands require Docker. Locally, they mount your checkout into the image
132+ and install Linux dependencies into Docker volumes, so your own ` node_modules `
133+ is untouched and later runs reuse the install. The first command compares
134+ screenshots without changing baselines. The second deletes the Linux baselines,
135+ lets Vitest write every screenshot again, and restores the old ones if the run
136+ fails, so new screenshots are created and ones no test produces are removed.
137+ Review the changed images and commit them under each test's ` __screenshots__/ `
138+ directory. Failed comparisons write actual, expected, and diff images under
139+ ` packages/mosaic/.vitest/attachments/ ` .
140+
141+ Use these package commands for screenshots. Calling Vitest directly bypasses
142+ the pinned image.
139143
140144Add a screenshot only when it covers a distinct layout or visual state that the
141145existing ones miss. Capture the element under test (a dialog, a popup, or the
@@ -150,10 +154,14 @@ fixture data and avatar fallbacks, and wait for content before capturing the
150154page so portaled menus and overlays are included.
151155
152156Baselines include the browser and operating system in their filenames. The
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.
157+ ` Mosaic Visual Tests ` job builds the workspace on the runner, then compares in
158+ the same pinned image. Its comparison is advisory: screenshot differences
159+ appear as a warning and in the job summary without blocking the rest of CI. A
160+ failed build, or a comparison that crashes before writing images, still fails
161+ the job. On a difference, download
162+ ` mosaic-visual-failure-artifacts-<run-id>-<run-attempt> ` from the run and review
163+ the images in ` .vitest/attachments/ ` , then run ` test:visual:update ` locally and
164+ commit the approved baselines.
157165
158166## Feature tests
159167
0 commit comments