React 测试库 - API

React Testing Library也会重新导出 DOM Testing Library中的所有内容 如以下方法：

render

function render(
  ui: React.ReactElement,
  options?: {
    /* You won't often use this, expand below for docs on options */
  },
): RenderResult

渲染到到 document.body 的容器中。

import {render} from '@testing-library/react'

render(
)

import {render} from '@testing-library/react'
import '@testing-library/jest-dom'

test('renders a message', () => {
  const {asFragment, getByText} = render()
  expect(getByText('Hello, world!')).toBeInTheDocument()
  expect(asFragment()).toMatchInlineSnapshot(`
    
Hello, World!
  `)
})

render Options

你通常不需要指定选项，但如果你需要，以下是你可以作为第二个参数提供给 render 的可用选项。

container

默认情况下，React Testing Library 将创建一个 div，并将其附加到 document.body 上，这就是你的 React 组件将被渲染的地方。如果你通过此选项提供自己的 HTMLElement 容器，它将不会自动附加到 document.body 上。

例如：如果你正在对 TableBody 元素进行单元测试，它不能是 div 的子元素。在这种情况下，你可以指定一个表格作为渲染容器。

const table = document.createElement('table')

const {container} = render(, {
  container: document.body.appendChild(table),
})

baseElement

如果指定了容器，则默认为该容器，否则默认为 document.body。它用作查询的基元素，以及使用debug()时打印的内容。

hydrate

如果hydrate设置为true，则它将使用 ReactDOM.hydrate 进行渲染。如果您使用服务器端渲染并使用 ReactDOM.hydrate 来挂载组件，则这可能会很有用。

legacyRoot

默认情况下，我们将使用对并发功能（即 ReactDOMClient.createRoot ）的支持进行渲染。但是，如果您正在处理需要像React 17中那样渲染的旧版应用程序（即ReactDOM.render），则应将此选项设置为 legacyRoot: true 以启用它。

wrapper

将React组件作为 wrapper 选项传递，以便在内部元素周围渲染它。这对于为常见的数据提供者创建可重用的自定义渲染函数非常有用。请参阅设置示例。

queries

要绑定的查询。除非合并，否则将覆盖从DOM测试库设置的默认集。

// Example, a function to traverse table contents
import * as tableQueries from 'my-table-query-library'
import {queries} from '@testing-library/react'

const {getByRowColumn, getByText} = render(, {
  queries: {...queries, ...tableQueries},
})

查看助手以获取有关如何使用实用程序函数创建自定义查询的指导。

也可以通过遵循自定义渲染指南来全局添加自定义查询。

render Result

render 方法返回一个具有一些属性的对象：

...queries

render 方法的最重要特性就是通过  DOM Testing Library 自动返回查询到的第一个参数绑定到 baseElement 的元素，baseElement 默认为 document.body。请参阅查询以获取完整列表。

示例

const {getByLabelText, queryAllByTestId} = render()

container

你的渲染后的 React 元素（使用 ReactDOM.render 渲染）的包含 DOM 节点。它是一个 div。这是一个常规的 DOM 节点，因此你可以调用 container.querySelector 等来检查子元素。

提示：要获取你渲染的元素的根元素，请使用 container.firstChild。

注意：当那个根元素是一个 React Fragment 时，container.firstChild 将只获取该 Fragment 的第一个子元素，而不是 Fragment 本身。

警告：如果你发现自己正在使用 container 查询渲染后的元素，那么你应该重新考虑！其他查询是为了更具弹性，以适应你正在测试的组件所做的更改。避免使用 container 查询元素！

baseElement

你的 React 元素在容器中渲染的包含 DOM 节点。如果你在 render 的选项中未指定 baseElement，它将默认为 document.body。

当你想要测试的组件在容器 div 外部渲染某些内容时，这很有用，例如，当你想要快照测试你的 portal 组件，该组件直接在 body 中渲染其 HTML。

注意：render 返回的查询将查看 baseElement，因此你可以使用查询来测试你的 portal 组件，而无需使用 baseElement。

debug

注意：建议使用 screen.debug 代替。

这个方法是 console.log(prettyDOM(baseElement)) 的快捷方式。

import React from 'react'
import {render} from '@testing-library/react'

const HelloWorld = () => 
Hello World
const {debug} = render()
debug()
// 

//   
Hello World
// 
// you can also pass an element: debug(getByTestId('messages'))
// and you can pass all the same arguments to debug as you can
// to prettyDOM:
// const maxLengthToPrint = 10000
// debug(getByTestId('messages'), maxLengthToPrint, {highlight: false})

这是一个简单的 prettyDOM 包装器，也来自 DOM 测试库。

rerender

如果你测试执行属性更新的组件以确保属性正确更新（参见“指导原则”部分），那么情况可能会更好。尽管如此，如果你更倾向于在测试中更新已渲染组件的属性，那么此函数可用于更新已渲染组件的属性。

import {render} from '@testing-library/react'

const {rerender} = render()

