3 篇博文含有标签「E2E测试」

查看所有标签

Playwright page.route() 实现 API 全量 Mock

2026年3月19日 · 阅读需 4 分钟

CCLEE

在构建 AI Agent 平台时遇到此问题，记录根因与解法。

TL;DR

使用 page.route() 拦截所有 API 请求，返回预定义的 mock 数据。测试不依赖真实后端，可以在任何环境稳定运行，且避免创建/删除数据等副作用。

问题现象

E2E 测试调用真实 API：

// ❌ 依赖真实后端
test('create agent', async ({ authenticatedPage }) => {
  await authenticatedPage.goto('/')

  // 点击创建按钮
  await authenticatedPage.click('button:has-text("Create")')

  // 填写表单
  await authenticatedPage.fill('input[name="name"]', 'Test Agent')
  await authenticatedPage.click('button[type="submit"]')

  // 等待 API 响应
  await authenticatedPage.waitForTimeout(2000)

  // 验证... 但如果后端挂了？如果数据库连接失败？
})

问题：

依赖后端状态 — 后端挂了测试就失败
数据副作用 — 每次运行创建真实数据
不可重复 — 数据变化导致断言失败
CI 环境问题 — 需要启动完整后端服务

解决方案

1. 定义 Mock 数据

// e2e/fixtures.ts
export const mockAgents = [
  {
    agent_id: 'agent-1',
    user_id: 'test-user-id',
    name: 'Test Agent 1',
    skills: [],
    mcp_tools: [],
    llm_config: { provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' },
    risk_threshold: 'medium',
    auto_confirm_low: true,
    created_at: '2024-01-01T00:00:00Z',
  },
]

export const mockSkills = [
  {
    skill_id: 'skill-1',
    owner_id: 'test-user-id',
    name: 'Test Skill',
    system_prompt: 'You are helpful.',
    is_public: false,
    is_own: true,
  },
]

2. 设置 API Mock

export async function setupMockApi(page: Page) {
  // Mock GET /api/agents
  await page.route('**/api/agents', async (route) => {
    if (route.request().method() === 'GET') {
      await route.fulfill({
        status: 200,
        contentType: 'application/json',
        body: JSON.stringify(mockAgents),
      })
    } else if (route.request().method() === 'POST') {
      // 模拟创建
      const body = route.request().postDataJSON()
      const newAgent = {
        agent_id: `agent-${Date.now()}`,
        user_id: 'test-user-id',
        name: body.name,
        created_at: new Date().toISOString(),
        ...body,
      }
      mockAgents.push(newAgent)
      await route.fulfill({
        status: 201,
        contentType: 'application/json',
        body: JSON.stringify(newAgent),
      })
    }
  })

  // Mock GET/PATCH/DELETE /api/agents/:id
  await page.route('**/api/agents/*', async (route) => {
    const url = route.request().url()
    const match = url.match(/\/api\/agents\/([^/]+)/)
    const agentId = match?.[1]

    if (route.request().method() === 'GET') {
      const agent = mockAgents.find((a) => a.agent_id === agentId)
      await route.fulfill({
        status: agent ? 200 : 404,
        contentType: 'application/json',
        body: JSON.stringify(agent || { error: 'Not found' }),
      })
    } else if (route.request().method() === 'DELETE') {
      const index = mockAgents.findIndex((a) => a.agent_id === agentId)
      if (index !== -1) mockAgents.splice(index, 1)
      await route.fulfill({ status: 204 })
    }
  })

  // Mock /api/skills
  await page.route('**/api/skills**', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify(mockSkills),
    })
  })

  // Mock /api/health
  await page.route('**/api/health', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ status: 'ok' }),
    })
  })
}

3. 在 Fixture 中使用

export const test = base.extend<{ authenticatedPage: Page }>({
  authenticatedPage: async ({ page }, use) => {
    await setupMockAuth(page)
    await setupMockApi(page)  // 拦截所有 API
    await use(page)
  },
})

4. 测试中使用

// e2e/dashboard.spec.ts
import { test, expect, mockAgents } from './fixtures'

