Aller au contenu principal

API

[Traduction Bêta Non Officielle]

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

React Testing Library réexporte tous les éléments de DOM Testing Library ainsi que ces méthodes :

render​

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

Effectue le rendu dans un conteneur ajouté à 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>
  `)
})

Options de render​

Vous n'aurez généralement pas besoin de spécifier d'options, mais si c'est le cas, voici celles disponibles que vous pouvez passer en second argument à render.

container​

Par défaut, React Testing Library crée une div et ajoute cette div au document.body. C'est là que votre composant React sera rendu. Si vous fournissez votre propre container HTMLElement via cette option, il ne sera pas automatiquement ajouté au document.body.

Par exemple : Si vous testez un élément tablebody, il ne peut pas être enfant d'un div. Dans ce cas, vous pouvez spécifier une table comme container de rendu.

const table = document.createElement('table')

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

baseElement​

Si container est spécifié, cette valeur le remplace par défaut. Sinon, elle vaut par défaut document.body. Cet élément sert de base pour les requêtes et ce qui est affiché lors de l'utilisation de debug().

hydrate​

Si hydrate est défini sur true, le rendu utilisera ReactDOM.hydrate. Utile si vous utilisez le rendu côté serveur et montez vos composants avec ReactDOM.hydrate.

legacyRoot​

danger

Cette option n'est disponible que pour les tests exécutés avec React 18 et antérieur.

Par défaut, nous effectuons le rendu avec le support des fonctionnalités concurrentes (c'est-à-dire ReactDOMClient.createRoot). Toutefois, si vous travaillez avec une application héritée nécessitant un rendu comme dans React 17 (c'est-à-dire ReactDOM.render), vous devez activer cette option en définissant legacyRoot: true.

onCaughtError​

Fonction de rappel déclenchée quand React intercepte une erreur dans un périmètre d'erreur (Error Boundary). Se comporte comme onCaughtError dans ReactDOMClient.createRoot.

onRecoverableError​

Fonction de rappel déclenchée quand React récupère automatiquement des erreurs. Se comporte comme onRecoverableError dans ReactDOMClient.createRoot.

wrapper​

Passez un composant React comme option wrapper pour qu'il soit rendu autour de l'élément interne. C'est particulièrement utile pour créer des fonctions de rendu personnalisées réutilisables pour des fournisseurs de données communs. Voir la configuration pour des exemples.

queries​

Requêtes à lier. Remplace l'ensemble par défaut de DOM Testing Library sauf si fusionné.

// 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},
})

Voir les helpers pour des conseils sur l'utilisation des fonctions utilitaires afin de créer des requêtes personnalisées.

Les requêtes personnalisées peuvent également être ajoutées globalement en suivant le guide de rendu personnalisé.

Options reactStrictMode pour render​

Lorsqu'activé, <StrictMode> est rendu autour de l'élément interne. Si défini, remplace la valeur de reactStrictMode définie dans configure.

Résultat de render​

La méthode render retourne un objet avec quelques propriétés :

...queries​

La caractéristique la plus importante de render est que les requêtes de DOM Testing Library sont automatiquement retournées avec leur premier argument lié au baseElement, qui correspond par défaut à document.body.

Voir Requêtes pour une liste complète.

Exemple

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

container​

Le nœud DOM contenant votre élément React rendu (affiché via ReactDOM.render). C'est une div. Il s'agit d'un nœud DOM standard, vous pouvez donc appeler container.querySelector etc. pour inspecter les enfants.

Conseil : Pour obtenir l'élément racine de votre élément rendu, utilisez container.firstChild.

NOTE : Lorsque cet élément racine est un Fragment React, container.firstChild récupérera uniquement le premier enfant du Fragment, pas le Fragment lui-même.

⚠️ Si vous vous surprenez à utiliser container pour interroger des éléments rendus, vous devriez reconsidérer votre approche ! Les autres requêtes sont conçues pour être plus résilientes aux modifications apportées au composant testé. Évitez d'utiliser container pour interroger des éléments !

baseElement​

Le nœud DOM contenant où votre élément React est rendu dans le conteneur. Si vous ne spécifiez pas le baseElement dans les options de render, il sera par défaut document.body.

Utile lorsque le composant à tester affiche des éléments en dehors de la div conteneur, par exemple pour tester des composants de type portal qui rendent leur HTML directement dans le body.

Note : les requêtes retournées par render examinent le baseElement, vous pouvez donc utiliser des requêtes pour tester votre composant portal sans spécifier de baseElement.

debug​

NOTE : Il est recommandé d'utiliser screen.debug à la place.

Cette méthode est un raccourci pour 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})

Il s'agit d'un simple wrapper autour de prettyDOM, également exposé et provenant de DOM Testing Library.

rerender​

Il serait probablement préférable de tester le composant qui effectue la mise à jour des props pour s'assurer qu'elles sont correctement actualisées (voir la section Principes directeurs). Cela dit, si vous préférez mettre à jour les props d'un composant rendu dans votre test, cette fonction peut être utilisée pour actualiser les props du composant.

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

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

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

Voir la page d'exemples

unmount​

Cela provoquera le démontage du composant rendu. C'est utile pour tester ce qui se passe lorsque votre composant est retiré de la page (par exemple vérifier que vous ne laissez pas de gestionnaires d'événements résiduels causant des fuites mémoire).

Cette méthode est une petite abstraction au-dessus de ReactDOM.unmountComponentAtNode

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

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

asFragment​

Retourne un DocumentFragment de votre composant rendu. Cela peut être utile si vous devez éviter les liaisons actives et observer comment votre composant réagit aux événements.

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​

Démonte les arbres React montés avec render.

Appelé automatiquement si votre framework de test (comme Mocha, Jest ou Jasmine) injecte une fonction globale afterEach(). Sinon, vous devez appeler cleanup() après chaque test.

Par exemple, si vous utilisez le framework de test ava, vous devrez utiliser le hook test.afterEach comme suit :

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

test.afterEach(cleanup)

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

// ... more tests ...

Ne pas appeler cleanup après avoir utilisé render peut entraîner une fuite mémoire et des tests non "idempotents" (ce qui peut provoquer des erreurs difficiles à déboguer).

act​

Il s'agit d'un léger wrapper autour de la fonction act de react. Son seul rôle est de transmettre tous les arguments à la fonction act si votre version de React supporte act. Il est recommandé d'utiliser l'import depuis @testing-library/react plutôt que react par souci de cohérence.

renderHook​

Il s'agit d'un wrapper pratique autour de render avec un composant de test personnalisé. Cette API est issue d'un modèle de test populaire et intéresse principalement les bibliothèques publiant des hooks. Vous devriez privilégier render car un composant de test personnalisé produit des tests plus lisibles et robustes, puisque l'élément à tester n'est pas caché derrière une abstraction.

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>

Exemple :

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

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

Options de renderHook​

Option initialProps de renderHook​

Définit les props transmises au callback de rendu lors du premier appel. Elles ne seront pas transmises si vous appelez rerender sans 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})
})

NOTE : Lorsque vous utilisez renderHook avec les options wrapper et initialProps, les initialProps ne sont pas transmises au composant wrapper. Pour fournir des props au composant wrapper, envisagez une solution comme :

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

...

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

onCaughtError​

Fonction de rappel déclenchée quand React intercepte une erreur dans un périmètre d'erreur (Error Boundary). Se comporte comme onCaughtError dans ReactDOMClient.createRoot.

onRecoverableError​

Fonction de rappel déclenchée quand React récupère automatiquement des erreurs. Se comporte comme onRecoverableError dans ReactDOMClient.createRoot.

Option wrapper pour renderHook​

Voir l'option wrapper pour render

Option reactStrictMode pour renderHook​

Voir l'option reactStrictMode pour render

Résultat de renderHook​

La méthode renderHook retourne un objet avec les propriétés suivantes :

result​

Contient la valeur la plus récente validée retournée par la fonction de rendu :

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

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

  return name
})

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

Notez que la valeur est stockée dans result.current. Considérez result comme une ref pour la valeur la plus récente validée.

rerender​

Ré-exécute la fonction de rendu précédente avec de nouvelles 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​

Démonte le hook testé.

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

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

unmount()

configure​

Modifie les options globales. L'utilisation de base est documentée dans Configuration Options.

React Testing Library propose également des options dédiées.

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

configure({reactStrictMode: true})

Options de configure​

reactStrictMode​

Quand activé, un <StrictMode> est rendu autour de l'élément interne. Par défaut : false.

Ce paramètre peut être modifié pour un test spécifique en fournissant reactStrictMode dans les options de la fonction render.