DOM Testing Library 中 getByText 与段落元素查询的最佳实践

问题背景

在 DOM Testing Library 的最新版本中，当开发者尝试使用 getByText 方法查询段落元素（<p> 标签）时，如果启用了 throwSuggestions 配置，会遇到一个特殊的错误提示。这个提示建议使用 getByRole('paragraph') 作为更好的查询方式，但实际上直接使用这种方式并不能像预期那样工作。

技术解析

现象描述

当开发者按照以下方式编写测试代码时：

render(<p>Hello world!</p>);
const p = screen.getByText('Hello world!');

会收到错误提示："A better query is available, try this: getByRole('paragraph')"

然而，如果尝试按照提示使用：

getByRole('paragraph', { name: 'Hello world!' })

这会导致另一个错误："Unable to find an accessible element with the role 'paragraph' and name 'Hello world!'"

根本原因

这个问题源于 W3C ARIA 规范中对段落角色的特殊规定。根据规范，段落（paragraph）角色属于"name from prohibited"类别，意味着不能通过常规的 name 属性来识别这类元素。DOM Testing Library 遵循这一规范，因此在尝试使用 name 参数查询段落时会失败。

解决方案

推荐方法

目前最推荐的解决方案是使用以下查询方式：

getByRole('paragraph', { 
  name: (name, element) => element.textContent === 'Hello world!' 
})

这种写法虽然略显冗长，但它：

1. 遵循了 ARIA 规范
2. 保持了测试的可读性
3. 能够准确匹配目标元素

实用技巧

对于大型项目，可以创建一个全局辅助函数来简化查询：

// 在测试全局设置文件中
global.getParagraphByText = (text) => {
  return getByRole('paragraph', { 
    name: (name, element) => element.textContent === text 
  });
};

// 在测试中使用
global.getParagraphByText('Hello World');

这种方法既保持了代码的整洁性，又遵循了最佳实践。

深入理解

为什么会出现这种情况

DOM Testing Library 的设计理念是鼓励开发者使用最接近用户实际交互方式的查询方法。对于大多数元素，这意味着优先使用角色（role）查询。然而，段落元素在可访问性规范中比较特殊，导致了这种看似矛盾的情况。

设计权衡

虽然 getByText 方法在功能上完全能够满足需求，但 DOM Testing Library 仍然推荐使用角色查询，这是为了：

1. 保持一致性：统一使用角色查询有助于形成一致的测试风格
2. 可维护性：角色查询通常更能适应 UI 结构的变化
3. 可访问性：强制开发者考虑元素的语义角色

最佳实践建议

1. 对于简单项目：可以考虑继续使用 getByText 并忽略相关提示
2. 对于严格遵循可访问性的项目：使用推荐的 getByRole 方式
3. 对于大型项目：创建自定义查询辅助函数以提高代码可读性
4. 团队协作项目：在团队内部文档中明确段落元素的查询规范

总结

DOM Testing Library 的这一行为虽然初看起来有些反直觉，但实际上是为了推动开发者编写更具可访问性和健壮性的测试代码。理解背后的设计理念和规范要求，能够帮助开发者更好地利用这个强大的测试工具。

通过采用本文介绍的模式和技巧，开发者可以在保持代码质量的同时，有效地解决段落元素查询的特殊情况。