test('should display agent list', async ({ authenticatedPage }) => {
  await authenticatedPage.goto('/')

  // API 被自动 mock，返回 mockAgents
  const agentCards = authenticatedPage.locator('[data-testid="agent-card"]')

  // 断言基于已知的 mock 数据
  await expect(agentCards).toHaveCount(mockAgents.length)
})

test('should create new agent', async ({ authenticatedPage }) => {
  await authenticatedPage.goto('/')

  await authenticatedPage.click('button:has-text("Create")')

  const dialog = authenticatedPage.locator('[role="dialog"]')
  await dialog.locator('input[name="name"]').fill('New Agent')
  await dialog.locator('button[type="submit"]').click()

  // POST /api/agents 被 mock，返回 201
  await authenticatedPage.waitForTimeout(500)

  // 验证 UI 更新
  await expect(authenticatedPage.locator('text=New Agent')).toBeVisible()
})

核心技巧

URL 匹配模式

// 精确匹配
await page.route('**/api/agents', handler)

// 通配符匹配
await page.route('**/api/agents/**', handler)

// 正则匹配
await page.route(/\/api\/agents\/\d+/, handler)

读取请求体

await page.route('**/api/agents', async (route) => {
  const body = route.request().postDataJSON()
  console.log('Request body:', body)

  // 根据请求内容返回不同响应
  if (body.name === 'error-test') {
    await route.fulfill({ status: 400, body: JSON.stringify({ error: 'Bad request' }) })
  } else {
    await route.fulfill({ status: 201, body: JSON.stringify({ id: 'new-id', ...body }) })
  }
})

模拟错误场景

// 模拟网络错误
await page.route('**/api/agents', (route) => route.abort('failed'))

// 模拟超时
await page.route('**/api/agents', async (route) => {
  await new Promise((r) => setTimeout(r, 30000))
  route.continue()
})

// 模拟 500 错误
await page.route('**/api/agents', (route) =>
  route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal error' }) })
)

部分放行

// 只 mock 特定 API，其他放行
await page.route('**/api/**', async (route) => {
  const url = route.request().url()

  if (url.includes('/api/agents')) {
    await route.fulfill({ status: 200, body: JSON.stringify(mockAgents) })
  } else {
    await route.continue()  // 其他 API 走真实请求
  }
})

Mock 数据管理

// 集中管理所有 mock 数据
// e2e/fixtures.ts
export const mockData = {
  agents: [...],
  skills: [...],
  apiKeys: [...],
  tasks: [...],
}

// 每个测试前重置
test.beforeEach(() => {
  Object.assign(mockData, JSON.parse(JSON.stringify(originalMockData)))
})

关键原则

Mock 所有外部依赖 — API、OAuth、第三方服务
模拟真实数据结构 — Mock 数据应与 API 契约一致
覆盖成功和失败场景 — 200/400/500 都要测试
隔离测试数据 — 每个测试用独立的 mock 数据副本

对类似需求感兴趣？联系合作

Playwright Custom Fixtures 实现免登录测试

2026年3月19日 · 阅读需 4 分钟

CCLEE

在构建 AI Agent 平台时遇到此问题，记录根因与解法。

TL;DR

使用 Playwright 的 test.extend() 创建自定义 fixture，通过 page.addInitScript() 在页面加载前注入 auth token 到 localStorage。测试用 authenticatedPage 替代 page，自动获得登录状态，无需每个测试重复登录。

问题现象

E2E 测试需要验证登录后才能访问的页面：

// ❌ 每个测试都要走登录流程
test('dashboard', async ({ page }) => {
  await page.goto('/login')
  await page.fill('input[name="email"]', 'test@example.com')
  await page.fill('input[name="password"]', 'password')
  await page.click('button[type="submit"]')
  await page.waitForURL('/dashboard')
  // 终于可以开始测试了...
  await expect(page.locator('h1')).toBeVisible()
})

问题：

每个测试重复登录 — 浪费时间，拖慢 CI
依赖真实认证服务 — Supabase Auth 不可用时测试失败
测试间状态污染 — 登录状态可能互相影响

