Dominando Testes em React com o Utilitário `act`: Um Guia Completo

Testar é um pilar de software robusto e de fácil manutenção. No ecossistema React, testes completos são cruciais para garantir que seus componentes se comportem como esperado e proporcionem uma experiência de usuário confiável. O utilitário `act`, fornecido por `react-dom/test-utils`, é uma ferramenta essencial para escrever testes confiáveis em React, especialmente ao lidar com atualizações de estado assíncronas e efeitos colaterais.

O que é o Utilitário `act`?

O utilitário `act` é uma função que prepara um componente React para asserções. Ele garante que todas as atualizações e efeitos colaterais relacionados tenham sido aplicados ao DOM antes de você começar a fazer asserções. Pense nele como uma forma de sincronizar seus testes com o estado interno e os processos de renderização do React.

Em essência, o `act` envolve qualquer código que cause atualizações de estado no React. Isso inclui:

• Manipuladores de eventos (ex: `onClick`, `onChange`)
• Hooks `useEffect`
• Setters do `useState`
• Qualquer outro código que modifique o estado do componente

Sem o `act`, seus testes podem fazer asserções antes que o React tenha processado completamente as atualizações, levando a resultados instáveis e imprevisíveis. Você pode ver avisos como "An update to [component] inside a test was not wrapped in act(...).". Este aviso indica uma possível condição de corrida onde seu teste está fazendo asserções antes que o React esteja em um estado consistente.

Por que o `act` é Importante?

A principal razão para usar o `act` é garantir que seus componentes React estejam em um estado consistente e previsível durante os testes. Ele resolve vários problemas comuns:

1. Prevenindo Problemas com Atualizações de Estado Assíncronas

As atualizações de estado no React são frequentemente assíncronas, o que significa que não acontecem imediatamente. Quando você chama `setState`, o React agenda uma atualização, mas não a aplica na hora. Sem o `act`, seu teste pode afirmar um valor antes que a atualização de estado tenha sido processada, levando a resultados incorretos.

Exemplo: Teste Incorreto (Sem `act`)

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

function Counter() {
  const [count, setCount] = useState(0);

  const increment = () => {
    setCount(count + 1);
  };

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

test('increments the counter', () => {
  render(<Counter />);
  const incrementButton = screen.getByText('Increment');
  fireEvent.click(incrementButton);
  expect(screen.getByText('Count: 1')).toBeInTheDocument(); // This might fail!
});

            

              
                Copy
              
            
          

Neste exemplo, a asserção `expect(screen.getByText('Count: 1')).toBeInTheDocument();` pode falhar porque a atualização de estado acionada pelo `fireEvent.click` não foi totalmente processada quando a asserção é feita.

2. Garantindo que Todos os Efeitos Colaterais Sejam Processados

Os hooks `useEffect` frequentemente acionam efeitos colaterais, como buscar dados de uma API ou atualizar o DOM diretamente. O `act` garante que esses efeitos colaterais sejam concluídos antes que o teste continue, prevenindo condições de corrida e garantindo que seu componente se comporte como esperado.

3. Melhorando a Confiabilidade e Previsibilidade dos Testes

Ao sincronizar seus testes com os processos internos do React, o `act` torna seus testes mais confiáveis e previsíveis. Isso reduz a probabilidade de testes instáveis que passam às vezes e falham em outras, tornando sua suíte de testes mais fidedigna.

Como Usar o Utilitário `act`

O utilitário `act` é simples de usar. Apenas envolva qualquer código que cause atualizações de estado no React ou efeitos colaterais em uma chamada `act`.

Exemplo: Teste Correto (Com `act`)

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

function Counter() {
  const [count, setCount] = useState(0);

  const increment = () => {
    setCount(count + 1);
  };

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

test('increments the counter', async () => {
  render(<Counter />);
  const incrementButton = screen.getByText('Increment');

  await act(async () => {
    fireEvent.click(incrementButton);
  });

  expect(screen.getByText('Count: 1')).toBeInTheDocument();
});

            

              
                Copy
              
            
          

Neste exemplo corrigido, a chamada `fireEvent.click` está envolvida em uma chamada `act`. Isso garante que o React tenha processado completamente a atualização de estado antes que a asserção seja feita.

`act` Assíncrono

O utilitário `act` pode ser usado de forma síncrona ou assíncrona. Ao lidar com código assíncrono (ex: hooks `useEffect` que buscam dados), você deve usar a versão assíncrona do `act`.

Exemplo: Testando Efeitos Colaterais Assíncronos

            
import React, { useState, useEffect } from 'react';
import { render, screen, act } from '@testing-library/react';

async function fetchData() {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve('Fetched Data');
    }, 50);
  });
}

