docs(mosaic): favor integration tests and stop asserting CSS in jsdom

[alexcarpenter]

Description

Rewrites the Mosaic testing guidance (.claude/skills/mosaic/references/testing.md) so agents stop producing large numbers of low-value unit tests.

The previous docs prescribed five test files per flow (model, controller, view, wrapper-with-all-layers-mocked, integration). That produced heavy duplication (one rule asserted in four files), tests coupled to internals (machine state names, busy keys, harness <output> elements, vi.mock of internal modules), and StyleX "probe" tests that assert compiled CSS atoms in jsdom, which never loads the stylesheet.

The new guide follows the testing trophy (Write tests. Not too many. Mostly integration.):

• Flows are tested mostly through one integration test: real layers, mocked @clerk/shared/react, driven with userEvent and role queries.
• Test each behavior once, at the highest level that reaches it cheaply.
• Mock only at the package boundary; never vi.mock a module inside packages/mosaic.
• Assert what users observe, not machine state, internal keys, or DOM nesting.
• Never assert CSS values in jsdom. The .cl-<slot> / data-<axis> contract is pinned once centrally and once per part; visual checks belong in a real browser.
• A list of tests not to write, and per-kind guidance for primitives, styled components, and the machine library.
• Adds end-to-end as the top layer: a few critical journeys run in Playwright against the published package (the suite from test(e2e): add Mosaic UserButton integration suite #9846), while jsdom integration tests own the branches.

references/mosaic-architecture.md and the other Mosaic skill references (SKILL.md, migration.md, models.md, controllers.md, views.md, headless.md) drop the per-layer test mandate and point to the new guide. Existing tests are unchanged.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 23, 2026 12:30am UTC
swingset	Ready	Preview	Sep 23, 2026 12:30am UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 0897b9d

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

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: 5866942e-c3e0-436f-aeac-afaee64c5c79

📥 Commits

Reviewing files that changed from the base of the PR and between 7333b13 and 0897b9d.

📒 Files selected for processing (9)

• .changeset/mosaic-testing-guidance.md
• .claude/skills/mosaic/SKILL.md
• .claude/skills/mosaic/references/controllers.md
• .claude/skills/mosaic/references/headless.md
• .claude/skills/mosaic/references/migration.md
• .claude/skills/mosaic/references/models.md
• .claude/skills/mosaic/references/testing.md
• .claude/skills/mosaic/references/views.md
• references/mosaic-architecture.md

🔗 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/cli (auto-detected)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)

Included review availability: 1 review is currently available. Your included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

---

📝 Walkthrough

Walkthrough

The PR replaces isolated Mosaic model, controller, and view testing guidance with integration-first guidance. It emphasizes real-layer composition, mocked Clerk package boundaries, DOM-driven interactions, and user-observable assertions. Unit tests remain for pure helpers and complex machines. Related architecture, migration, skill, and layer references now describe this approach.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• clerk/javascript#9597: Defines the Mosaic model, controller, view split and the earlier per-layer testing matrix revised by this PR.

Suggested reviewers: ephem, austincalvelage

Merge Risk: ⚪ Minimal · up to 0897b

The updated testing guidance is ready to merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation change: favoring integration tests and removing CSS assertions from jsdom tests.
Description check	✅ Passed	The description directly explains the Mosaic testing guidance changes, their motivation, and the affected references.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 0897b9d

[maxyinger]

🤖 Two small additions that fit the guide's approach:

1. Say outright that pass-through props aren't tested. The styled-component section says to test "defaults and prop wiring a developer would rely on", which is loose enough that agents keep writing "prop X reached child Y" tests. Suggested wording:

Don't test that a prop is passed through unchanged. TypeScript catches a renamed or missing required prop, and the integration test catches a broken wire. Test a prop only when the component maps, picks, or overrides it (label becomes title, a failed state picks data-color="negative", a consumer className wins over a default). An exported component gets one test that it forwards ref, aria-*, and the rest of its props to the DOM, since that is its contract with consumers.

2. Extend "test a behavior once" to blocks, not just primitives. Rule 1 names styled components vs primitives. Features duplicate blocks the same way: every user-profile action test was re-asserting Confirmation / Destructive behavior (pending aria-busy, blocking a second confirm, failure + retry, focus return after Escape). Something like:

Features don't re-test the blocks they use. Confirmation and Destructive own pending, failure and retry, and focus return; a feature asserts only what it decides (which rows get an action, the confirmation copy, the call that leaves Mosaic).