解决方案

1. 创建 Custom Fixture

// e2e/fixtures.ts
import { test as base, expect, Page } from '@playwright/test'

// Mock 用户数据
export const mockUser = {
  id: 'test-user-id',
  email: 'test@example.com',
  aud: 'authenticated',
  role: 'authenticated',
}

export const mockAccessToken = 'mock-access-token-for-testing'

// 注入 auth token 到 localStorage
export async function setupMockAuth(page: Page) {
  await page.addInitScript(
    ({ user, accessToken }) => {
      const mockSession = {
        access_token: accessToken,
        refresh_token: 'mock-refresh-token',
        expires_in: 3600,
        expires_at: Math.floor(Date.now() / 1000) + 3600,
        token_type: 'bearer',
        user,
      }
      // Supabase auth token key 格式: sb-{project}-auth-token
      localStorage.setItem('sb-placeholder-auth-token', JSON.stringify(mockSession))
    },
    { user: mockUser, accessToken: mockAccessToken }
  )
}

// 扩展 fixture
export const test = base.extend<{
  authenticatedPage: Page
}>({
  authenticatedPage: async ({ page }, use) => {
    await setupMockAuth(page)
    await use(page)
  },
})

export { expect }

2. 测试中使用 authenticatedPage

// e2e/dashboard.spec.ts
import { test, expect } from './fixtures'

test.describe('Dashboard', () => {
  test('should display welcome message', async ({ authenticatedPage }) => {
    // 直接访问受保护页面，无需登录
    await authenticatedPage.goto('/dashboard')

    await expect(authenticatedPage.locator('h1')).toContainText('Welcome')
  })

  test('should show agent list', async ({ authenticatedPage }) => {
    await authenticatedPage.goto('/dashboard')

    const agents = authenticatedPage.locator('[data-testid="agent-card"]')
    await expect(agents.first()).toBeVisible()
  })
})

3. 对比：未认证 vs 已认证

// 未认证测试（会重定向到登录页）
test('redirects to login when not authenticated', async ({ page }) => {
  await page.goto('/dashboard')
  await page.waitForTimeout(500)

  expect(page.url()).toContain('/login')
})

// 已认证测试（直接访问 dashboard）
test('allows access when authenticated', async ({ authenticatedPage }) => {
  await authenticatedPage.goto('/dashboard')
  await authenticatedPage.waitForTimeout(500)

  expect(authenticatedPage.url()).not.toContain('/login')
})

核心原理

addInitScript vs 页面加载后设置

// ❌ 错误方式：页面加载后设置（可能已重定向）
await page.goto('/dashboard')
await page.evaluate(() => {
  localStorage.setItem('auth-token', '...')
})
// 此时 auth guard 已经检测到未登录并重定向了

// ✅ 正确方式：页面加载前注入
await page.addInitScript(() => {
  localStorage.setItem('auth-token', '...')
})
await page.goto('/dashboard')  // 页面加载时 auth guard 检测到 token

addInitScript 在以下时机执行：

页面 DOM 开始解析前
React/Vue 等框架初始化前
Auth guard 检查前

Fixture 生命周期

test('dashboard', async ({ authenticatedPage }) => {})
                ↓
        base.extend<{ authenticatedPage }>()
                ↓
        authenticatedPage: async ({ page }, use) => {
          await setupMockAuth(page)  // 1. 设置 auth
          await use(page)            // 2. 执行测试
        }                            // 3. 自动清理

完整配置

// playwright.config.ts
export default defineConfig({
  testDir: './e2e',
  fullyParallel: false,  // 串行执行避免状态污染
  workers: 1,
  use: {
    baseURL: 'http://localhost:5173',
    trace: 'on-first-retry',
  },
  webServer: {
    command: 'pnpm dev',
    url: 'http://localhost:5173',
    reuseExistingServer: !process.env.CI,
  },
})

扩展：结合 API Mock

export const test = base.extend<{
  authenticatedPage: Page
}>({
  authenticatedPage: async ({ page }, use) => {
    await setupMockAuth(page)
    await setupMockApi(page)  // 同时 mock API
    await use(page)
  },
})

