React测试中使用queryByRole获取input元素报错，该如何解决？

问题场景 #

React组件代码：

function SignUpPage() {
  return (
    <>
      <h1>Sign Up</h1>
      <input name="userName" />
    </>
  );
}
export default SignUpPage;

对应的测试代码：

it("has input", () => {
  render(<SignUpPage />);
  const input = screen.queryByRole("input", { name: /userName/i });
  expect(input).toBeInTheDocument();
});

运行测试时抛出错误：

received value must be an HTMLElement or an SVGElement.
Received has value: null

问题原因 #

queryByRole的第一个参数需要传入ARIA role值，而非HTML标签名。HTML的<input>元素并没有名为input的ARIA role，不同类型的input对应不同的默认role：

• 文本类input（type="text"/"password"/"search"等）：默认role为textbox
• 复选框：checkbox
• 单选框：radio
• 按钮型input：button

你传入的"input"不是合法的role值，因此无法找到对应元素，返回null导致测试报错。

解决方案 #

1. 使用正确的ARIA role值

针对文本类型的input，使用textbox作为role参数：

it("has input", () => {
  render(<SignUpPage />);
  const input = screen.queryByRole("textbox", { name: /username/i });
  expect(input).toBeInTheDocument();
});

2. 优化组件的可访问性（推荐）

为input添加关联的<label>标签或aria-label属性，让name参数的匹配更准确，同时提升页面可访问性：

• 添加label的组件代码：

function SignUpPage() {
  return (
    <>
      <h1>Sign Up</h1>
      <label htmlFor="userName">Username</label>
      <input id="userName" name="userName" />
    </>
  );
}

此时测试代码无需修改（依然使用textbox role），name: /username/i会匹配label的文本内容。

• 添加aria-label的组件代码：

function SignUpPage() {
  return (
    <>
      <h1>Sign Up</h1>
      <input name="userName" aria-label="Username" />
    </>
  );
}

测试代码同样使用textbox role，name参数会匹配aria-label的内容。

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