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

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});

.changeset/retry-testing-token.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Add retry logic with exponential backoff for testing token fetch on 429 and 5xx responses.

packages/testing/package.json

@@ -72,7 +72,8 @@
  "dev:pub": "pnpm dev -- --env.publish",
  "format": "node ../../scripts/format-package.mjs",
  "format:check": "node ../../scripts/format-package.mjs --check",
- "lint": "eslint src"
+ "lint": "eslint src",
+ "test": "vitest"
  },
  "dependencies": {
  "@clerk/backend": "workspace:^",

packages/testing/src/common/__tests__/setup.test.ts

@@ -0,0 +1,200 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Re-export internals for testing by importing the module and testing through fetchEnvVars
+// Since fetchWithRetry and isNetworkError are not exported, we test them indirectly through fetchEnvVars
+// and also directly by extracting them via a test-specific import approach.
+
+// We need to mock the dependencies before importing the module under test
+vi.mock('@clerk/backend', () => ({
+ createClerkClient: vi.fn(),
+}));
+
+vi.mock('dotenv', () => ({
+ default: { config: vi.fn() },
+}));
+
+vi.mock('@clerk/shared/keys', () => ({
+ parsePublishableKey: vi.fn(() => ({ frontendApi: 'clerk.test.lcl.dev' })),
+}));
+
+import { createClerkClient } from '@clerk/backend';
+
+import { fetchEnvVars } from '../setup';
+
+function createClerkAPIError(status: number, retryAfter?: number) {
+ return new ClerkAPIResponseError('API error', {
+ data: [],
+ status,
+ retryAfter,
+ });
+}
+
+function createNetworkError(code: string) {
+ const err = new Error(`connect ${code}`);
+ (err as NodeJS.ErrnoException).code = code;
+ return err;
+}
+
+describe('fetchWithRetry (via fetchEnvVars)', () => {
+ const mockCreateTestingToken = vi.fn();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubEnv('CLERK_PUBLISHABLE_KEY', 'pk_test_abc');
+ vi.stubEnv('CLERK_SECRET_KEY', 'sk_test_abc');
+ delete process.env.CLERK_TESTING_TOKEN;
+
+ vi.mocked(createClerkClient).mockReturnValue({
+ testingTokens: { createTestingToken: mockCreateTestingToken },
+ } as any);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it('returns on first success without retrying', async () => {
+ mockCreateTestingToken.mockResolvedValueOnce({ token: 'test-token' });
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on 429 and succeeds', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('[Retry] 429');
+ expect(warnSpy.mock.calls[0][0]).toContain('attempt 1/5');
+ });
+
+ it.each([408, 500, 502, 503, 504])('retries on %i status code', async status => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(status))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not retry on non-retryable status codes', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(createClerkAPIError(401));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('API error');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws after max retries exhausted', async () => {
+ mockCreateTestingToken.mockImplementation(() => Promise.reject(createClerkAPIError(429)));
+
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const promise = fetchEnvVars({ dotenv: false }).catch(e => e);
+
+ await vi.runAllTimersAsync();
+
+ const error = await promise;
+ expect(error).toBeInstanceOf(ClerkAPIResponseError);
+ expect(error.status).toBe(429);
+ // 1 initial + 5 retries = 6 total calls
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(6);
+ });
+
+ it('uses retryAfter from error when available', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 2))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter is 2 seconds = 2000ms
+ await vi.advanceTimersByTimeAsync(2000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
+ });
+
+ it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 60))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ // 60s * 1000 = 60000ms, capped to 30000ms
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 30000ms');
+ });
+
+ it.each(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN'])(
+ 'retries on network error %s',
+ async code => {
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createNetworkError(code))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(2);
+ expect(warnSpy.mock.calls[0][0]).toContain(`[Retry] ${code}`);
+ },
+ );
+
+ it('does not retry on non-network errors', async () => {
+ mockCreateTestingToken.mockRejectedValueOnce(new TypeError('unexpected'));
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unexpected');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not retry when non-retryable error code is present', async () => {
+ const err = new Error('unknown');
+ (err as NodeJS.ErrnoException).code = 'EPERM';
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ mockCreateTestingToken.mockRejectedValueOnce(err);
+
+ await expect(fetchEnvVars({ dotenv: false })).rejects.toThrow('unknown');
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+ });
+
+ it('skips retry when CLERK_TESTING_TOKEN is already set', async () => {
+ vi.stubEnv('CLERK_TESTING_TOKEN', 'existing-token');
+
+ const result = await fetchEnvVars({ dotenv: false });
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('existing-token');
+ expect(mockCreateTestingToken).not.toHaveBeenCalled();
+ });
+});

packages/testing/src/common/setup.ts

@@ -1,9 +1,49 @@
 import { createClerkClient } from '@clerk/backend';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import dotenv from 'dotenv';
 
 import type { ClerkSetupOptions, ClerkSetupReturn } from './types';
 
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const JITTER_MAX_MS = 500;
+const MAX_RETRY_DELAY_MS = 30_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN']);
+
+function isNetworkError(error: unknown): boolean {
+ return (
+ error instanceof Error &&
+ 'code' in error &&
+ RETRYABLE_NETWORK_ERRORS.has((error as NodeJS.ErrnoException).code ?? '')
+ );
+}
+
+async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T> {
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+ try {
+ return await fn();
+ } catch (error) {
+ const isRetryableApi = isClerkAPIResponseError(error) && RETRYABLE_STATUS_CODES.has(error.status);
+ const isRetryableNetwork = isNetworkError(error);
+ if ((!isRetryableApi && !isRetryableNetwork) || attempt === MAX_RETRIES) {
+ throw error;
+ }
+ const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const delay =
+ isClerkAPIResponseError(error) && typeof error.retryAfter === 'number'
+ ? Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS)
+ : Math.min(BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS, MAX_RETRY_DELAY_MS);
+ console.warn(
+ `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
+ );
+ await new Promise(resolve => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error('Unreachable');
+}
+
 export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSetupReturn> => {
  const { debug = false, dotenv: loadDotEnv = true, ...rest } = options || {};
 
@@ -44,7 +84,10 @@ export const fetchEnvVars = async (options?: ClerkSetupOptions): Promise<ClerkSe
  try {
  const apiUrl = (rest as any)?.apiUrl || process.env.CLERK_API_URL;
  const clerkClient = createClerkClient({ secretKey, apiUrl });
- const tokenData = await clerkClient.testingTokens.createTestingToken();
+ const tokenData = await fetchWithRetry(
+ () => clerkClient.testingTokens.createTestingToken(),
+ 'testingTokens.createTestingToken',
+ );
  testingToken = tokenData.token;
  } catch (err) {
  console.error('Failed to fetch testing token from Clerk API.');

packages/testing/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ watch: false,
+ include: ['**/*.{test,spec}.{ts,tsx}'],
+ },
+});