Saltar al contenido principal

API

[Traducción Beta No Oficial]

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

React Testing Library reexporta todo de DOM Testing Library además de estos métodos:

render​

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

Renderiza en un contenedor que se añade a document.body.

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

render(<div />)
import {render} from '@testing-library/react'
import '@testing-library/jest-dom'

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

Opciones de render​

Normalmente no necesitarás especificar opciones, pero si alguna vez lo haces, estas son las opciones disponibles que puedes proporcionar como segundo argumento a render.

container​

Por defecto, React Testing Library creará un div y agregará ese div al document.body, siendo este el lugar donde se renderizará tu componente React. Si proporcionas tu propio container HTMLElement mediante esta opción, no se agregará automáticamente al document.body.

Por ejemplo: Si estás probando un elemento tablebody, no puede ser hijo de un div. En este caso, puedes especificar una table como container de renderizado.

const table = document.createElement('table')

const {container} = render(<TableBody {...props} />, {
  container: document.body.appendChild(table),
})

baseElement​

Si se especifica container, este valor se toma por defecto. En caso contrario, el valor predeterminado es document.body. Se utiliza como elemento base para las consultas y también para lo que se imprime al usar debug().

hydrate​

Si hydrate se establece en true, se renderizará con ReactDOM.hydrate. Esto puede ser útil si estás usando renderizado del lado del servidor y utilizas ReactDOM.hydrate para montar tus componentes.

legacyRoot​

peligro

Esta opción solo está disponible cuando las pruebas se ejecutan con React 18 y versiones anteriores.

Por defecto renderizaremos con soporte para características concurrentes (es decir, ReactDOMClient.createRoot). Sin embargo, si estás trabajando con una aplicación heredada que requiere renderizado como en React 17 (es decir, ReactDOM.render), debes habilitar esta opción estableciendo legacyRoot: true.

onCaughtError​

Callback invocado cuando React detecta un error en un Error Boundary. Se comporta igual que onCaughtError en ReactDOMClient.createRoot.

onRecoverableError​

Callback invocado cuando React se recupera automáticamente de errores. Se comporta igual que onRecoverableError en ReactDOMClient.createRoot.

wrapper​

Pasa un componente de React como opción wrapper para que se renderice alrededor del elemento interno. Esto es especialmente útil para crear funciones de renderizado personalizadas reutilizables para proveedores de datos comunes. Consulta configuración para ver ejemplos.

queries​

Consultas a vincular. Sobrescribe el conjunto predeterminado de DOM Testing Library a menos que se fusionen.

// 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(<MyTable />, {
  queries: {...queries, ...tableQueries},
})

Consulta helpers para obtener orientación sobre cómo usar funciones de utilidad para crear consultas personalizadas.

Las consultas personalizadas también pueden agregarse globalmente siguiendo la guía de renderizado personalizado.

Opción reactStrictMode de render​

Cuando está habilitado, se renderiza <StrictMode> alrededor del elemento interno. Si se define, sobrescribe el valor de reactStrictMode establecido en configure.

Resultado de render​

El método render devuelve un objeto con varias propiedades:

...queries​

La característica más importante de render es que las consultas de DOM Testing Library se devuelven automáticamente con su primer argumento vinculado al baseElement, que por defecto es document.body.

Consulta Queries para ver la lista completa.

Ejemplo

const {getByLabelText, queryAllByTestId} = render(<Component />)

container​

El nodo DOM contenedor de tu elemento React renderizado (usando ReactDOM.render). Es un div. Este es un nodo DOM regular, por lo que puedes usar container.querySelector, etc., para inspeccionar los elementos hijos.

Consejo: Para obtener el elemento raíz de tu elemento renderizado, usa container.firstChild.

NOTA: Cuando ese elemento raíz es un Fragmento de React, container.firstChild solo obtendrá el primer hijo del Fragmento, no el Fragmento en sí.

🚨 ¡Si te encuentras usando container para consultar elementos renderizados, deberías reconsiderarlo! Las otras consultas están diseñadas para ser más resistentes a los cambios que se harán en el componente que estás probando. Evita usar container para consultar elementos.

baseElement​

El nodo DOM contenedor donde se renderiza tu elemento React. Si no especificas baseElement en las opciones de render, por defecto será document.body.

Esto es útil cuando el componente que deseas probar renderiza algo fuera del contenedor div, por ejemplo, cuando quieres hacer pruebas de instantáneas de tu componente portal que renderiza su HTML directamente en el body.

Nota: las consultas devueltas por render examinan baseElement, por lo que puedes usar consultas para probar tu componente portal sin especificar baseElement.

debug​

