blank/docs/architecture/testing-strategy.md

测试策略

测试框架和工具

单元测试

Vitest 3.2.4

• 快速的测试运行器，专为Vite优化
• 支持TypeScript和ES模块
• 内置代码覆盖率报告
• 快照测试支持

Testing Library 16.3.0

• React Testing Library: 组件测试
• DOM Testing Library: DOM操作测试
• 用户行为导向的测试方法

端到端测试

Playwright 1.55.0

• 跨浏览器自动化测试
• 支持Chromium、Firefox、WebKit
• 自动等待和断言
• 截图和视频录制

测试脚本配置

{
  "scripts": {
    "test": "vitest",
    "test:coverage": "vitest --coverage",
    "test:e2e": "playwright test",
    "test:e2e:chromium": "playwright test --project=chromium",
    "test:e2e:headed": "playwright test --headed"
  }
}

测试层级结构

单元测试 (Unit Tests)

测试范围

• 工具函数 (src/common/utils.ts)
• 自定义Hooks (src/common/hooks.ts)
• 管理器类 (src/manager/)
• 工具类和方法

测试位置

src/
├── common/
│   └── __tests__/
│       └── utils.test.ts
├── manager/
│   └── __tests__/
│       ├── rtc.test.ts
│       ├── rtm.test.ts
│       └── stt.test.ts
└── components/
    └── __tests__/
        └── *.test.tsx

集成测试 (Integration Tests)

测试范围

• 组件与状态管理的集成
• 管理器间的协作
• API调用和响应处理
• 事件系统集成

测试位置

tests/
├── integration/
│   ├── store-integration.test.ts
│   ├── manager-integration.test.ts
│   └── api-integration.test.ts
└── __mocks__/
    └── agora-mocks.ts

端到端测试 (E2E Tests)

测试范围

• 完整的用户流程
• 音视频功能验证
• 语音转文字功能
• 多语言支持
• 错误处理场景

测试位置

e2e/
├── specs/
│   ├── login.spec.ts
│   ├── home.spec.ts
│   ├── stt-functionality.spec.ts
│   └── error-handling.spec.ts
├── pages/
│   ├── login.page.ts
│   └── home.page.ts
└── fixtures/
    └── test-data.ts

测试策略实施

核心功能测试重点

RTC管理器测试

• 音视频轨道创建和发布
• 用户加入/离开频道
• 网络质量监控
• 错误恢复机制

RTM管理器测试

• 实时消息发送和接收
• 用户状态同步
• 频道元数据管理
• 连接状态处理

STT管理器测试

• 语音转文字任务启动/停止
• 多语言转录和翻译
• 任务状态管理
• API错误处理

测试数据管理

模拟数据

// tests/__mocks__/agora-mocks.ts
export const mockRtcClient = {
  join: vi.fn(),
  publish: vi.fn(),
  leave: vi.fn(),
}

export const mockSttResponse = {
  taskId: "test-task-123",
  status: "started",
}

测试夹具

// tests/fixtures/test-data.ts
export const testUserInfo = {
  userId: 123456,
  userName: "Test User",
}

export const testChannelConfig = {
  channel: "test-channel",
  appId: "test-app-id",
}

测试环境配置

开发环境测试

• 使用内存数据库和模拟服务
• 快速反馈循环
• 热重载测试运行

CI/CD环境测试

• 真实的Agora服务集成
• 多浏览器并行测试
• 性能基准测试

测试最佳实践

测试命名规范

// 描述性测试名称
describe("SttManager", () => {
  it("should start transcription when valid languages provided", () => {
    // 测试实现
  })

  it("should throw error when initialization is missing", () => {
    // 测试实现
  })
})

测试结构

AAA模式 (Arrange-Act-Assert)

it("should handle user join correctly", () => {
  // Arrange
  const manager = new RtcManager()
  const joinConfig = { channel: "test", userId: 123 }

  // Act
  await manager.join(joinConfig)

  // Assert
  expect(manager.client.join).toHaveBeenCalledWith(
    expect.any(String),
    "test",
    expect.any(String),
    123,
  )
})

异步测试处理

it("should handle async operations correctly", async () => {
  // 使用async/await处理异步操作
  const result = await manager.startTranscription()

  expect(result).toBeDefined()
  expect(result.status).toBe("started")
})

测试覆盖率目标

核心功能覆盖率

• 管理器类: 90%+
• 工具函数: 85%+
• 自定义Hooks: 80%+
• 组件逻辑: 70%+

集成测试覆盖率

• 用户流程: 主要路径100%
• 错误场景: 关键错误处理100%
• 边界条件: 重要边界情况覆盖

持续集成

GitHub Actions配置

name: Test Suite
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run test:coverage
      - run: npm run test:e2e

测试报告

• Vitest覆盖率报告
• Playwright测试报告
• 测试结果可视化
• 性能基准比较

故障排除

常见测试问题

异步操作超时

// 增加超时时间
it("should complete within timeout", async () => {
  await expect(manager.longOperation()).resolves.toBeDefined()
}, 10000) // 10秒超时

模拟服务设置

// 正确设置模拟
beforeEach(() => {
  vi.mock("agora-rtc-sdk-ng", () => ({
    createClient: () => mockRtcClient,
  }))
})

调试技巧

• 使用 --headed 模式运行E2E测试
• 利用Playwright的追踪功能
• 检查测试失败时的截图和日志
• 使用Vitest的UI模式进行调试