React Native Testing Library 查询指南：如何选择合适的查询方法

前言

在 React Native 应用测试中，查询元素是测试编写的基础环节。React Native Testing Library 提供了丰富的查询方法，但面对众多选项，开发者可能会感到困惑。本文将深入解析各种查询方法的特点和使用场景，帮助您为测试场景选择最合适的查询方式。

查询方法的结构

每个查询方法都由两部分组成：查询变体(variant)和查询谓词(predicate)，中间用 by 连接。

例如在 getByRole() 中：

• getBy* 是查询变体
• *ByRole 是查询谓词

查询变体详解

查询变体决定了匹配元素的数量预期和返回类型，是测试断言的基础。

主要查询变体类型

1. getBy*

   • 预期：必须且只能匹配一个元素
   • 返回类型：ReactTestInstance
   • 是否异步：否
   • 使用场景：最常用，当确定只有一个匹配元素时

2. getAllBy*

   • 预期：匹配一个或多个元素
   • 返回类型：Array<ReactTestInstance>
   • 是否异步：否
   • 使用场景：列表项、重复元素等情况

3. queryBy*

   • 预期：匹配零个或一个元素
   • 返回类型：ReactTestInstance | null
   • 是否异步：否
   • 使用场景：验证元素不存在的情况

4. queryAllBy*

   • 预期：不进行数量断言
   • 返回类型：Array<ReactTestInstance>
   • 是否异步：否
   • 使用场景：自定义测试工具开发

5. findBy*

   • 预期：必须且只能匹配一个元素
   • 返回类型：Promise<ReactTestInstance>
   • 是否异步：是
   • 使用场景：异步加载的元素

6. findAllBy*

   • 预期：匹配一个或多个元素
   • 返回类型：Promise<Array<ReactTestInstance>>
   • 是否异步：是
   • 使用场景：异步加载的多个元素

查询变体选择指南

1. 优先使用 getBy*：适用于大多数只有一个匹配元素的场景
2. 异步场景使用 findBy*：等待元素出现在组件树中
3. 多个元素使用 getAllBy*：列表等有多个相同元素的场景
4. 验证不存在使用 queryBy*：配合断言如 not.toBeOnTheScreen()
5. 避免常规测试中使用 queryAllBy*：缺乏数量断言，主要用于工具开发

查询谓词详解

查询谓词决定了如何匹配元素，反映了测试意图和用户交互方式。

主要查询谓词类型

1. ByRole

   • 适用元素：所有宿主元素
   • 检查属性：role, accessibilityRole 等
   • 特点：语义化查询，推荐首选

2. ByLabelText

   • 适用元素：所有宿主元素
   • 检查属性：accessibilityLabel 等
   • 特点：通过可访问性标签查询

3. ByDisplayValue

   • 适用元素：TextInput
   • 检查属性：value, defaultValue
   • 特点：查询输入框的当前值

4. ByPlaceholderText

   • 适用元素：TextInput
   • 检查属性：placeholder
   • 特点：查询输入框的占位文本

5. ByText

   • 适用元素：Text
   • 检查属性：children (文本内容)
   • 特点：直接查询文本内容

6. ByHintText

   • 适用元素：所有宿主元素
   • 检查属性：accessibilityHint
   • 特点：查询辅助提示文本

7. ByTestId

   • 适用元素：所有宿主元素
   • 检查属性：testID
   • 特点：通过测试ID查询，不推荐常规使用

查询谓词选择指南

1. 首选 ByRole 查询

ByRole 是最推荐的查询方式，它基于元素的语义角色，可以配合 name 选项精确查询：

// 带有"Start"文本的按钮
getByRole("button", { name: "Start" })

// 静音模式开关
getByRole("switch", { name: "Silent Mode" })

// 设置页面标题
getByRole("header", { name: "Settings" })

// 错误消息
getByRole("alert", { name: /Not logged in/ })

常见角色包括：

• button - 按钮
• switch - 开关
• header - 标题
• alert - 错误提示
• image - 图片
• 等等

2. 文本输入框的特殊查询

由于 TextInput 没有特定角色，可采用以下方式查询：

// 通过标签查询
getByLabelText("用户名")

// 通过占位符查询
getByPlaceholderText("请输入密码")

// 通过当前值查询
getByDisplayValue("已输入文本")

3. 其他可访问性查询

// 通过文本内容查询
getByText("提交")

// 通过辅助提示查询
getByHintText("双击可编辑")

4. 最后考虑 TestID 查询

getByTestId("login-button")

虽然灵活，但不反映用户体验，建议仅在必要时使用。

最佳实践总结

1. 查询变体选择：根据元素数量和出现时机选择合适的变体
2. 查询谓词优先级：ByRole > 文本输入查询 > 其他可访问性查询 > TestID
3. 语义化查询：优先使用反映用户视角的查询方式
4. 异步处理：正确使用 findBy* 处理异步场景
5. 避免过度依赖 TestID：保持测试与用户体验一致

通过遵循这些原则，您可以编写出更健壮、更易维护的 React Native 组件测试。记住，好的测试应该像用户一样与您的应用交互，而选择合适的查询方法是实现这一目标的关键。