Testes com React

Padrões abrangentes de testes com React para testes de componentes focados em comportamento, testes de hooks customizados, asserções de acessibilidade e mock de requisições em nível de rede.

Quando Ativar

• Escrevendo testes para componentes React, hooks customizados ou páginas
• Adicionando cobertura de testes a componentes legados sem testes
• Migrando de Enzyme ou padrões da era de componentes de classe para React Testing Library
• Configurando Vitest ou Jest para um novo projeto React
• Simulando requisições HTTP em testes
• Verificando violações de acessibilidade
• Decidindo quais testes pertencem ao RTL vs. Playwright Component Testing vs. E2E completo

Princípio Central

Teste o que o usuário vê e faz, não os detalhes de implementação.

Um teste deve:

• Renderizar o componente com os mesmos provedores que ele tem em produção
• Interagir com ele através de queries acessíveis (role, label) e userEvent
• Afirmar a saída visível e efeitos colaterais observáveis (callback disparado, requisição enviada)

Um teste NÃO deve:

• Inspecionar o estado do componente, props passadas para filhos, ou quais hooks foram chamados
• Simular o próprio React ou hooks do framework
• Afirmar o número de renderizações ou a estrutura do DOM além do que afeta os usuários

Escolha da Biblioteca

Escolha um. Não execute RTL + Vitest E Playwright CT no mesmo repositório, a menos que você tenha uma separação clara de responsabilidades.

Prioridade de Queries

React Testing Library expõe queries em três níveis — use de cima para baixo:

1. Acessível a todos: getByRole, getByLabelText, getByPlaceholderText, getByText, getByDisplayValue
2. Semântico: getByAltText, getByTitle
3. Test IDs (válvula de escape): getByTestId

// Best
screen.getByRole("button", { name: /save/i });

// OK for inputs
screen.getByLabelText("Email");

// Last resort
screen.getByTestId("save-btn");

Variantes:

• getBy* — lança um erro se não encontrar correspondência
• queryBy* — retorna null (use para "afirmar ausência")
• findBy* — assíncrono, retorna uma Promise (use para elementos que aparecem após trabalho assíncrono)

Interação do Usuário com userEvent

import userEvent from "@testing-library/user-event";

test("submits the form", async () => {
  const user = userEvent.setup();
  const onSubmit = vi.fn();
  render(<UserForm onSubmit={onSubmit} />);

  await user.type(screen.getByLabelText("Email"), "user@example.com");
  await user.click(screen.getByRole("button", { name: /save/i }));

  expect(onSubmit).toHaveBeenCalledWith({ email: "user@example.com" });
});

• Sempre await chamadas de userEvent
• Chame userEvent.setup() uma vez por teste, reutilize o user retornado
• userEvent simula uma sequência de navegador real; fireEvent dispara um único evento sintético — prefira userEvent

Padrões Assíncronos

// Element that appears after async work
expect(await screen.findByText("Loaded")).toBeInTheDocument();

// Side effect assertion
await waitFor(() => expect(saveSpy).toHaveBeenCalled());

// Element that should disappear
await waitForElementToBeRemoved(() => screen.queryByText("Loading"));

Nunca setTimeout + asserção — instável. Use os matchers acima.

Mock de Rede com MSW

Mock Service Worker simula em nível de rede. O componente, hooks e a biblioteca fetch se comportam exatamente como em produção.

Configuração

// test/setup.ts
import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

export const handlers = [
  http.get("/api/users/:id", ({ params }) =>
    HttpResponse.json({ id: params.id, name: "Alice" }),
  ),
  http.post("/api/users", async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ id: "new-id", ...body }, { status: 201 });
  }),
];

export const server = setupServer(...handlers);

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Configure onUnhandledRequest: "error" para que qualquer requisição não simulada falhe o teste de forma explícita — passes silenciosos são piores que falhas.

Sobrescrita por teste

test("renderiza erro em 500", async () => {
  server.use(
    http.get("/api/users/:id", () => new HttpResponse(null, { status: 500 })),
  );
  render(<UserPage id="1" />);

…