现代 Web 前端测试体系完全指南：从单元测试到 E2E 的工程化实践

{
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{css,md,json}": ["prettier --write"]
}

export function formatPrice(amount: number, currency = 'CNY'): string {
  if (Number.isNaN(amount) || amount < 0) return '¥0.00'
  return new Intl.NumberFormat('zh-CN', {
    style: 'currency',
    currency,
  }).format(amount)
}

// tests/unit/formatPrice.test.ts
import { describe, expect, it } from 'vitest'
import { formatPrice } from '@/utils/formatPrice'

describe('formatPrice', () => {
  it('应当正确格式化标准金额', () => {
    expect(formatPrice(1234.56)).toBe('¥1,234.56')
  })

  it('遇到 NaN 或负数时应当安全降级返回零值', () => {
    expect(formatPrice(NaN)).toBe('¥0.00')
    expect(formatPrice(-50)).toBe('¥0.00')
  })
})

import { useCallback, useState } from 'react'

export function useCounter(initialValue = 0) {
  const [count, setCount] = useState(initialValue)
  const increment = useCallback(() => setCount((c) => c + 1), [])
  const decrement = useCallback(() => setCount((c) => c - 1), [])
  return { count, increment, decrement }
}

// tests/unit/useCounter.test.ts
import { act, renderHook } from '@testing-library/react'
import { describe, expect, it } from 'vitest'
import { useCounter } from '@/hooks/useCounter'

describe('useCounter', () => {
  it('应当支持正确递增与递减状态', () => {
    const { result } = renderHook(() => useCounter(10))

    expect(result.current.count).toBe(10)

    act(() => {
      result.current.increment()
    })
    expect(result.current.count).toBe(11)

    act(() => {
      result.current.decrement()
    })
    expect(result.current.count).toBe(10)
  })
})

import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/user', () => {
    return HttpResponse.json({
      id: 'usr_123',
      name: 'Miles Pan',
      email: '[email protected]',
    })
  }),

  http.post('/api/login', async ({ request }) => {
    const body = (await request.json()) as { username?: string }
    if (body.username === 'admin') {
      return HttpResponse.json({ token: 'fake_jwt_token' })
    }
    return new HttpResponse(null, { status: 401 })
  }),
]

import { useEffect, useState } from 'react'

export function UserProfileCard() {
  const [user, setUser] = useState<{ name: string } | null>(null)
  const [error, setError] = useState(false)

  useEffect(() => {
    fetch('/api/user')
      .then((res) => {
        if (!res.ok) throw new Error('Fetch failed')
        return res.json()
      })
      .then((data) => setUser(data))
      .catch(() => setError(true))
  }, [])

  if (error) return <div role="alert">加载用户信息失败</div>
  if (!user) return <div>加载中...</div>
  return <h2>欢迎回来，{user.name}</h2>
}

// tests/components/UserProfileCard.test.tsx
import { render, screen, waitFor } from '@testing-library/react'
import { describe, expect, it } from 'vitest'
import { UserProfileCard } from '@/components/UserProfileCard'

describe('<UserProfileCard />', () => {
  it('应当在接口请求成功后展示用户名', async () => {
    render(<UserProfileCard />)

    expect(screen.getByText('加载中...')).toBeInTheDocument()

    await waitFor(() => {
      expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent('欢迎回来，Miles Pan')
    })
  })
})

import { MatchersV3, PactV3 } from '@pact-foundation/pact'
import { describe, expect, it } from 'vitest'

// 1. 初始化 Pact Mock 服务提供者
const provider = new PactV3({
  consumer: 'FrontendWebApp',
  provider: 'UserService',
  dir: './tests/contracts', // 契约产物保存目录
})