function MyComponent() {
  const [data, setData] = useState(null);

  useEffect(() => {
    async function loadData() {
      const result = await fetchData();
      setData(result);
    }

    loadData();
  }, []);

  return <div>{data ? <p>{data}</p> : <p>Loading...</p>}</div>;
}

test('fetches data correctly', async () => {
  render(<MyComponent />);

  // Initial render shows "Loading..."
  expect(screen.getByText('Loading...')).toBeInTheDocument();

  // Wait for the data to load and the component to update
  await act(async () => {
    // The fetchData function will resolve after 50ms, triggering a state update.
    // The await here ensures we wait for act to complete all updates.
    await new Promise(resolve => setTimeout(resolve, 0)); // A small delay to allow act to process.
  });

  // Assert that the data is displayed
  expect(screen.getByText('Fetched Data')).toBeInTheDocument();
});

            

              
                Copy
              
            
          

Neste exemplo, o hook `useEffect` busca dados de forma assíncrona. A chamada `act` é usada para envolver o código assíncrono, garantindo que o componente tenha sido totalmente atualizado antes que a asserção seja feita. A linha `await new Promise` é necessária para dar tempo ao `act` para processar a atualização acionada pela chamada `setData` dentro do hook `useEffect`, especialmente em ambientes onde o agendador pode atrasar a atualização.

Melhores Práticas para Usar o `act`

Para aproveitar ao máximo o utilitário `act`, siga estas melhores práticas:

1. Envolva Todas as Atualizações de Estado

Garanta que todo o código que causa atualizações de estado no React seja envolvido em uma chamada `act`. Isso inclui manipuladores de eventos, hooks `useEffect` e setters do `useState`.

2. Use `act` Assíncrono para Código Assíncrono

Ao lidar com código assíncrono, use a versão assíncrona do `act` para garantir que todos os efeitos colaterais sejam concluídos antes que o teste continue.

3. Evite Chamadas `act` Aninhadas

Evite aninhar chamadas `act`. O aninhamento pode levar a um comportamento inesperado e tornar seus testes mais difíceis de depurar. Se você precisar realizar várias ações, envolva todas elas em uma única chamada `act`.

4. Use `await` com `act` Assíncrono

Ao usar a versão assíncrona do `act`, sempre use `await` para garantir que a chamada `act` tenha sido concluída antes que o teste continue. Isso é especialmente importante ao lidar com efeitos colaterais assíncronos.

5. Evite Envolver Código em Excesso

Embora seja crucial envolver as atualizações de estado, evite envolver código que não causa diretamente mudanças de estado ou efeitos colaterais. O excesso de envolvimento pode tornar seus testes mais complexos e menos legíveis.

6. Entendendo `flushMicrotasks` e `advanceTimersByTime`

Em certos cenários, especialmente ao lidar com timers ou promises mockados, você pode precisar usar `act(() => jest.advanceTimersByTime(time))` ou `act(() => flushMicrotasks())` para forçar o React a processar as atualizações imediatamente. Estas são técnicas mais avançadas, mas entendê-las pode ser útil para cenários assíncronos complexos.

7. Considere Usar `userEvent` de `@testing-library/user-event`

Em vez de `fireEvent`, considere usar `userEvent` de `@testing-library/user-event`. O `userEvent` simula interações de usuário reais com mais precisão, muitas vezes lidando com chamadas `act` internamente, o que leva a testes mais limpos e confiáveis. Por exemplo:

            
import React, { useState } from 'react';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

function MyComponent() {
  const [value, setValue] = useState('');

  const handleChange = (event) => {
    setValue(event.target.value);
  };

  return (
    <input type="text" value={value} onChange={handleChange} />
  );
}

test('updates the input value', async () => {
  render(<MyComponent />);
  const inputElement = screen.getByRole('textbox');

  await userEvent.type(inputElement, 'hello');
  expect(inputElement.value).toBe('hello');
});

            

              
                Copy
              
            
          

