feat(e2e): implement Playwright + MSW authentication bypass for E2E tests

- Add instrumentation.ts for server-side MSW initialization
- Add E2E test mode bypass in proxy.ts middleware
- Use JavaScript Proxy pattern in server.ts to mock Supabase auth
- Fix test selectors based on actual page structure
- Replace networkidle with domcontentloaded for MSW compatibility

All 26 E2E tests passing locally with mocked authentication.

Author: ryota-murakami

app/layout.tsx

@@ -33,20 +33,8 @@ import { Providers } from '@/lib/redux/providers'
 
 import { MSWProvider } from './msw-provider'
 
-// Server-side MSW initialization
-// This runs at module load time for Node.js runtime only
-// Must be at the TOP of the file, before any components render
-if (process.env.NEXT_RUNTIME === 'nodejs') {
-  // Dynamic import to avoid bundling MSW in client bundle
-  const initMSW = async () => {
-    const { isMSWEnabled } = await import('@/lib/utils/isMSWEnabled')
-    if (isMSWEnabled()) {
-      const { server } = await import('../mocks/server')
-      server.listen({ onUnhandledRequest: 'bypass' })
-    }
-  }
-  initMSW()
-}
+// NOTE: Server-side MSW is initialized via instrumentation.ts (Next.js hook)
+// This ensures MSW starts BEFORE any route handlers run.
 
 export default function RootLayout({
   children,

instrumentation.ts

@@ -0,0 +1,32 @@
+/**
+ * Next.js Instrumentation
+ *
+ * This file is automatically loaded by Next.js before the application starts.
+ * Used to initialize MSW for server-side mocking in test environments.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+ */
+
+export async function register() {
+  // Only run on Node.js runtime (not Edge)
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    console.log(
+      '[instrumentation] APP_ENV:',
+      process.env.APP_ENV,
+      'NODE_ENV:',
+      process.env.NODE_ENV,
+    )
+
+    // Check if MSW should be enabled
+    const isMSWEnabled =
+      process.env.NEXT_PUBLIC_ENABLE_MSW_MOCK === 'true' &&
+      (process.env.APP_ENV === 'test' || process.env.NODE_ENV === 'test')
+
+    if (isMSWEnabled) {
+      console.log('[MSW] Starting server-side MSW...')
+      const { server } = await import('./mocks/server')
+      server.listen({ onUnhandledRequest: 'bypass' })
+      console.log('[MSW] Server-side MSW started')
+    }
+  }
+}

lib/supabase/server.ts

@@ -10,6 +10,17 @@ import { cookies } from 'next/headers'
 
 import type { Database } from './types'
 
+/**
+ * Check if E2E test mode is enabled
+ * When true, auth checks return mock data to bypass OAuth
+ *
+ * NOTE: Uses APP_ENV (server-side) instead of NEXT_PUBLIC_ENABLE_MSW_MOCK
+ * because NEXT_PUBLIC_* vars are inlined at build time and may not be
+ * available at runtime on the server.
+ */
+const isE2ETestMode = () =>
+  process.env.APP_ENV === 'test' || process.env.NODE_ENV === 'test'
+
 /**
  * Create Supabase client for use in Server Components
  *
@@ -27,7 +38,7 @@ import type { Database } from './types'
 export async function createClient() {
   const cookieStore = await cookies()
 
-  return createServerClient<Database>(
+  const supabase = createServerClient<Database>(
     process.env.NEXT_PUBLIC_SUPABASE_URL!,
     process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
     {
@@ -53,6 +64,59 @@ export async function createClient() {
       },
     },
   )
+
+  // In E2E test mode, wrap auth methods to return mock data
+  const testMode = isE2ETestMode()
+  console.log(
+    '[createClient] APP_ENV:',
+    process.env.APP_ENV,
+    'NODE_ENV:',
+    process.env.NODE_ENV,
+    'isE2ETestMode:',
+    testMode,
+  )
+  if (testMode) {
+    // Use a Proxy to intercept auth methods while preserving all other client functionality
+    const mockedAuth = {
+      getUser: async () => ({
+        data: { user: MOCK_USER_FOR_E2E },
+        error: null,
+      }),
+      getSession: async () => ({
+        data: {
+          session: {
+            access_token: 'mock-access-token-for-testing',
+            token_type: 'bearer',
+            expires_in: 3600,
+            expires_at: Math.floor(Date.now() / 1000) + 3600,
+            refresh_token: 'mock-refresh-token-for-testing',
+            user: MOCK_USER_FOR_E2E,
+          },
+        },
+        error: null,
+      }),
+    }
+
+    return new Proxy(supabase, {
+      get(target, prop) {
+        if (prop === 'auth') {
+          // Return a proxy for auth that intercepts getUser/getSession
+          return new Proxy(target.auth, {
+            get(authTarget, authProp) {
+              if (authProp === 'getUser') return mockedAuth.getUser
+              if (authProp === 'getSession') return mockedAuth.getSession
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              return (authTarget as any)[authProp]
+            },
+          })
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (target as any)[prop]
+      },
+    }) as typeof supabase
+  }
+
+  return supabase
 }
 
 /**
@@ -136,10 +200,47 @@ export async function createServerActionClient() {
   )
 }
 
+/**
+ * Mock user for E2E testing when MSW is enabled
+ */
+const MOCK_USER_FOR_E2E = {
+  id: 'test-user-id-12345',
+  aud: 'authenticated',
+  role: 'authenticated',
+  email: 'test@example.com',
+  email_confirmed_at: new Date().toISOString(),
+  phone: '',
+  confirmed_at: new Date().toISOString(),
+  last_sign_in_at: new Date().toISOString(),
+  app_metadata: { provider: 'github', providers: ['github'] },
+  user_metadata: {
+    avatar_url: 'https://avatars.githubusercontent.com/u/12345',
+    full_name: 'Test User',
+    preferred_username: 'testuser',
+    user_name: 'testuser',
+  },
+  identities: [],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+  is_anonymous: false,
+} as const
+
 /**
  * Get current user (server-side)
+ *
+ * In E2E test mode (NEXT_PUBLIC_ENABLE_MSW_MOCK=true + APP_ENV=test),
+ * returns a mock user to bypass OAuth flow.
  */
 export async function getUser() {
+  // E2E test mode: return mock user to bypass OAuth
+  const isMSWEnabled =
+    process.env.NEXT_PUBLIC_ENABLE_MSW_MOCK === 'true' &&
+    (process.env.APP_ENV === 'test' || process.env.NODE_ENV === 'test')
+
+  if (isMSWEnabled) {
+    return MOCK_USER_FOR_E2E
+  }
+
   const supabase = await createClient()
   const {
     data: { user },
@@ -156,8 +257,27 @@ export async function getUser() {
 
 /**
  * Get current session (server-side)
+ *
+ * In E2E test mode (NEXT_PUBLIC_ENABLE_MSW_MOCK=true + APP_ENV=test),
+ * returns a mock session to bypass OAuth flow.
  */
 export async function getSession() {
+  // E2E test mode: return mock session to bypass OAuth
+  const isMSWEnabled =
+    process.env.NEXT_PUBLIC_ENABLE_MSW_MOCK === 'true' &&
+    (process.env.APP_ENV === 'test' || process.env.NODE_ENV === 'test')
+
+  if (isMSWEnabled) {
+    return {
+      access_token: 'mock-access-token-for-testing',
+      token_type: 'bearer',
+      expires_in: 3600,
+      expires_at: Math.floor(Date.now() / 1000) + 3600,
+      refresh_token: 'mock-refresh-token-for-testing',
+      user: MOCK_USER_FOR_E2E,
+    }
+  }
+
   const supabase = await createClient()
   const {
     data: { session },

mocks/handlers.ts

@@ -418,20 +418,13 @@ const supabaseAuthHandlers: HttpHandler[] = [
 
   /**
    * GET /auth/v1/user - Get current authenticated user
+   *
+   * For E2E tests: Always returns mock user to simulate authenticated state.
+   * The cookie injection in auth.setup.ts triggers Supabase to call this endpoint.
    */
-  http.get(`${SUPABASE_URL}/auth/v1/user`, ({ request }) => {
-    const authHeader = request.headers.get('Authorization')
-
-    if (!authHeader || !authHeader.startsWith('Bearer ')) {
-      return HttpResponse.json(
-        {
-          error: 'unauthorized',
-          message: 'Missing or invalid authorization header',
-        },
-        { status: 401 },
-      )
-    }
-
+  http.get(`${SUPABASE_URL}/auth/v1/user`, () => {
+    // Always return authenticated user for E2E tests
+    // This allows tests to proceed without real OAuth flow
     return HttpResponse.json(mockUser)
   }),
 

proxy.ts

@@ -14,7 +14,23 @@ import { NextResponse, type NextRequest } from 'next/server'
 // Public paths that don't require authentication
 const publicPaths = ['/', '/login', '/auth/callback']
 
+/**
+ * Check if E2E test mode is enabled
+ * Bypass authentication in middleware for E2E tests
+ */
+const isE2ETestMode = () =>
+  process.env.APP_ENV === 'test' || process.env.NODE_ENV === 'test'
+
 export async function proxy(request: NextRequest) {
+  // In E2E test mode, bypass authentication and allow all requests
+  if (isE2ETestMode()) {
+    console.log('[proxy] E2E test mode - bypassing auth check')
+    return NextResponse.next({
+      request: {
+        headers: request.headers,
+      },
+    })
+  }
   let response = NextResponse.next({
     request: {
       headers: request.headers,

tests/e2e/auth.setup.ts

@@ -29,9 +29,9 @@ const MOCK_USER = {
 
 /**
  * Creates a mock Supabase session token.
- * This is a simplified JWT structure for testing purposes.
+ * This is a simplified session structure for testing purposes.
  *
- * @returns Base64-encoded mock session data
+ * @returns JSON string of mock session data (Supabase SSR expects JSON, not Base64)
  */
 function createMockSupabaseSession(): string {
   const session = {
@@ -43,8 +43,8 @@ function createMockSupabaseSession(): string {
     user: MOCK_USER,
   }
 
-  // Supabase stores session as base64-encoded JSON
-  return Buffer.from(JSON.stringify(session)).toString('base64')
+  // Supabase SSR stores session as JSON string (NOT base64)
+  return JSON.stringify(session)
 }
 
 /**

tests/e2e/boards.spec.ts

@@ -16,66 +16,65 @@ test.describe('Boards Page (Authenticated)', () => {
     // Should show the boards page (not redirected to login)
     await expect(page).toHaveURL(/\/boards/)
 
-    // Should have a heading or indication of boards
-    const heading = page.getByRole('heading', { name: /board/i })
-    await expect(heading).toBeVisible()
+    // Wait for main heading to appear
+    const heading = page.getByRole('heading', { level: 1 })
+    await expect(heading).toBeVisible({ timeout: 10000 })
   })
 
   test('should display user avatar or profile indicator', async ({ page }) => {
     await page.goto('/boards')
 
-    // Look for user menu or avatar
+    // Wait for page to stabilize
+    await page.waitForLoadState('domcontentloaded')
+
+    // Look for user info section (Test User text or avatar)
     const userIndicator = page.locator(
-      '[data-testid="user-menu"], [data-testid="user-avatar"], button:has(img[alt*="avatar" i])',
+      'img[alt="Test User"], :text("Test User")',
     )
-    await expect(userIndicator.first()).toBeVisible()
+    await expect(userIndicator.first()).toBeVisible({ timeout: 10000 })
   })
 
   test('should have option to create new board', async ({ page }) => {
     await page.goto('/boards')
 
-    // Look for create/add board button
-    const createButton = page.getByRole('button', { name: /create|new|add/i })
-    await expect(createButton).toBeVisible()
+    // Wait for page to stabilize
+    await page.waitForLoadState('domcontentloaded')
+
+    // Look for create board link (it's a link, not a button based on the snapshot)
+    const createLink = page.getByRole('link', { name: /create board/i })
+    await expect(createLink).toBeVisible({ timeout: 10000 })
   })
 
   test('should navigate to board detail when clicking a board', async ({
     page,
   }) => {
     await page.goto('/boards')
 
-    // Wait for boards to load (MSW will return mock data)
-    await page.waitForLoadState('networkidle')
+    // Wait for page to stabilize
+    await page.waitForLoadState('domcontentloaded')
 
     // Click on the first board link/card
     const boardLink = page.locator('a[href*="/board/"]').first()
+    await expect(boardLink).toBeVisible({ timeout: 10000 })
+    await boardLink.click()
 
-    if (await boardLink.isVisible()) {
-      await boardLink.click()
-
-      // Should navigate to board detail page
-      await expect(page).toHaveURL(/\/board\//)
-    }
+    // Should navigate to board detail page
+    await expect(page).toHaveURL(/\/board\//)
   })
 
   test('should open create board modal or navigate to new board page', async ({
     page,
   }) => {
     await page.goto('/boards')
 
-    // Click create button
-    const createButton = page.getByRole('button', { name: /create|new|add/i })
-    await createButton.click()
+    // Wait for page to stabilize
+    await page.waitForLoadState('domcontentloaded')
 
-    // Should either open modal or navigate to /boards/new
-    const modalOrPage = page.locator(
-      '[role="dialog"], [data-testid="create-board-modal"]',
-    )
-    const newBoardUrl = page.url().includes('/boards/new')
+    // Click create board link
+    const createLink = page.getByRole('link', { name: /create board/i })
+    await createLink.click()
 
-    expect(
-      (await modalOrPage.isVisible()) || newBoardUrl,
-      'Should either show modal or navigate to new board page',
-    ).toBeTruthy()
+    // Should navigate to /boards/new
+    await expect(page).toHaveURL(/\/boards\/new/)
   })
 })