关键原则

Fixture 优于 beforeEach — 自动复用，代码更简洁
addInitScript 避免竞态 — 在 auth guard 检查前注入 token
隔离测试数据 — Mock 用户和 token 不要与生产混淆
串行执行避免污染 — workers: 1 或 fullyParallel: false

对类似需求感兴趣？联系合作

绕过 Supabase Auth 实现 Playwright E2E 测试免登录

2026年3月19日 · 阅读需 4 分钟

CCLEE

在为客户构建 AI Agent SaaS 平台时遇到此问题，记录根因与解法。

TL;DR

E2E 测试不应该依赖真实的 OAuth 登录流程。通过在 useAuth hook 中检测 localStorage 的测试标记，直接注入 mock 认证状态，跳过 Supabase 初始化。同时将 Zustand store 的 loading 默认值改为 false，避免 AuthGuard 卡在无限 spinner。

问题现象

使用 Playwright 测试 React SPA 时，页面被 AuthGuard 组件保护，需要 Supabase 认证才能访问。测试启动后，页面一直显示 loading spinner，无法进入业务流程。

// AuthGuard 组件 - 测试时卡在这里
export function AuthGuard({ children }: AuthGuardProps) {
  const { isAuthenticated, loading } = useAuth()

  if (loading) {
    return <Spinner />  // 永远显示 spinner
  }

  if (!isAuthenticated) {
    return <Navigate to="/login" />
  }

  return <>{children}</>
}

测试代码尝试模拟登录，但 Supabase Auth SDK 内部状态无法通过简单的 API mock 控制。

根因

1. Supabase Auth 是异步初始化的

useAuth hook 在 useEffect 中调用 supabase.auth.getSession()，这是异步操作。测试环境下网络请求可能失败或超时，导致状态永远停留在 loading: true。

2. Zustand Store 的默认值问题

// authStore.ts - 问题代码
export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      token: null,
      loading: true,  // 👈 默认值是 true
      // ...
    }),
    { name: 'auth-storage' }
  )
)

测试启动时，loading: true + 异步初始化失败 = 永远 loading。

3. OAuth 流程无法自动化

即使能 mock API，OAuth 的重定向流程需要真实浏览器交互，E2E 测试无法可靠模拟。

解决方案

步骤 1：在 useAuth hook 中添加测试模式检测

// hooks/useAuth.ts
export function useAuth() {
  const { user, token, loading, setUser, setToken, setLoading } = useAuthStore()

  useEffect(() => {
    const initAuth = async () => {
      // 👇 优先检测测试模式
      const testAuthUser = localStorage.getItem('test-auth-user')
      const testAuthToken = localStorage.getItem('test-auth-token')

      if (testAuthUser && testAuthToken) {
        try {
          const userData = JSON.parse(testAuthUser) as User
          setUser(userData)
          setToken(testAuthToken)
          setLoading(false)
          console.log('[useAuth] Using test mode auth')
          return  // 👈 直接返回，跳过 Supabase 初始化
        } catch (e) {
          console.error('Failed to parse test auth user:', e)
        }
      }

      // 👇 正常模式：走 Supabase Auth
      try {
        const { data: { session } } = await supabase.auth.getSession()
        if (session) {
          setUser(session.user as User)
          setToken(session.access_token)
        }
      } catch (error) {
        console.error('Auth init failed:', error)
      } finally {
        setLoading(false)
      }
    }

    initAuth()

    // 👇 测试模式下跳过 auth state listener
    if (localStorage.getItem('test-auth-user')) {
      return
    }

    const { data: { subscription } } = supabase.auth.onAuthStateChange(
      async (event, session) => {
        // ... 正常的 auth state 处理
      }
    )

    return () => subscription.unsubscribe()
  }, [])
}

步骤 2：修改 Zustand Store 默认值

// stores/authStore.ts
export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      token: null,
      loading: false,  // 👈 改为 false，让 useAuth hook 控制状态
      setUser: (user) => set({ user }),
      setToken: (token) => set({ token }),
      setLoading: (loading) => set({ loading }),
      logout: () => set({ user: null, token: null, loading: false }),
    }),
    {
      name: 'auth-storage',
      partialize: (state) => ({ user: state.user, token: state.token }),
    }
  )
)

