test(expo): add behavioral native client sync suite

[mikepitre]

Description

Adds an engine-agnostic behavioral test suite for the @clerk/expo JS <-> native client sync, so it can gate the upcoming replacement of the sync engine (native owns the device token, payload-free invalidations in both directions).

The suite lives in packages/expo/src/provider/__tests__/nativeClientSyncBehavior/ and asserts only user-observable outcomes: the JS signed-in state and active session, the native token and client view, request and refresh counts, the absence of signed-out emissions during session switches, and errors surfaced through the sync barrier. It is backed by:

• FakeClerkServer: one Frontend API shared by both SDKs, with clients keyed by device token.
• FakeNativeClerk: the native SDK's persisted token, its client view, and native-originated actions and change notifications.
• FakeClerk: a stand-in for the clerk-js instance returned by getClerkInstance, using the same surface the existing ClerkProvider tests mock. It talks to the fake Frontend API through the token cache it is built with, like createClerkInstance.
• currentEngineAdapter: renderWithNativeSync(scenario) for today's engine. It keeps today's native module contract (configure, getClientToken, syncClientStateFromJs, clerkNativeClientChanged payloads and sourceId tags) out of the tests. To run the suite against a new engine, only the export in index.ts needs to point at a new adapter.

Two behaviors the current engine does not meet yet are kept as it.fails under "known gaps in the current engine". They should flip to it once the new engine lands:

• JS starting with a stale device token replaces native's signed-in token, because configure adopts the JS bearer token.
• If JS and native rotate the device token at the same time, the two sides end up on different tokens.

The existing ClerkProvider.nativeClientSync and coordinator 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: tests

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 8c5d287

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]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 27, 2026 2:53pm UTC
swingset	Ready	Preview	Sep 27, 2026 2:53pm UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{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@9954

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 544222b