Métodos Assíncronos
Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →
Diversos utilitários são fornecidos para lidar com código assíncrono. Eles são úteis para aguardar a aparição ou desaparecimento de um elemento em resposta a eventos, ações do usuário, timeouts ou Promises. (Consulte o guia para testar desaparecimentos.)
Os métodos assíncronos retornam Promises, portanto lembre-se de usar await ou .then ao chamá-los.
Consultas findBy
Os métodos findBy combinam as consultas getBy com waitFor. Eles aceitam as opções do waitFor como último argumento (ex: await screen.findByText('text', queryOptions, waitForOptions)).
As consultas findBy funcionam quando você espera que um elemento apareça, mas a alteração no DOM pode não ocorrer imediatamente.
const button = screen.getByRole('button', {name: 'Click Me'})
fireEvent.click(button)
await screen.findByText('Clicked once')
fireEvent.click(button)
await screen.findByText('Clicked twice')
waitFor
function waitFor<T>(
callback: () => T | Promise<T>,
options?: {
container?: HTMLElement
timeout?: number
interval?: number
onTimeout?: (error: Error) => Error
mutationObserverOptions?: MutationObserverInit
},
): Promise<T>
Quando precisar aguardar qualquer período de tempo, use waitFor para esperar suas expectativas serem atendidas. Retornar uma condição falsa não é suficiente para acionar uma nova tentativa: o callback deve lançar um erro para repetir a verificação. Veja um exemplo simples:
// ...
// Wait until the callback does not throw an error. In this case, that means
// it'll wait until the mock function has been called once.
await waitFor(() => expect(mockAPI).toHaveBeenCalledTimes(1))
// ...
O waitFor pode executar o callback várias vezes até o timeout ser atingido. Note que o número de chamadas é limitado pelas opções timeout e interval.
Isso é útil em testes unitários que simulam chamadas de API, onde você precisa aguardar todas as Promises de mock serem resolvidas.
Se você retornar uma Promise no callback do waitFor (explicitamente ou implicitamente com sintaxe async), o utilitário waitFor não chamará seu callback novamente até que essa Promise seja rejeitada. Isso permite que você use o waitFor para verificações que precisam ser feitas assincronamente.
O container padrão é o document global. Certifique-se de que os elementos que você aguarda sejam descendentes desse container.
O interval padrão é 50ms. Porém, ele executa seu callback imediatamente antes de iniciar os intervalos.
O timeout padrão é 1000ms.
O onTimeout padrão captura o erro e anexa o estado impresso do container à mensagem de erro, facilitando a identificação da causa do timeout.
As mutationObserverOptions padrão são {subtree: true, childList: true, attributes: true, characterData: true}, que detectam adições/remoções de elementos filhos (incluindo nós de texto) no container e seus descendentes, além de alterações em atributos. Quando ocorrem essas mudanças, o callback é reexecutado.
waitForElementToBeRemoved
function waitForElementToBeRemoved<T>(
callback: (() => T) | T,
options?: {
container?: HTMLElement
timeout?: number
interval?: number
onTimeout?: (error: Error) => Error
mutationObserverOptions?: MutationObserverInit
},
): Promise<void>
Para aguardar a remoção de elemento(s) do DOM, use waitForElementToBeRemoved. A função waitForElementToBeRemoved é um wrapper simples em torno do utilitário waitFor.
O primeiro argumento deve ser um elemento, array de elementos ou callback que retorne um elemento ou array de elementos.
Exemplo onde a Promise é resolvida porque o elemento foi removido:
const el = document.querySelector('div.getOuttaHere')
waitForElementToBeRemoved(document.querySelector('div.getOuttaHere')).then(() =>
console.log('Element no longer in DOM'),
)
el.setAttribute('data-neat', true)
// other mutations are ignored...
el.parentElement.removeChild(el)
// logs 'Element no longer in DOM'
waitForElementToBeRemoved lança um erro se o primeiro argumento for null ou um array vazio:
waitForElementToBeRemoved(null).catch(err => console.log(err))
waitForElementToBeRemoved(queryByText(/not here/i)).catch(err =>
console.log(err),
)
waitForElementToBeRemoved(queryAllByText(/not here/i)).catch(err =>
console.log(err),
)
waitForElementToBeRemoved(() => getByText(/not here/i)).catch(err =>
console.log(err),
)
// Error: The element(s) given to waitForElementToBeRemoved are already removed. waitForElementToBeRemoved requires that the element(s) exist(s) before waiting for removal.
O objeto de opções é repassado para waitFor.