NOTA: Se recomienda usar screen.debug en su lugar.

Este método es un atajo para console.log(prettyDOM(baseElement)).

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

const HelloWorld = () => <h1>Hello World</h1>
const {debug} = render(<HelloWorld />)
debug()
// <div>
//   <h1>Hello World</h1>
// </div>
// 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})

Es un envoltorio simple alrededor de prettyDOM, que también está expuesto y proviene de DOM Testing Library.

rerender​

Probablemente sería mejor probar el componente que actualiza las props para asegurarse de que se actualizan correctamente (consulta la sección de Principios Guía). Dicho esto, si prefieres actualizar las props de un componente renderizado en tu prueba, esta función puede usarse para actualizar props del componente renderizado.

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

const {rerender} = render(<NumberDisplay number={1} />)

// re-render the same component with different props
rerender(<NumberDisplay number={2} />)

Consulta la página de ejemplos

unmount​

Esto hará que el componente renderizado se desmonte. Es útil para probar qué sucede cuando tu componente se elimina de la página (como verificar que no dejas manejadores de eventos pendientes causando fugas de memoria).

Este método es una pequeña abstracción sobre ReactDOM.unmountComponentAtNode

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

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

asFragment​

Devuelve un DocumentFragment de tu componente renderizado. Esto puede ser útil si necesitas evitar enlaces en vivo y ver cómo reacciona tu componente a eventos.

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

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

  return (
    <button onClick={() => setCounter(count => count + 1)}>
      Click to increase: {count}
    </button>
  )
}

const {getByText, asFragment} = render(<TestComponent />)
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​

Desmonta árboles de React que fueron montados con render.

Esto se llama automáticamente si tu framework de pruebas (como Mocha, Jest o Jasmine) inyecta una función global afterEach() en el entorno de pruebas. Si no es el caso, deberás llamar a cleanup() después de cada prueba.

Por ejemplo, si estás usando el framework de pruebas ava, necesitarás utilizar el hook test.afterEach de esta manera:

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

test.afterEach(cleanup)

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

// ... more tests ...

No llamar a cleanup después de haber invocado render puede causar pérdidas de memoria y pruebas que no son "idempotentes" (lo que puede generar errores difíciles de depurar en tus pruebas).

act​

Este es un envoltorio ligero alrededor de la función react act. Simplemente reenvía todos los argumentos a la función act si tu versión de React la soporta. Se recomienda importar desde @testing-library/react en lugar de react por consistencia.

renderHook​

Es un envoltorio conveniente alrededor de render con un componente de prueba personalizado. Esta API surgió de un patrón de pruebas popular y es principalmente útil para bibliotecas que publican hooks. Se recomienda preferir render ya que un componente de prueba personalizado produce tests más legibles y robustos, porque lo que quieres probar no está oculto tras una abstracción.

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<Props, Q, Container, BaseElement>,
): RenderHookResult<Result, Props>

Ejemplo:

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

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

Opciones de renderHook​

renderHook Opciones initialProps​

Define las props que se pasan al render-callback durante la primera invocación. No se pasarán si llamas a rerender sin 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})
})

NOTA: Al usar renderHook junto con las opciones wrapper e initialProps, los initialProps no se pasan al componente wrapper. Para proporcionar props al componente wrapper, considera una solución como esta:

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

...

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

onCaughtError​

Callback invocado cuando React detecta un error en un Error Boundary. Se comporta igual que onCaughtError en ReactDOMClient.createRoot.

onRecoverableError​

Callback invocado cuando React se recupera automáticamente de errores. Se comporta igual que onRecoverableError en ReactDOMClient.createRoot.

renderHook Opciones wrapper​

Ver opción wrapper para render

Opciones de renderHook reactStrictMode​

Ver opción reactStrictMode para render

Resultado de renderHook​

El método renderHook retorna un objeto con varias propiedades:

result​

Contiene el valor más reciente confirmado devuelto por el render-callback:

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

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

  return name
})

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

Nota que el valor se almacena en result.current. Considera result como una ref para el valor más reciente confirmado.

rerender​

Vuelve a renderizar el render-callback previamente renderizado con nuevas props:

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

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

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

unmount​

Desmonta el hook de prueba.

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

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

unmount()

configure​

Modifica opciones globales. El uso básico puede verse en Opciones de Configuración.

React Testing Library también tiene opciones específicas.

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

configure({reactStrictMode: true})

Opciones de configure​

reactStrictMode​

Cuando está habilitado, <StrictMode> se renderiza alrededor del elemento interno. Por defecto es false.

Esta configuración puede cambiarse para una prueba individual proporcionando reactStrictMode en el argumento de opciones de la función render.