describe('用户服务 API 契约校验', () => {
  it('验证 /api/users/:id 契约约束', async () => {
    // 2. 声明前端对 API 的请求预期与响应数据结构
    provider
      .given('用户 123 存在')
      .uponReceiving('获取用户 123 详细信息的请求')
      .withRequest({
        method: 'GET',
        path: '/api/users/123',
        headers: {
          Accept: 'application/json',
        },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': 'application/json; charset=utf-8' },
        body: {
          id: MatchersV3.string('123'),
          username: MatchersV3.string('Miles Pan'),
          email: MatchersV3.regex(
            '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
            '[email protected]'
          ),
          role: MatchersV3.equal('admin'),
        },
      })

    // 3. 执行契约校验
    await provider.executeTest(async (mockServer) => {
      const response = await fetch(`${mockServer.url}/api/users/123`, {
        headers: { Accept: 'application/json' },
      })
      const data = await response.json()

      expect(response.status).toBe(200)
      expect(data.username).toBe('Miles Pan')
    })
  })
})

import { z } from 'zod'

// 定义接口运行期强契约
export const UserResponseSchema = z.object({
  id: z.string(),
  username: z.string(),
  email: z.string().email(),
  avatarUrl: z.string().url().optional(),
  status: z.enum(['active', 'suspended', 'pending']),
})

export type UserResponse = z.infer<typeof UserResponseSchema>

// 带契约校验的通用请求封装
export async function fetchUserProfile(userId: string): Promise<UserResponse> {
  const response = await fetch(`/api/users/${userId}`)
  if (!response.ok) throw new Error(`HTTP Error ${response.status}`)

  const rawData = await response.json()

  // 运行时 Strict Parse：如果后端返回了未约定的字段或破坏性类型改动，立刻触发格式化异常
  const parseResult = UserResponseSchema.safeParse(rawData)
  if (!parseResult.success) {
    console.error('API 契约破裂异常:', parseResult.error.format())
    throw new Error('API 响应数据违背了前端契约规范')
  }

  return parseResult.data
}

import type { Locator, Page } from '@playwright/test'

export class PostsPage {
  readonly page: Page
  readonly heading: Locator
  readonly searchInput: Locator
  readonly postCards: Locator

  constructor(page: Page) {
    this.page = page
    this.heading = page.getByRole('heading', { level: 1 })
    this.searchInput = page.getByPlaceholder(/搜索文章/i)
    this.postCards = page.locator('article')
  }

  async goto() {
    await this.page.goto('/posts/')
  }

  async search(query: string) {
    await this.searchInput.fill(query)
  }
}

// tests/e2e/posts.spec.ts
import { expect, test } from '@playwright/test'
import { PostsPage } from './pom/PostsPage'

test.describe('文章列表页 E2E', () => {
  test('应当能正常浏览并搜索文章', async ({ page }) => {
    const postsPage = new PostsPage(page)
    await postsPage.goto()

    await expect(postsPage.heading).toBeVisible()
    await expect(postsPage.postCards.first()).toBeVisible()
  })
})

import { expect, test } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'

test.describe('网站无障碍 (a11y) 自动化合规扫描', () => {
  test('首页应当零 WCAG 严重违规项', async ({ page }) => {
    await page.goto('/')

    // 执行 axe 引擎静态与 DOM 规则审计
    const accessibilityScanResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag21a', 'wcag21aa']) // 指定 WCAG 2.1 AA 级标准
      .disableRules(['color-contrast']) // 可选：排除特定提示级规则
      .analyze()

    // 违规结果断言
    expect(accessibilityScanResults.violations).toEqual([])
  })
})

{
  "ci": {
    "collect": {
      "staticDistDir": "./dist",
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.85 }],
        "categories:accessibility": ["error", { "minScore": 0.9 }],
        "first-contentful-paint": ["error", { "maxNumericValue": 2000 }],
        "interactive": ["error", { "maxNumericValue": 3500 }]
      }
    }
  }
}

import { render, screen } from '@testing-library/react'
import { describe, expect, it } from 'vitest'
import { CommentItem } from '@/components/CommentItem'

describe('安全注入防范测试', () => {
  it('应当妥善转义恶意的 XSS Script 脚本标签', () => {
    const maliciousPayload = `<script>alert('xss')</script><img src=x onerror="window.__xss__=true" />`

    render(<CommentItem content={maliciousPayload} />)

    // 断言 DOM 中绝不会执行脚本注入
    expect(window.__xss__).toBeUndefined()
    expect(screen.getByText(/<script>/i)).toBeInTheDocument()
  })
})