# .env.local — use test keys (pk_test_ / sk_test_)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Optional: Enable Clerk debug logging
CLERK_DEBUG=true

// scripts/seed-test-users.ts
import { createClerkClient } from '@clerk/backend'

const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY! })

async function seedTestUsers() {
  const users = [
    { emailAddress: ['admin@test.com'], password: 'test1234', firstName: 'Admin', lastName: 'User' },
    { emailAddress: ['member@test.com'], password: 'test1234', firstName: 'Member', lastName: 'User' },
  ]

  for (const user of users) {
    try {
      await clerk.users.createUser(user)
      console.log(`Created: ${user.emailAddress[0]}`)
    } catch (err: any) {
      if (err.status === 422) {
        console.log(`Already exists: ${user.emailAddress[0]}`)
      } else {
        throw err
      }
    }
  }
}

seedTestUsers()

npx tsx scripts/seed-test-users.ts

// next.config.ts — ensure Clerk works with hot reload
const nextConfig = {
  // Clerk SDK is compatible with Turbopack
  experimental: {
    // turbo: {}, // Uncomment if using Turbopack
  },
  // Prevent Clerk SDK from being bundled incorrectly
  serverExternalPackages: ['@clerk/backend'],
}

export default nextConfig

# Start dev server with HTTPS (required for some Clerk features)
npx next dev --experimental-https

// package.json scripts
{
  "scripts": {
    "dev": "next dev",
    "dev:https": "next dev --experimental-https",
    "dev:seed": "tsx scripts/seed-test-users.ts",
    "dev:tunnel": "ngrok http 3000",
    "dev:webhook": "ngrok http 3000 --log stdout"
  }
}

// test/helpers/clerk-mock.ts
import { vi } from 'vitest'

export function mockClerkAuth(overrides: { userId?: string; orgId?: string } = {}) {
  const mockAuth = {
    userId: overrides.userId || 'user_test_123',
    orgId: overrides.orgId || null,
    getToken: vi.fn().mockResolvedValue('mock_token'),
    has: vi.fn().mockReturnValue(true),
  }

  vi.mock('@clerk/nextjs/server', () => ({
    auth: vi.fn().mockResolvedValue(mockAuth),
    currentUser: vi.fn().mockResolvedValue({
      id: mockAuth.userId,
      firstName: 'Test',
      lastName: 'User',
      emailAddresses: [{ emailAddress: 'test@test.com' }],
    }),
    clerkMiddleware: vi.fn(() => (req: any, res: any, next: any) => next()),
  }))

  return mockAuth
}

// test/api/data.test.ts
import { describe, it, expect, beforeEach } from 'vitest'
import { mockClerkAuth } from '../helpers/clerk-mock'

describe('GET /api/data', () => {
  beforeEach(() => {
    mockClerkAuth({ userId: 'user_test_123' })
  })

  it('returns data for authenticated user', async () => {
    const res = await fetch('/api/data')
    expect(res.status).toBe(200)
  })
})

// e2e/fixtures/auth.ts
import { test as base } from '@playwright/test'

export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/sign-in')
    await page.fill('input[name="identifier"]', 'admin@test.com')
    await page.click('button:has-text("Continue")')
    await page.fill('input[name="password"]', 'test1234')
    await page.click('button:has-text("Continue")')
    await page.waitForURL('/dashboard')
    await use(page)
  },
})