速查表

DOM 测试库 中所有导出函数的简短指南

查询

	无匹配	1 个匹配	1 个以上匹配	异步？
getBy	抛出异常	返回	抛出异常	否
findBy	抛出异常	返回	抛出异常	是
queryBy	null	返回	抛出异常	否
getAllBy	抛出异常	数组	数组	否
findAllBy	抛出异常	数组	数组	是
queryAllBy	[]	数组	数组	否

ByLabelText 通过标签或 aria-label 文本内容查找
- getByLabelText
- queryByLabelText
- getAllByLabelText
- queryAllByLabelText
- findByLabelText
- findAllByLabelText
ByPlaceholderText 通过输入占位符值查找
- getByPlaceholderText
- queryByPlaceholderText
- getAllByPlaceholderText
- queryAllByPlaceholderText
- findByPlaceholderText
- findAllByPlaceholderText
ByText 通过元素文本内容查找
- getByText
- queryByText
- getAllByText
- queryAllByText
- findByText
- findAllByText
ByDisplayValue 通过表单元素的当前值查找
- getByDisplayValue
- queryByDisplayValue
- getAllByDisplayValue
- queryAllByDisplayValue
- findByDisplayValue
- findAllByDisplayValue
ByAltText 通过 img 的 alt 属性查找
- getByAltText
- queryByAltText
- getAllByAltText
- queryAllByAltText
- findByAltText
- findAllByAltText
ByTitle 通过 title 属性或 svg title 标签查找
- getByTitle
- queryByTitle
- getAllByTitle
- queryAllByTitle
- findByTitle
- findAllByTitle
ByRole 通过 aria 角色查找
- getByRole
- queryByRole
- getAllByRole
- queryAllByRole
- findByRole
- findAllByRole
ByTestId 通过 data-testid 属性查找
- getByTestId
- queryByTestId
- getAllByTestId
- queryAllByTestId
- findByTestId
- findAllByTestId

异步

参见异步 API。记住在你的测试中对异步函数的结果使用 await 或 .then()!

waitFor (Promise) 在函数停止抛出异常或超时之前重试函数
waitForElementToBeRemoved (Promise) 在函数不再返回 DOM 节点之前重试函数

自 v7.0.0 起已弃用
wait (Promise) 在函数停止抛出异常或超时之前重试函数
waitForElement (Promise) 在函数返回元素或元素数组之前重试函数。findBy 和 findAllBy 查询是异步的，会在查询成功返回或查询超时时重试；它们包装了 waitForElement
waitForDomChange (Promise) 每次 DOM 发生改变时重试函数

事件

参见 fireEvent 的注意事项，事件 API

fireEvent 触发 DOM 事件：fireEvent(node, event)
fireEvent.* 默认事件类型的帮助器
- click fireEvent.click(node)
- 参见所有支持的事件

其他

参见在元素内查询，配置 API

within 获取节点并返回一个包含所有绑定到该节点的查询的对象（用于从 React 测试库 的渲染方法返回查询）：within(node).getByText("hello")
configure 更改全局选项：configure({testIdAttribute: 'my-data-test-id'})

文本匹配选项

给定以下 HTML

<div>Hello World</div>

将找到 div

// Matching a string:
getByText(container, 'Hello World') // full string match
getByText(container, 'llo Worl', {exact: false}) // substring match
getByText(container, 'hello world', {exact: false}) // ignore case

// Matching a regex:
getByText(container, /World/) // substring match
getByText(container, /world/i) // substring match, ignore case
getByText(container, /^hello world$/i) // full string match, ignore case
getByText(container, /Hello W?oRlD/i) // advanced regex

// Matching with a custom function:
getByText(container, (content, element) => content.startsWith('Hello'))

给定一个在一段时间后更新页面的按钮

test('loads items eventually', async () => {
  // Click button
  fireEvent.click(getByText(node, 'Load'))

  // Wait for page to update with query text
  const items = await findAllByText(node, /Item #[0-9]: /)
  expect(items).toHaveLength(10)
})

查询​

异步​

事件​

其他​

文本匹配选项​

查询

异步

事件

其他

文本匹配选项