add test descriptiongs

Author: jacekradko

integration/tests/session-token-cache/multi-session.test.ts

@@ -4,6 +4,14 @@ import { appConfigs } from '../../presets';
 import type { FakeUser } from '../../testUtils';
 import { createTestUtils, testAgainstRunningApps } from '../../testUtils';
 
+/**
+ * Tests MemoryTokenCache session isolation in multi-session scenarios
+ *
+ * This suite validates that when multiple user sessions exist simultaneously,
+ * each session maintains its own isolated token cache. Tokens are not shared
+ * between different sessions, even within the same tab, ensuring proper
+ * security boundaries between users.
+ */
 testAgainstRunningApps({ withEnv: [appConfigs.envs.withSessionTasks] })(
   'MemoryTokenCache Multi-Session Integration @nextjs',
   ({ app }) => {
@@ -26,6 +34,23 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withSessionTasks] })(
       await app.teardown();
     });
 
+    /**
+     * Test Flow:
+     * 1. Tab1: Sign in as user1, fetch and cache their token
+     * 2. Tab2: Opens and inherits user1's session via cookies
+     * 3. Tab2: Sign in as user2 using programmatic sign-in (preserves both sessions)
+     * 4. Tab2: Now has two active sessions (user1 and user2)
+     * 5. Tab2: Switch between sessions and fetch tokens for each
+     * 6. Verify no network requests occur (tokens served from cache)
+     * 7. Tab1: Verify it still has user1 as active session (tab independence)
+     *
+     * Expected Behavior:
+     * - Each session has its own isolated token cache
+     * - Switching sessions in tab2 returns different tokens
+     * - Both tokens are served from cache (no network requests)
+     * - Tab1 remains unaffected by tab2's session changes
+     * - Multi-session state is properly maintained per-tab
+     */
     test('MemoryTokenCache multi-session - multiple users in different tabs with separate token caches', async ({
       context,
     }) => {

integration/tests/session-token-cache/single-session.test.ts

@@ -4,6 +4,13 @@ import { appConfigs } from '../../presets';
 import type { FakeUser } from '../../testUtils';
 import { createTestUtils, testAgainstRunningApps } from '../../testUtils';
 
+/**
+ * Tests MemoryTokenCache cross-tab token sharing via BroadcastChannel
+ *
+ * This suite validates that when multiple browser tabs share the same user session,
+ * token fetches in one tab are automatically broadcast and cached in other tabs,
+ * eliminating redundant network requests.
+ */
 testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
   'MemoryTokenCache Multi-Tab Integration @generic',
   ({ app }) => {
@@ -25,6 +32,20 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
       await app.teardown();
     });
 
+    /**
+     * Test Flow:
+     * 1. Open two tabs with the same browser context (shared cookies)
+     * 2. Sign in on tab1, which creates a session
+     * 3. Reload tab2 to pick up the session from cookies
+     * 4. Clear token cache on both tabs
+     * 5. Fetch token on tab1 (triggers network request + broadcast)
+     * 6. Fetch token on tab2 (should use broadcasted token, no network request)
+     *
+     * Expected Behavior:
+     * - Both tabs receive identical tokens
+     * - Only ONE network request is made (from tab1)
+     * - Tab2 gets the token via BroadcastChannel, proving cross-tab cache sharing
+     */
     test('MemoryTokenCache multi-tab token sharing', async ({ context }) => {
       const page1 = await context.newPage();
       const page2 = await context.newPage();