Introdução

[Tradução Beta Não Oficial]

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

user-event é uma biblioteca complementar para a Testing Library que simula interações do usuário despachando os eventos que ocorreriam se a interação acontecesse em um navegador.

[Última versão]

Esta documentação descreve user-event@14. Recomendamos atualizar seus projetos para esta versão, pois ela inclui correções de bugs importantes e novos recursos. Você pode encontrar a documentação para user-event@13.5.0 aqui e o changelog da versão aqui.

Embora a maioria dos exemplos com user-event seja para React, a biblioteca pode ser usada com qualquer framework, desde que haja um DOM.

Diferenças em relação ao fireEvent

fireEvent despacha eventos DOM, enquanto user-event simula interações completas, que podem disparar múltiplos eventos e realizar verificações adicionais durante o processo.

O fireEvent integrado na Testing Library é um wrapper leve em torno da API de baixo nível dispatchEvent do navegador, que permite que desenvolvedores disparem qualquer evento em qualquer elemento. O problema é que o navegador normalmente faz mais do que apenas disparar um único evento por interação. Por exemplo, quando um usuário digita em uma caixa de texto, o elemento precisa ser focado e então eventos de teclado e input são disparados, enquanto a seleção e o valor do elemento são manipulados durante a digitação.

user-event permite descrever uma interação do usuário em vez de um evento concreto. Ele adiciona verificações de visibilidade e interatividade durante o processo e manipula o DOM exatamente como uma interação do usuário faria no navegador. Ele considera que o navegador, por exemplo, não permitiria que um usuário clicasse em um elemento oculto ou digitasse em uma caixa de texto desativada.
Este é o motivo pelo qual você deve usar user-event para testar a interação com seus componentes.

Existem, no entanto, algumas interações do usuário ou aspectos dessas interações que ainda não foram implementados e, portanto, não podem ser descritos com user-event. Nesses casos, você pode usar fireEvent para disparar os eventos concretos dos quais seu software depende.

Observe que isso torna seu componente e/ou teste dependente das suas suposições sobre os aspectos concretos da interação estarem corretos. Portanto, se você já dedicou esforço para especificar os aspectos corretos dessa interação, considere contribuir com este projeto para que user-event possa cobrir esses casos também.

Escrevendo testes com userEvent

Recomendamos invocar userEvent.setup() antes do componente ser renderizado. Isso pode ser feito no próprio teste ou usando uma função de configuração. Desencorajamos a renderização ou o uso de qualquer função do userEvent fora do teste em si - por exemplo, em hooks before/after - pelas razões descritas em "Evite Aninhamento Quando Estiver Testando".

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

Observe que, embora a invocação direta de APIs como userEvent.click() (que irá acionar setup internamente) ainda seja suportada na v14, esta opção existe para facilitar a migração da v13 para v14 e para testes simples. Recomendamos usar os métodos nas instâncias retornadas por userEvent.setup().