mini-starter/packages/e2e-test-utils/docs/DEVELOPER_CHECKLIST.md

E2E 测试工具包 - 开发者自查清单

本清单基于 Epic 1 和 Epic 2 的回顾总结，确保代码质量和一致性。 参见: _bmad-output/implementation-artifacts/epic-1-retrospective.md, epic-2-retrospective.md

---

代码质量

JSDoc 文档

• [ ] 所有导出函数都有完整的 JSDoc

  • 包含 @param - 参数说明
  • 包含 @returns - 返回值说明
  • 包含 @throws {E2ETestError} - 可能抛出的错误
  • 包含 @example - 使用示例

• [ ] 内部函数使用 @internal 标记

  /**
  * @internal
  * 内部辅助函数，不导出
  */
  

错误处理

• [ ] 使用 E2ETestError 而非原生 Error

  // ✅ 正确
  throwError({
  operation: 'selectRadixOption',
  target: label,
  expected: value,
  });
  
  // ❌ 错误
  throw new Error('Select failed');
  

---

选择器策略

文本匹配

• [ ] 使用 :text-is() 而非 :has-text() 进行精确匹配

  // ✅ 精确匹配
  page.locator(`.option:text-is("广东省")`)
  
  // ❌ 部分匹配 - 可能误选
  page.locator(`.option:has-text("广东省")`)
  

DOM 结构验证

• DOM 结构假设必须基于真实组件验证
  • 不能基于理想模型开发工具
  • 必须在真实 Radix UI 组件上验证
  • 单元测试无法发现真实 DOM 问题，必须添加集成测试

---

配置和超时

配置对象

• [ ] 配置对象继承 BaseOptions

  export interface AsyncSelectOptions extends BaseOptions {
  waitForOption?: boolean;
  waitForNetworkIdle?: boolean;
  }
  

超时配置

• [ ] 超时值使用 DEFAULT_TIMEOUTS 常量

  import { DEFAULT_TIMEOUTS } from './constants.js';
  
  await page.waitForTimeout(DEFAULT_TIMEOUTS.static);
  

• [ ] 网络空闲等待使用用户自定义的超时值

  // ✅ 正确 - 使用用户自定义的 timeout
  await page.waitForLoadState('networkidle', {
  timeout: options.timeout ?? DEFAULT_TIMEOUTS.async
  });
  
  // ❌ 错误 - 使用固定的 networkIdle 超时
  await page.waitForLoadState('networkidle', {
  timeout: DEFAULT_TIMEOUTS.networkIdle
  });
  

---

DOM 操作

避免使用 page.evaluate

• [ ] 避免使用 page.evaluate() 处理 DOM 操作

  // ❌ 不推荐 - TypeScript 类型问题
  const text = await page.evaluate(el => el.textContent, element);
  
  // ✅ 推荐 - 使用 Playwright API
  const text = await element.textContent();
  
  // ✅ 推荐 - 使用 locator 获取多个文本
  const texts = await page.locator(selector).allTextContents();
  

---

测试策略（Epic 2 关键发现）

集成测试重要性

• [ ] 单元测试无法发现真实 DOM 结构问题

  • 单元测试使用模拟 DOM，覆盖率 93.65% 仍然无法发现 DOM 问题
  • 必须添加集成测试级别

• [ ] 使用真实组件验证工具

  • 使用真实的 Radix UI 组件进行测试
  • 不能仅依赖模拟 DOM

---

ESLint 检查

运行以下命令确保代码符合规范：

# 类型检查
pnpm typecheck

# ESLint 检查
pnpm lint

# 单元测试
pnpm test:unit

# 覆盖率检查
pnpm test:coverage

---

提交前检查

在提交代码或创建 PR 之前，确保：

• 所有 ESLint 检查通过
• 所有单元测试通过
• 测试覆盖率 ≥ 80%
• 类型检查通过（无 any 类型）
• 所有导出函数有完整 JSDoc
• 错误处理使用 E2ETestError
• 选择器使用精确匹配 :text-is()
• 超时值使用 DEFAULT_TIMEOUTS

---

快速参考

常见错误模式

模式	正确	错误
文本匹配	:text-is("value")	:has-text("value")
错误处理	E2ETestError	Error
DOM 操作	element.textContent()	page.evaluate()
超时配置	DEFAULT_TIMEOUTS.static	2000 (硬编码)
网络等待	options.timeout	DEFAULT_TIMEOUTS.networkIdle

相关文档

• 架构文档: _bmad-output/planning-artifacts/architecture.md
• Epic 1 回顾: _bmad-output/implementation-artifacts/epic-1-retrospective.md
• Epic 2 回顾: _bmad-output/implementation-artifacts/epic-2-retrospective.md