// re-render the same component with different props
rerender()

unmount

这将导致渲染的组件被卸载。这对于测试当组件从页面中被移除时会发生什么（比如测试你没有留下事件处理器造成内存泄漏）是非常有用的。

这种方法是对 ReactDOM.unmountComponentAtNode 的一个相当小的抽象

import {render} from '@testing-library/react'

const {container, unmount} = render()
unmount()
// your component has been unmounted and now: container.innerHTML === ''

asFragment

返回已渲染组件的 DocumentFragment。如果您需要避免实时绑定并查看组件如何对事件做出反应，这可能会很有用。

import React, {useState} from 'react'
import {render, fireEvent} from '@testing-library/react'

const TestComponent = () => {
  const [count, setCounter] = useState(0)

  return (
     setCounter(count => count + 1)}>
      Click to increase: {count}
    
  )
}

const {getByText, asFragment} = render()
const firstRender = asFragment()

fireEvent.click(getByText(/Click to increase/))

// This will snapshot only the difference between the first render, and the
// state of the DOM after the click event.
// See https://github.com/jest-community/snapshot-diff
expect(firstRender).toMatchDiffSnapshot(asFragment())

cleanup

卸载使用 render() 挂载的React树。

如果你的测试框架（如mocha，Jest或Jasmine）在测试环境中注入了全局afterEach()函数，那么它会被自动调用。否则，你需要在每个测试之后调用 cleanup()。

例如，如果你正在使用 ava 测试框架，那么你需要使用 test.afterEach 钩子，如下所示：

import {cleanup, render} from '@testing-library/react'
import test from 'ava'

test.afterEach(cleanup)

test('renders into document', () => {
  render(
)
  // ...
})

// ... more tests ...

如果在调用 render 之后未能调用 cleanup，则可能会导致内存泄漏以及非“幂等”的测试（这可能导致测试中出现难以调试的错误）。

act

这是一个围绕 react-dom/test-utils 的 act 函数的轻量级包装器。如果你的 React 版本支持 act，它所做的就是将所有参数转发给 act 函数。为了保持一致性，建议使用 @testing-library/react 中的导入，而不是 react-dom/test-utils。

renderHook 

这是一个围绕自定义测试组件的 render 函数的便利包装器。这个 API 源自一种流行的测试模式，主要对发布钩子的库来说很有趣。你应该更喜欢使用 render，因为自定义测试组件会使测试更具可读性和健壮性，因为你要测试的东西不会隐藏在抽象背后。

function renderHook<
  Result,
  Props,
  Q extends Queries = typeof queries,
  Container extends Element | DocumentFragment = HTMLElement,
  BaseElement extends Element | DocumentFragment = Container
>(
  render: (initialProps: Props) => Result,
  options?: RenderHookOptions,
): RenderHookResult

Example:

import {renderHook} from '@testing-library/react'

test('returns logged in user', () => {
  const {result} = renderHook(() => useLoggedInUser())
  expect(result.current).toEqual({name: 'Alice'})
})

renderHook Options

initialProps

首次调用渲染回调时，声明传递的 props。 如果您在没有 props 的情况下调用重新渲染，则不会传递这些 props。

import {renderHook} from '@testing-library/react'

test('returns logged in user', () => {
  const {result, rerender} = renderHook((props = {}) => props, {
    initialProps: {name: 'Alice'},
  })
  expect(result.current).toEqual({name: 'Alice'})
  rerender()
  expect(result.current).toEqual({name: undefined})
})

注意：当与包装器（wrapper）和初始属性（initialProps）选项一起使用renderHook时，不会将初始属性传递给包装器组件。要为包装器组件提供属性，请考虑采用以下解决方案：

const createWrapper = (Wrapper, props) => {
  return function CreatedWrapper({ children }) {
    return {children};
  };
};

...

{
  wrapper: createWrapper(Wrapper, { value: 'foo' }),
}

 wrapper

参考 wrapper option for render

renderHook Result

renderHook 方法返回一个包含几个属性的对象：

result

持有最近提交的渲染回调的返回值：

import {renderHook} from '@testing-library/react'

const {result} = renderHook(() => {
  const [name, setName] = useState('')
  React.useEffect(() => {
    setName('Alice')
  }, [])

  return name
})

expect(result.current).toBe('Alice')

请注意，该值存储在 result.current 中。可以认为 result 是最近提交值的引用。

rerender

使用新属性重新渲染之前渲染的渲染回调：

import {renderHook} from '@testing-library/react'

const {rerender} = renderHook(({name = 'Alice'} = {}) => name)

// re-render the same hook with different props
rerender({name: 'Bob'})

unmount

卸载测试钩子。

import {renderHook} from '@testing-library/react'

const {unmount} = renderHook(({name = 'Alice'} = {}) => name)

unmount()

configure

更改全局选项。基本用法可参见 configure Options。React Testing Library 也有专用选项。

configure Options

reactStrictMode

启用时，将在  内部渲染元素。 默认值为 false。