DO NOT MERGE: validate refresh timer cleanup test fails without fix

[jacekradko]

⚠️ DO NOT MERGE — Validation Only

This PR exists solely to validate that the e2e test added in #TBD (jacek/fix-token-cache-timer-leak) fails without the corresponding implementation changes.

What's here

• integration/tests/session-token-cache/refresh-timer-cleanup.test.ts — the new e2e test that verifies the token cache's proactive refresh timer does not accumulate orphaned timers across set() calls.

What's NOT here

• The implementation fix in tokenCache.ts that clears the previous timer before setting a new one.

Expected outcome

This test should fail on CI, confirming that:

1. The test actually catches the timer leak bug
2. The implementation changes on jacek/fix-token-cache-timer-leak are necessary for the test to pass

Once validated, this PR should be closed without merging.

Summary by CodeRabbit

• Tests
  • Added integration tests for session token refresh behavior to ensure token refresh requests are properly managed and not unnecessarily clustered during session operations.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 20, 2026 3:15am

[changeset-bot]

⚠️ No Changeset found

Latest commit: 172200f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 172200f

[coderabbitai]

📝 Walkthrough

Walkthrough

A new Playwright integration test file was added at integration/tests/session-token-cache/refresh-timer-cleanup.test.ts. The test runs in serial mode against apps with the withEmailCodes environment. It provisions a test user before execution and cleans up afterward. The test signs in via UI, intercepts token refresh requests to track their timestamps, triggers multiple Clerk.session.touch() calls, waits 50 seconds, then verifies that total token refresh requests remain at or below 3, with consecutive requests separated by more than 10 seconds.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change—adding a validation test to demonstrate a timer cleanup issue—though it uses 'DO NOT MERGE' which is unconventional formatting.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

📝 Coding Plan

• Generate coding plan for human review comments

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@integration/tests/session-token-cache/refresh-timer-cleanup.test.ts`:
- Around line 63-65: The test relies on SessionTokenCache clearing existing
refresh timers when a new token is set, but the current main omits that logic;
update the SessionTokenCache.set() implementation to cancel any existing refresh
timer for the same session/key before scheduling a new one
(clearTimeout/clearInterval on the stored timer reference), ensure the timer
reference is stored on the SessionTokenCache instance (e.g., a map of sessionId
-> refreshTimer), and start the new refresh timer only after cleaning up the
previous one so orphaned timers don't fire and the tokenRequests assertion
passes; alternatively, if you deliberately don't want the fix here, keep the
test skipped/xfail in this branch rather than merging it.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4eeb25e1-884e-408a-9f81-34f3cdd7954a

📥 Commits

Reviewing files that changed from the base of the PR and between 21c7c55 and 172200f.

📒 Files selected for processing (1)

• integration/tests/session-token-cache/refresh-timer-cleanup.test.ts

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

This test is unmergeable without the matching token-cache fix.

These assertions require behavior that current main does not have yet: the SessionTokenCache.set() timer cleanup is intentionally omitted in this PR. Merging this file by itself will keep CI red, so the implementation fix needs to land with the test, or this validation test should stay skipped/xfail on this branch.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@integration/tests/session-token-cache/refresh-timer-cleanup.test.ts` around
lines 63 - 65, The test relies on SessionTokenCache clearing existing refresh
timers when a new token is set, but the current main omits that logic; update
the SessionTokenCache.set() implementation to cancel any existing refresh timer
for the same session/key before scheduling a new one (clearTimeout/clearInterval
on the stored timer reference), ensure the timer reference is stored on the
SessionTokenCache instance (e.g., a map of sessionId -> refreshTimer), and start
the new refresh timer only after cleaning up the previous one so orphaned timers
don't fire and the tokenRequests assertion passes; alternatively, if you
deliberately don't want the fix here, keep the test skipped/xfail in this branch
rather than merging it.