test(mosaic): add screenshot testing POC by austincalvelage · Pull Request #10451 · clerk/javascript

austincalvelage · 2026-10-27T05:16:59Z

Description

Token changes can alter text, borders, and layout without failing behavior tests. This adds six Mosaic screenshot tests. They cover both open switchers, the user profile Account page in light, dark, and narrow layouts, and an edit-name form showing a banner and a field error. The profile tests render the real <UserProfile /> against the fake FAPI, so a change to the profile's sections or pages shows up in the screenshots.

Screenshots are generated and compared only inside the digest-pinned Playwright 1.62.1 image, locally and in CI. pnpm --filter @clerk/mosaic test:visual compares, and test:visual:update regenerates every Linux baseline with Vitest's update mode, so new screenshots are created and unused ones removed. Locally, both mount the checkout into the image and install Linux dependencies into Docker volumes, leaving the host node_modules untouched. In CI, the Mosaic Visual Tests job builds on the runner with the turbo remote cache and only runs Vitest in the image. The suite bundles Inter, disables CSS motion, hides carets, checks the narrow profile for horizontal overflow, and compares with zero color tolerance and zero mismatched pixels.

The comparison is advisory and not a required check. Screenshot differences warn and upload actual, expected, and diff images for seven days. A failed build, or a comparison that crashes before writing images, fails the job.

A token change the suite catches

Dimming dark-mode secondary text from neutralMix(50, 64.25) to neutralMix(50, 40) fails only the dark profile screenshot. The comparison also catches the change to 62, which is too small to see.

Baseline	With the token change

Checklist

pnpm test runs as expected for Mosaic.
pnpm build runs as expected for Mosaic and its dependencies.
All six screenshot comparisons pass locally and in CI.
Scoped lint and formatting pass.
Screenshot differences upload diff images without failing the advisory visual job.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

🤖 Generated with Claude Code

changeset-bot · 2026-10-27T05:17:03Z

🦋 Changeset detected

Latest commit: df33288

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-10-27T05:17:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Nov 3, 2026 12:03am UTC
swingset	Ready	Preview	Nov 3, 2026 12:03am UTC

coderabbitai · 2026-10-27T05:17:07Z

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Files ignored due to path filters: 7

packages/mosaic/src/features/organization-switcher/__tests__/__screenshots__/organization-switcher.visual.test.tsx/organization-switcher-open-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-button/__tests__/__screenshots__/user-button.visual.test.tsx/user-button-combined-open-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-desktop-dark-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-desktop-light-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-narrow-light-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-edit-name-error-chromium-linux.png is excluded by !**/*.png
packages/mosaic/test/public/fonts/InterVariable.woff2 is excluded by !**/*.woff2

Run configuration

Source mode: Auto
Repository: clerk/javascript
Branch: austin/snapshot-test-poc
File: .coderabbit.yaml
Commit: df33288
Layers: Repository YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Team
Run ID: 01c01d07-fbae-4dad-8c64-917b5ffaedd2

Commits

Reviewing files that changed from the base of the PR and between 752d3bf and df33288.

Files ignored due to path filters: 7

packages/mosaic/src/features/organization-switcher/__tests__/__screenshots__/organization-switcher.visual.test.tsx/organization-switcher-open-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-button/__tests__/__screenshots__/user-button.visual.test.tsx/user-button-combined-open-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-desktop-dark-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-desktop-light-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-narrow-light-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-edit-name-error-chromium-linux.png is excluded by !**/*.png
packages/mosaic/test/public/fonts/InterVariable.woff2 is excluded by !**/*.woff2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

Trigger review

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: clerk/javascript
Branch: austin/snapshot-test-poc
File: .coderabbit.yaml
Commit: 70d2429
Layers: Repository YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Team
Run ID: 21b28a34-e5a6-41e2-ab71-a6182c59f9c6

Commits

Reviewing files that changed from the base of the PR and between 5248474 and 70d2429.