Neste exemplo, `userEvent.type` lida com as chamadas `act` necessárias internamente, tornando o teste mais limpo e fácil de ler.

Armadilhas Comuns e Como Evitá-las

Embora o utilitário `act` seja uma ferramenta poderosa, é importante estar ciente de armadilhas comuns e como evitá-las:

1. Esquecer de Envolver as Atualizações de Estado

A armadilha mais comum é esquecer de envolver as atualizações de estado em uma chamada `act`. Isso pode levar a testes instáveis e comportamento imprevisível. Sempre verifique novamente se todo o código que causa atualizações de estado está envolvido em `act`.

2. Usar Incorretamente o `act` Assíncrono

Ao usar a versão assíncrona do `act`, é importante usar `await` na chamada `act`. Não fazer isso pode levar a condições de corrida e resultados incorretos.

3. Depender Excessivamente de `setTimeout` ou `flushPromises`

Embora `setTimeout` ou `flushPromises` possam às vezes ser usados para contornar problemas com atualizações de estado assíncronas, eles devem ser usados com moderação. Na maioria dos casos, usar o `act` corretamente é a melhor maneira de garantir que seus testes sejam confiáveis.

4. Ignorar Avisos

Se você vir um aviso como "An update to [component] inside a test was not wrapped in act(...).", não o ignore! Este aviso indica uma possível condição de corrida que precisa ser resolvida.

Exemplos em Diferentes Frameworks de Teste

O utilitário `act` está principalmente associado às utilidades de teste do React, mas os princípios se aplicam independentemente do framework de teste específico que você está usando.

1. Usando `act` com Jest e React Testing Library

Este é o cenário mais comum. A React Testing Library incentiva o uso de `act` para garantir atualizações de estado adequadas.

            
import React from 'react';
import { render, screen, fireEvent, act } from '@testing-library/react';

// Component and test (as shown previously)

            

              
                Copy
              
            
          

2. Usando `act` com Enzyme

Enzyme é outra biblioteca de testes popular para React, embora esteja se tornando menos comum à medida que a React Testing Library ganha proeminência. Você ainda pode usar `act` com Enzyme para garantir atualizações de estado adequadas.

            
import React from 'react';
import { mount } from 'enzyme';
import { act } from 'react-dom/test-utils';

// Example component (e.g., Counter from previous examples)

it('increments the counter', () => {
  const wrapper = mount(<Counter />);
  const button = wrapper.find('button');

  act(() => {
    button.simulate('click');
  });

  wrapper.update(); // Force re-render
  expect(wrapper.find('p').text()).toEqual('Count: 1');
});

            

              
                Copy
              
            
          

Nota: Com o Enzyme, você pode precisar chamar `wrapper.update()` para forçar uma nova renderização após a chamada `act`.

`act` em Diferentes Contextos Globais

Os princípios de uso do `act` são universais, mas a aplicação prática pode variar ligeiramente dependendo do ambiente específico e das ferramentas usadas por diferentes equipes de desenvolvimento ao redor do mundo. Por exemplo:

• Equipes usando TypeScript: Os tipos fornecidos por `@types/react-dom` ajudam a garantir que o `act` seja usado corretamente e fornecem verificação em tempo de compilação para possíveis problemas.
• Equipes usando pipelines de CI/CD: O uso consistente do `act` garante que os testes sejam confiáveis e previne falhas espúrias em ambientes de CI/CD, independentemente do provedor de infraestrutura (ex: GitHub Actions, GitLab CI, Jenkins).
• Equipes trabalhando com internacionalização (i18n): Ao testar componentes que exibem conteúdo localizado, é importante garantir que o `act` seja usado corretamente para lidar com quaisquer atualizações assíncronas ou efeitos colaterais relacionados ao carregamento ou atualização das strings localizadas.

Conclusão

O utilitário `act` é uma ferramenta vital para escrever testes de React confiáveis e previsíveis. Ao garantir que seus testes estejam sincronizados com os processos internos do React, o `act` ajuda a prevenir condições de corrida e garante que seus componentes se comportem como esperado. Seguindo as melhores práticas delineadas neste guia, você pode dominar o utilitário `act` e escrever aplicações React mais robustas e de fácil manutenção. Ignorar os avisos e pular o uso do `act` cria suítes de teste que mentem para os desenvolvedores e stakeholders, levando a bugs em produção. Sempre use o `act` para criar testes fidedignos.