Testing Library 如何将getByText的搜索范围限制在指定DOM父节点下

根据React Testing Library的API定义，getByText原生支持传入自定义的搜索根节点作为第一个参数。日常用screen.getByText()的时候会全DOM搜索，本质是因为screen对象已经自动把这个根节点固定为整个文档的document.body，相当于跳过了手动传容器的步骤（和官方文档里的注释逻辑完全一致）。

要缩小搜索范围，只需要主动指定这个根容器为你需要的父DOM节点就行，常用实现方式有两种：

• 直接在拿到的父DOM节点实例上调用查询方法
  RTL会给测试环境内所有DOM元素实例挂载全套查询方法，不需要依赖全局screen。只要你先获取到要作为搜索边界的父节点引用，直接在这个节点上调用getByText即可，搜索范围会自动限定在该节点的子树内。
  示例代码：

  // 先定位到作为搜索边界的父节点，比如页面的header区域
  const headerEl = screen.getByRole('banner');
  // 直接在该节点上查找文本，不会检索节点外部的DOM内容
  const aboutNavLink = headerEl.getByText(/about/i);
  

  这种写法下，哪怕页面其他位置（比如页脚、侧边栏）还有同样匹配/about/i的文本，也不会干扰当前查找，查询只会在headerEl的子节点范围内匹配。
• 手动导入原生查询函数传入容器参数
  如果你不想依赖元素实例上挂载的方法，也可以从核心库直接导入基础查询函数，手动把父DOM节点作为第一个参数传入：

  import { getByText } from '@testing-library/dom';
  // 拿到作为搜索边界的侧边栏节点
  const sidebarEl = screen.getByRole('complementary');
  // 手动指定搜索容器为侧边栏节点
  const sidebarAboutItem = getByText(sidebarEl, /about/i);
  

常见误区提醒：

• 不要尝试给全局screen的查询方法传容器参数，screen的API已经固定绑定了文档根节点为搜索边界，额外传入的参数只会被当成匹配选项解析，不会改变搜索范围。
• 不要寄希望于用options里的selector参数实现范围限制：selector只是对已经在全树匹配到的文本元素做CSS选择器过滤，本质还是全树搜索，一旦页面其他位置出现相同匹配文本，依然会抛出“匹配到多个元素”的错误，达不到精准限范围的效果。

内容的提问来源于stack exchange，提问作者Unknown developer