Introduction

[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 →

user-event est une bibliothèque complémentaire à Testing Library qui simule les interactions utilisateur en déclenchant les événements qui se produiraient si l'interaction avait lieu dans un navigateur.

[Dernière version]

Cette documentation décrit user-event@14. Nous recommandons de mettre à jour vos projets vers cette version, car elle inclut des corrections de bugs importantes et de nouvelles fonctionnalités. Vous pouvez trouver la documentation pour user-event@13.5.0 ici, et le journal des modifications de cette version ici.

Bien que la plupart des exemples avec user-event concernent React, cette bibliothèque peut être utilisée avec n'importe quel framework tant qu'un DOM est présent.

Différences avec fireEvent

fireEvent déclenche des événements DOM, tandis que user-event simule des interactions complètes, qui peuvent générer plusieurs événements et effectuer des vérifications supplémentaires durant le processus.

Le fireEvent intégré à Testing Library est une surcouche légère autour de l'API bas niveau dispatchEvent des navigateurs, permettant aux développeurs de déclencher n'importe quel événement sur n'importe quel élément. Le problème est que le navigateur fait généralement plus que simplement déclencher un événement par interaction. Par exemple, lorsqu'un utilisateur saisit du texte dans un champ, l'élément doit d'abord recevoir le focus, puis des événements clavier et de saisie sont déclenchés, tandis que la sélection et la valeur de l'élément sont modifiées au fil de la frappe.

user-event permet de décrire une interaction utilisateur plutôt qu'un événement spécifique. Il ajoute des vérifications de visibilité et d'interactivité durant le processus et manipule le DOM exactement comme le ferait une interaction utilisateur réelle dans un navigateur. Il prend en compte que le navigateur n'autoriserait par exemple pas un clic sur un élément masqué ou une saisie dans un champ désactivé.
Voici pourquoi vous devriez utiliser user-event pour tester les interactions avec vos composants.

Certaines interactions utilisateur ou aspects de celles-ci ne sont cependant pas encore implémentés et ne peuvent donc pas être décrits avec user-event. Dans ces cas, vous pouvez utiliser fireEvent pour déclencher les événements spécifiques dont dépend votre logiciel.

Notez que cela rend votre composant et/ou votre test dépendant de vos hypothèses concernant les aspects concrets de l'interaction. Par conséquent, si vous avez déjà travaillé à spécifier les aspects corrects de cette interaction, envisagez de contribuer à ce projet pour que user-event puisse également couvrir ces cas.

Écrire des tests avec userEvent

Nous recommandons d'appeler userEvent.setup() avant le rendu du composant. Cela peut être fait dans le test lui-même ou via une fonction de configuration. Nous déconseillons d'effectuer le rendu ou d'utiliser des fonctions userEvent en dehors du test proprement dit (par exemple dans un hook before/after), pour les raisons décrites dans "Évitez l'imbrication dans vos tests".

import userEvent from '@testing-library/user-event'

// inlining
test('trigger some awesome feature when clicking the button', async () => {
  const user = userEvent.setup()
  // Import `render` and `screen` from the framework library of your choice.
  // See https://testing-library.com/docs/dom-testing-library/install#wrappers
  render(<MyComponent />)

  await user.click(screen.getByRole('button', {name: /click me!/i}))

  // ...assertions...
})

import userEvent from '@testing-library/user-event'

// setup function
function setup(jsx) {
  return {
    user: userEvent.setup(),
    // Import `render` from the framework library of your choice.
    // See https://testing-library.com/docs/dom-testing-library/install#wrappers
    ...render(jsx),
  }
}

test('render with a setup function', async () => {
  const {user} = setup(<MyComponent />)
  // ...
})

Notez que l'appel direct d'API comme userEvent.click() (qui déclenchera setup en interne) est toujours pris en charge dans la v14. Cette option existe pour faciliter la migration de la v13 vers la v14 et pour les tests simples. Nous recommandons néanmoins d'utiliser les méthodes des instances retournées par userEvent.setup().