fix(testing): fix concurrent Playwright workers timing out on signIn()

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );

.changeset/fix-testing-concurrent-workers.md

@@ -0,0 +1,5 @@
+---
+"@clerk/testing": patch
+---
+
+Fix `signIn()` timing out with concurrent Playwright workers by de-duplicating route handler registration and adding retry with exponential backoff for transient FAPI errors (429, 502, 503, 504).

integration/testUtils/__tests__/retryableClerkClient.test.ts

@@ -135,6 +135,29 @@ describe('withRetry', () => {
  expect(mock).toHaveBeenCalledTimes(2);
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ const error = makeClerkAPIError(429, { retryAfter: 0 });
+ const mock = vi
+ .fn()
+ .mockImplementationOnce(() => Promise.resolve().then(() => Promise.reject(error)))
+ .mockResolvedValueOnce({ id: 'user_123' });
+ const client = makeMockClient({ getUser: mock });
+ const wrapped = withRetry(client);
+
+ const promise = (wrapped.users as any).getUser('user_123');
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mock).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(promise).resolves.toEqual({ id: 'user_123' });
+ expect(mock).toHaveBeenCalledTimes(2);
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS (30s)', async () => {
  const error = makeClerkAPIError(429, { retryAfter: 60 });
  const mock = vi

integration/testUtils/retryableClerkClient.ts

@@ -14,10 +14,11 @@ function sleep(ms: number): Promise<void> {
 }
 
 function getRetryDelay(error: unknown, attempt: number): number {
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  if (isClerkAPIResponseError(error) && typeof error.retryAfter === 'number') {
- return Math.min(error.retryAfter * 1000, MAX_RETRY_DELAY_MS);
+ return Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS);
  }
- return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
+ return exponentialDelay;
 }
 
 function recordRetry(path: string): void {

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

@@ -137,6 +137,26 @@ describe('fetchWithRetry (via fetchEnvVars)', () => {
  expect(warnSpy.mock.calls[0][0]).toContain('waiting 2000ms');
  });
 
+ it('uses exponential backoff as floor when retryAfter is 0', async () => {
+ vi.spyOn(Math, 'random').mockReturnValue(0);
+ mockCreateTestingToken
+ .mockRejectedValueOnce(createClerkAPIError(429, 0))
+ .mockResolvedValueOnce({ token: 'test-token' });
+
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const promise = fetchEnvVars({ dotenv: false });
+
+ // retryAfter=0 should NOT cause a 0ms delay; exponential backoff (1000ms for attempt 0) is used as floor
+ await vi.advanceTimersByTimeAsync(999);
+ expect(mockCreateTestingToken).toHaveBeenCalledTimes(1);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const result = await promise;
+
+ expect(result.CLERK_TESTING_TOKEN).toBe('test-token');
+ expect(warnSpy.mock.calls[0][0]).toContain('waiting 1000ms');
+ });
+
  it('caps retryAfter delay at MAX_RETRY_DELAY_MS', async () => {
  mockCreateTestingToken
  .mockRejectedValueOnce(createClerkAPIError(429, 60))

packages/testing/src/common/setup.ts

@@ -31,10 +31,11 @@ async function fetchWithRetry<T>(fn: () => Promise<T>, label: string): Promise<T
  throw error;
  }
  const status = isClerkAPIResponseError(error) ? error.status : (error as NodeJS.ErrnoException).code;
+ const exponentialDelay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * JITTER_MAX_MS;
  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);
+ ? Math.min(Math.max(error.retryAfter * 1000, exponentialDelay), MAX_RETRY_DELAY_MS)
+ : Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
  console.warn(
  `[Retry] ${status} for ${label}, attempt ${attempt + 1}/${MAX_RETRIES}, waiting ${Math.round(delay)}ms`,
  );