React Academy · Aula

Testes de integração com React Testing Library

Renderize componentes nos testes, dispare eventos e faça asserções sobre a saída visível, não sobre a implementação.

Testes de integração com React Testing Library é uma aula grátis de React Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.

O que é o React Testing Library?

O React Testing Library (RTL) incentiva os testes sob a perspectiva do usuário: renderize componentes, interaja com eles como um usuário faria e verifique a saída visível em vez dos detalhes de implementação.

Configuração

O RTL vem incluído no Create React App e no modelo React do Vite. Para uma configuração manual, instale @testing-library/react e @testing-library/jest-dom.

// package.json
// "@testing-library/react": "^14.0.0",
// "@testing-library/jest-dom": "^6.0.0"

// setupTests.ts
import '@testing-library/jest-dom';

Renderizando um componente

render() monta um componente em um DOM virtual. Ele retorna funções de consulta restritas à saída renderizada.

import { render, screen } from '@testing-library/react';
import { Button } from './Button';

test('renders button label', () => {
  render(<Button label="Submit" onClick={() => {}} />);
  expect(screen.getByText('Submit')).toBeInTheDocument();
});

Consultando elementos

Prefira as consultas nesta ordem: getByRole > getByLabelText > getByPlaceholderText > getByText. As consultas por função correspondem à semântica de acessibilidade.

// Best: query by role
const button = screen.getByRole('button', { name: /submit/i });

// Good: query by label (for form inputs)
const input = screen.getByLabelText('Email address');

// Acceptable: query by text
const heading = screen.getByText('Welcome');

Disparando eventos

Use userEvent de @testing-library/user-event, que é preferível, ou fireEvent, para casos básicos. userEvent simula interações reais do navegador, incluindo foco e perda de foco.

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

test('types into input', async () => {
  const user = userEvent.setup();
  render(<SearchBar />);
  const input = screen.getByRole('textbox');
  await user.type(input, 'react');
  expect(input).toHaveValue('react');
});

Testando o envio de um formulário

Renderize o formulário, preencha os campos de entrada com userEvent.type, clique em enviar e verifique o resultado: mensagem de sucesso, navegação ou chamada de função de retorno.

test('submits the login form', async () => {
  const onLogin = jest.fn();
  const user = userEvent.setup();
  render(<LoginForm onLogin={onLogin} />);

  await user.type(screen.getByLabelText('Email'), 'test@example.com');
  await user.type(screen.getByLabelText('Password'), 'password123');
  await user.click(screen.getByRole('button', { name: /log in/i }));

  expect(onLogin).toHaveBeenCalledWith({ email: 'test@example.com', password: 'password123' });
});

Verificando a visibilidade

Verificadores do jest-dom, como toBeInTheDocument(), toBeVisible() e toHaveValue(), tornam as verificações mais legíveis.

expect(screen.getByText('Error: required')).toBeInTheDocument();
expect(screen.getByRole('dialog')).toBeVisible();
expect(screen.getByRole('textbox')).toHaveValue('hello');
expect(screen.queryByText('Loading...')).not.toBeInTheDocument();

Testando a renderização condicional

Use queryBy, que retorna nulo quando o elemento está ausente, para verificar que um elemento não foi renderizado. Use getBy quando esperar que ele esteja presente.

test('shows error message when validation fails', async () => {
  const user = userEvent.setup();
  render(<SignUpForm />);
  await user.click(screen.getByRole('button', { name: /submit/i }));
  expect(screen.getByText('Email is required')).toBeInTheDocument();
});

Envolvendo com provedores

A maioria dos componentes precisa de contexto ou de um roteador. Envolva-os em provedores dentro da chamada de render ou crie um auxiliar personalizado renderWithProviders.

function renderWithProviders(ui: React.ReactElement) {
  return render(
    <QueryClientProvider client={new QueryClient()}>
      <MemoryRouter>
        {ui}
      </MemoryRouter>
    </QueryClientProvider>
  );
}

test('shows user data', () => {
  renderWithProviders(<UserProfile />);
});

Testando alterações de estado

Interaja com o componente e depois verifique se o novo estado está refletido na interface. O RTL envolve a maioria das interações em act automaticamente ao usar userEvent.

test('counter increments', async () => {
  const user = userEvent.setup();
  render(<Counter />);
  expect(screen.getByText('Count: 0')).toBeInTheDocument();
  await user.click(screen.getByRole('button', { name: /increment/i }));
  expect(screen.getByText('Count: 1')).toBeInTheDocument();
});

Auxiliar de depuração da tela

Chame screen.debug() para imprimir o HTML renderizado atual no console — útil quando uma consulta falha e você precisa ver o que foi realmente renderizado.

test('debugging a failing query', () => {
  render(<MyComponent />);
  screen.debug(); // prints rendered HTML
  screen.getByRole('button', { name: /save/i }); // then inspect output
});

Verificação rápida

Qual consulta você deve preferir ao testar um botão no React Testing Library?

Recapitulação

O RTL renderiza componentes e interage com eles por meio de consultas baseadas em funções e userEvent. Envolva os componentes nos provedores necessários, use os verificadores do jest-dom para obter verificações legíveis e prefira queryBy ao verificar a ausência de um elemento.

Perguntas Frequentes

A aula “Testes de integração com React Testing Library” é grátis?

Sim — o texto completo de “Testes de integração com React Testing Library” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.

O que vou aprender em “Testes de integração com React Testing Library”?

Renderize componentes nos testes, dispare eventos e faça asserções sobre a saída visível, não sobre a implementação. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar React Academy?

Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Testes de integração com React Testing Library”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de React Academy?

Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Testes de integração com React Testing Library
Testando interface assíncrona e chamadas de API com MSW
Primeiros passos com Playwright para React
Testando formulários e fluxos do usuário de ponta a ponta

← Voltar para React Academy