react-testing-library的name查询选项含义及匹配失败问题

你遇到的查询失效问题，核心是对getByRole查询中name参数的匹配规则认知有误，具体规则和解决方案如下：

核心匹配规则 #

getByRole的name参数匹配的是元素的可访问名称（Accessible Name），而非HTML原生的name属性，可访问名称的计算优先级从高到低为：

• 优先读取元素的aria-label属性值
• 其次读取aria-labelledby属性关联的元素文本内容
• 最后才会读取元素本身的可见文本、关联label标签的文本、输入框的placeholder等内容

问题原因 #

你给出的按钮代码显式设置了aria-label="Close"，按照优先级规则，该按钮的可访问名称为Close，而非内部的Create new文本，因此用/Create new/gi匹配自然会失败。

额外提示：当前按钮的aria-label属性值和可见文本不一致，本身属于可访问性缺陷，读屏软件会播报Close，但用户视觉上看到的是Create new，会造成视障用户使用困惑，建议优先修正组件的属性设置。

可行的查询方案 #

如果暂时不修改组件属性，可以用以下方式查询到目标按钮：

1. 按可访问名称匹配：

const createNewButton = screen.getByRole('button', {
    name: /Close/gi,
});

2. 自定义匹配函数，直接匹配元素文本内容：

const createNewButton = screen.getByRole('button', {
    name: (_, element) => element.textContent.includes('Create new')
});

3. 先匹配文本再定位按钮元素：

const createNewButton = screen.getByText(/Create new/gi).closest('button');

常见认知修正 #

你之前理解的「input类元素的name可以指代id、name属性」是不准确的，原生id、name属性不会直接作为可访问名称参与匹配，只有当input通过for属性关联了label标签，或者显式设置了aria-label/aria-labelledby属性时，才会用对应内容作为可访问名称。

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