步骤 3：在 Playwright Fixture 中注入测试认证

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

export const mockUser = {
  id: 'test-user-id',
  email: 'test@example.com',
  created_at: '2024-01-01T00:00:00Z',
}

export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    // 先访问页面以设置 localStorage 的 origin
    await page.goto('/login')

    // 👇 注入测试认证状态到 localStorage
    await page.evaluate(
      ({ user, token }) => {
        localStorage.setItem('test-auth-user', JSON.stringify(user))
        localStorage.setItem('test-auth-token', token)
      },
      { user: mockUser, token: 'mock-access-token' }
    )

    // 导航到受保护页面，useAuth 会检测到测试模式
    await page.goto('/dashboard')

    await use(page)
  },
})

步骤 4：在测试中使用

// e2e/dashboard.spec.ts
import { test, expect } from './fixtures'

test('dashboard shows user agents', async ({ authenticatedPage }) => {
  // authenticatedPage 已经通过认证，无需登录
  await expect(authenticatedPage.getByText('Test Agent')).toBeVisible()
})

完整代码结构

agent-frontend/
├── e2e/
│   ├── fixtures.ts          # Playwright fixture + mock 数据
│   ├── dashboard.spec.ts    # 测试用例
│   └── ...
├── src/
│   ├── hooks/
│   │   └── useAuth.ts       # 测试模式检测
│   └── stores/
│       └── authStore.ts     # loading: false 默认值
└── playwright.config.ts

关键要点

测试模式 key 使用特殊前缀：test-auth-* 不会在生产环境中出现
检测优先于初始化：先检查 localStorage，再走 Supabase Auth
跳过 auth listener：测试模式下不需要监听 auth state 变化
loading 默认值改为 false：让 hook 显式控制 loading 状态

对类似需求感兴趣？联系合作

TL;DR​

问题现象​

解决方案​

1. 定义 Mock 数据​

2. 设置 API Mock​

3. 在 Fixture 中使用​

4. 测试中使用​

核心技巧​

URL 匹配模式​

读取请求体​

模拟错误场景​

部分放行​

Mock 数据管理​

关键原则​

TL;DR​

问题现象​

解决方案​

1. 创建 Custom Fixture​

2. 测试中使用 authenticatedPage​

3. 对比：未认证 vs 已认证​

核心原理​

addInitScript vs 页面加载后设置​

Fixture 生命周期​

完整配置​

扩展：结合 API Mock​

关键原则​

TL;DR​

问题现象​

根因​

1. Supabase Auth 是异步初始化的​

2. Zustand Store 的默认值问题​

3. OAuth 流程无法自动化​

解决方案​

步骤 1：在 useAuth hook 中添加测试模式检测​

步骤 2：修改 Zustand Store 默认值​

步骤 3：在 Playwright Fixture 中注入测试认证​

步骤 4：在测试中使用​

完整代码结构​

关键要点​

TL;DR

问题现象

解决方案

1. 定义 Mock 数据

2. 设置 API Mock

3. 在 Fixture 中使用

4. 测试中使用

核心技巧

URL 匹配模式

读取请求体

模拟错误场景

部分放行

Mock 数据管理

关键原则

TL;DR

问题现象

解决方案

1. 创建 Custom Fixture

2. 测试中使用 authenticatedPage

3. 对比：未认证 vs 已认证

核心原理

addInitScript vs 页面加载后设置

Fixture 生命周期

完整配置

扩展：结合 API Mock

关键原则

TL;DR

问题现象

根因

1. Supabase Auth 是异步初始化的

2. Zustand Store 的默认值问题

3. OAuth 流程无法自动化

解决方案

步骤 1：在 useAuth hook 中添加测试模式检测

步骤 2：修改 Zustand Store 默认值

步骤 3：在 Playwright Fixture 中注入测试认证

步骤 4：在测试中使用

完整代码结构

关键要点