fix(testing): add retry logic for testing token fetch on 429/5xx

[jacekradko]

Summary

• Add retry with exponential backoff to the testing token fetch in @clerk/testing
• The fetchEnvVars function calls testingTokens.createTestingToken() without retry handling, causing E2E test failures when FAPI returns 429 (Too Many Requests)
• Retries up to 5 times on 429, 502, 503, 504 with exponential backoff + jitter, matching the existing retryableClerkClient used in integration tests
• Both retryAfter and exponential backoff delay paths are consistently capped by MAX_RETRY_DELAY_MS

Test plan

• Verify @clerk/testing builds successfully
• Run E2E tests with concurrent workers to confirm 429s are retried instead of failing immediately

Summary by CodeRabbit

• Bug Fixes
  • Testing token creation now automatically retries on transient failures (rate limits and 5xx) with exponential backoff and jitter, respects Retry-After when provided, and caps retry delays—improving reliability.
  • Retry attempts emit warning logs with status, operation label, attempt count, and wait time; final failures still surface the original error.

[changeset-bot]

🦋 Changeset detected

Latest commit: 131cff5

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

This PR includes changesets to release 1 package

Name	Type
@clerk/testing	Patch

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 (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 26, 2026 4:39pm

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8138

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8138

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 131cff5

[coderabbitai]

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: Pro

Run ID: d18c8e7d-30fd-4a83-beff-fcec07c89de2

📥 Commits

Reviewing files that changed from the base of the PR and between c23b2e4 and 131cff5.

📒 Files selected for processing (1)

• packages/testing/src/common/setup.ts

---

📝 Walkthrough

Walkthrough

Added an internal fetchWithRetry helper and an isClerkAPIResponseError guard in the testing setup. fetchWithRetry wraps the testing token creation call and retries the operation up to MAX_RETRIES when the error is a Clerk API response with status 429, 502, 503, or 504. Retry delay uses a numeric retryAfter (seconds → ms, capped) or exponential backoff with jitter (capped). Each retry emits a console.warn; final failures are rethrown.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding retry logic for testing token fetch when 429/5xx errors occur.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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