inula/packages/testing_library

@openinula/testing-library 设计文档

1. 项目概述

@openinula/testing-library 是一个为 openInula 应用程序设计的测试工具库。它提供了一套简单、直观的 API，帮助开发人员编写有效的、可维护的测试代码。该库基于用户行为的测试方法，而不是依赖于组件的内部实现细节。

2. 设计目标

• 提供与 openInula 生态系统无缝集成的测试工具
• 支持测试 Inula 组件的渲染、交互和状态管理
• 提供简单、直观的 API，易于学习和使用
• 支持异步测试和断言
• 提供详细的错误消息，便于定位和修复测试失败
• 保持与 @testing-library/react 相似的 API，以便于用户迁移

3. 核心组件

3.1 render 函数

render 函数用于将 Inula 组件渲染到测试环境中。它返回一个对象，包含查询方法和其他有用的属性。

3.2 查询函数

提供多种查询函数，如 getByText、getByRole、getByLabelText 等，用于在渲染的组件中查找元素。

3.3 fireEvent

fireEvent 对象提供了模拟用户交互的方法，如点击、输入等。

3.4 act

act 函数用于包装可能导致组件状态更新的操作，确保在断言之前完成所有更新。

3.5 cleanup

cleanup 函数用于在每个测试后清理渲染的组件。

4. 技术实现

4.1 依赖

• openinula: Inula 核心库
• @testing-library/dom: 提供底层 DOM 测试功能

4.2 主要模块

• src/index.js: 库的主入口，导出所有公共 API
• src/render.js: 实现 render 函数
• src/queries.js: 实现各种查询函数
• src/fire-event.js: 实现 fireEvent 对象
• src/act-compat.js: 实现 act 函数
• src/config.js: 处理库的配置

4.3 自动清理机制

通过 afterEach 或 teardown 钩子自动调用 cleanup 函数，除非用户显式禁用。

4.4 Act 环境管理

使用 getIsInulaActEnvironment 和 setInulaActEnvironment 函数管理 Act 环境。

5. API 设计

5.1 render

function render(ui, options) -> {
  container,
  baseElement,
  debug,
  unmount,
  rerender,
  asFragment,
  ...queries
}

5.2 查询函数

getByText(text) -> Element
getByRole(role) -> Element
getByLabelText(label) -> Element
getByTestId(testId) -> Element
// ... 其他查询函数

5.3 fireEvent

fireEvent.click(element)
fireEvent.change(element, { target: { value: 'new value' } })
// ... 其他事件

5.4 act

act(() => {
  // 执行可能导致组件更新的操作
})

5.5 cleanup

cleanup()

6. 配置选项

通过 configure 函数提供全局配置选项，如：

configure({
  inulaStrictMode: true,
  // ... 其他配置选项
})

7. 测试策略

• 单元测试：为每个主要模块编写单元测试
• 集成测试：测试各个模块的集成
• 端到端测试：使用库测试实际的 Inula 组件

8. 文档和示例

• 提供详细的 API 文档
• 提供常见用例的示例代码
• 编写一个全面的 README.md 文件

9. 未来扩展

• 添加更多的查询方法
• 支持更多的事件类型
• 提供自定义渲染器的选项
• 集成 Inula 特定的测试工具（如果有）

10. 兼容性考虑

• 确保与不同版本的 openInula 兼容
• 考虑浏览器兼容性问题

11. 性能优化

• 优化渲染性能
• 减少不必要的 DOM 操作

12. 安全性考虑

• 避免在测试中暴露敏感信息
• 确保测试环境的隔离性