Files ignored due to path filters: 7

packages/mosaic/src/features/organization-switcher/__tests__/__screenshots__/organization-switcher.visual.test.tsx/organization-switcher-open-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-button/__tests__/__screenshots__/user-button.visual.test.tsx/user-button-combined-open-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-desktop-dark-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-desktop-light-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-account-narrow-light-chromium-linux.png is excluded by !**/*.png
packages/mosaic/src/features/user-profile/__tests__/__screenshots__/user-profile.visual.test.tsx/user-profile-edit-name-error-chromium-linux.png is excluded by !**/*.png
packages/mosaic/test/public/fonts/InterVariable.woff2 is excluded by !**/*.woff2

Files selected for processing: 1

packages/mosaic/package.json

Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/clerk-android (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/cli (auto-detected)

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

Walkthrough

The change adds a Chromium visual-test project for Mosaic and screenshot tests for organization and user switchers and user profiles. It adds test fixtures, browser and font setup, and Docker commands for screenshot comparison and baseline updates. A CI job reports screenshot differences and uploads artifacts. The testing guide describes the visual-test workflow alongside Swingset stories.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

clerk/javascript#10514: Changes the UserProfile render path used by the profile screenshots.
clerk/javascript#10408: Changes Mosaic color tokens that affect the dark-mode profile screenshot.

Merge Risk: Moderate · previous review 70d24

Resolve the baseline, CI reporting, documentation, and pixel-comparison issues before relying on these visual tests as a safe regression signal.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly identifies the addition of Mosaic screenshot testing and matches the main changeset.
Description check		The description directly explains the six screenshot tests, visual comparison setup, CI behavior, and validation results.
Docstring Coverage		Docstring coverage is inconclusive: files from earlier reviews still need to be rechecked within the check's analysis limits. Not blocking.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.

CodeRabbit Verify

Run CodeRabbit Verify to test the changes in this pull request.

pkg-pr-new · 2026-10-27T05:20:05Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@10451

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@10451

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@10451

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@10451

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10451

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10451

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10451

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@10451

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10451

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10451

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10451

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@10451

@clerk/express

npm i https://pkg.pr.new/@clerk/express@10451

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@10451

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@10451

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@10451

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10451

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@10451

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@10451

@clerk/react

npm i https://pkg.pr.new/@clerk/react@10451

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@10451

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@10451

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@10451

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@10451

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@10451

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@10451

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@10451

commit: df33288

alexcarpenter · 2026-10-27T12:23:40Z

This is awesome, always found visual tests to be a bit flaky, mostly comes from the rendering environment, so maybe we:

Pin the environment. Baselines are *-darwin.png, so Linux CI won't match. Generate and compare only in the pinned Playwright Docker image, locally and in CI.
Self-host a font in test/public instead of Arial, which is likely missing on Linux (not verified).
Kill motion globally. reducedMotion only helps where CSS respects it. Add a setup stylesheet that disables animations/transitions and hides the caret.
Roll out non-blocking. Upload diffs as artifacts and rerun the same commit to measure flake rate before making it required.
Prefer layout assertions for layout bugs, e.g. scrollWidth === clientWidth overflow checks.

I haven't run the suite; these come from reading the code.

…t overlay

…d image

…ocally and in CI

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 05:17

View deployment

github-actions Bot added the mosaic label Oct 27, 2026

vercel Bot deployed to Preview – swingset October 27, 2026 05:20

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 15:18

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 15:20

View deployment

github-actions Bot added the actions label Oct 27, 2026

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 15:22

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 15:24

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 16:03

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 16:05

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 16:10

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 16:13

View deployment

austincalvelage force-pushed the austin/snapshot-test-poc branch from e181368 to 126db7e Compare October 27, 2026 17:16

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 17:17

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 17:18

View deployment

alexcarpenter mentioned this pull request Oct 27, 2026

fix(mosaic): strip native button styling from switcher rows #10466

Merged

1 of 9 tasks

austincalvelage force-pushed the austin/snapshot-test-poc branch from 126db7e to ac036f8 Compare October 27, 2026 20:12

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 20:13

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 20:15

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 20:18

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 20:20

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 21:36

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 21:38

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox October 27, 2026 21:53

View deployment

vercel Bot deployed to Preview – swingset October 27, 2026 21:55

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox November 2, 2026 20:05

View deployment

vercel Bot deployed to Preview – swingset November 2, 2026 20:08

View deployment

vercel Bot deployed to Preview – clerk-js-sandbox November 2, 2026 20:15

View deployment

vercel Bot deployed to Preview – swingset November 2, 2026 20:18

View deployment

austincalvelage force-pushed the austin/snapshot-test-poc branch from 4099952 to 752d3bf Compare November 2, 2026 20:35

vercel Bot deployed to Preview – clerk-js-sandbox November 2, 2026 20:36

View deployment

vercel Bot deployed to Preview – swingset November 2, 2026 20:39

View deployment

austincalvelage added 16 commits November 2, 2026 16:00

test(mosaic): add screenshot testing POC

4841fd7

test(mosaic): run visual comparisons in Linux CI

18e98a7

test(mosaic): add CI-generated Linux screenshot baselines

1e19675

test(mosaic): pin visual testing to a shared Docker environment

610846e

test(mosaic): refresh baselines from the pinned Linux container

9f527a2

test(mosaic): refresh switcher baselines after button reset

cd7a5ff

test(mosaic): stabilize visual tests and simplify the Docker loop

41b6e6f

test(mosaic): screenshot the real user profile instead of a hand-buil…

002ca65

…t overlay

ci(mosaic): build visual tests on the runner and compare in the pinne…

5383780

…d image

ci(mosaic): fail the visual job on setup errors and call vitest by path

66efc85

test(mosaic): fit the viewport to the profile and pull baselines from CI

9d03e54

test(mosaic): refresh baselines from the CI comparison

30f08cd

docs(mosaic): describe the CI-only screenshot baseline flow

ab1f7f1

test(mosaic): run screenshot compare and update in the pinned image l…

0e465f9

…ocally and in CI

test(mosaic): compare screenshots with zero color tolerance

236a83f

test(mosaic): refresh visual baselines for color token updates

df33288

austincalvelage force-pushed the austin/snapshot-test-poc branch from 752d3bf to df33288 Compare November 3, 2026 00:00

vercel Bot deployed to Preview – clerk-js-sandbox November 3, 2026 00:01

View deployment

vercel Bot deployed to Preview – swingset November 3, 2026 00:03

View deployment

coderabbitai Bot mentioned this pull request Nov 3, 2026

refactor(mosaic): share media sizes and radii between IconFrame and Avatar #10600

Merged

1 of 9 tasks

alexcarpenter approved these changes Nov 3, 2026

View reviewed changes

austincalvelage merged commit 457be8e into main Nov 3, 2026
57 checks passed

austincalvelage deleted the austin/snapshot-test-poc branch November 3, 2026 18:20

Navigation Menu

Repository navigation

test(mosaic): add screenshot testing POC - #10451

test(mosaic): add screenshot testing POC#10451
austincalvelage merged 16 commits into
mainfrom
austin/snapshot-test-poc

austincalvelage commented Oct 27, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Oct 27, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 27, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading

Review skipped

Uh oh!

pkg-pr-new Bot commented Oct 27, 2026 •

edited

Loading

Uh oh!

alexcarpenter commented Oct 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

austincalvelage commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

CodeRabbit Verify

Uh oh!

pkg-pr-new Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexcarpenter commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

austincalvelage commented Oct 27, 2026 •

edited

Loading

changeset-bot Bot commented Oct 27, 2026 •

edited

Loading

vercel Bot commented Oct 27, 2026 •

edited

Loading

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 27, 2026 •

edited

Loading

alexcarpenter commented Oct 27, 2026 •

edited

Loading