Testes de interface

Provar que a tela funciona como quem usa espera: testes de função, de componente e de ponta a ponta.

Cerca de 14 min · Revisado em

Ao final, você vai conseguir

  • Escrever um teste com organizar, agir e verificar
  • Buscar elementos como uma pessoa usuária faria
  • Escolher entre teste de unidade, de componente e de ponta a ponta

Você corrige o filtro de busca, testa clicando, publica. Dois dias depois alguém avisa que o carrinho parou de somar: sua correção quebrou outra parte e ninguém percebeu. Testes automatizados são pequenos programas que conferem seu programa em segundos, toda vez, sem cansar. Eles são o que deixa você mudar código sem medo.

Uma rede de segurança

Um teste automatizado é um código que usa o seu código e confere se o resultado é o esperado. Você escreve uma vez e roda quantas vezes quiser, com um comando.

Testar clicando na tela continua útil, mas é lento e depende da sua memória. Ninguém reconfere 40 telas a cada mudança. Quando algo que funcionava para de funcionar, isso se chama regressão, e é o tipo de bug que testes pegam melhor.

Qual é o principal ganho de ter testes automatizados num projeto?

  • Mudar o código com confiança, porque uma regressão aparece em segundos
  • Provar que o programa não tem nenhum bug
  • Deixar o site mais rápido para quem usa

Anatomia de um teste

A maioria das ferramentas de teste em JavaScript usa as mesmas três palavras: describe agrupa, it descreve um caso e expect confere um valor. Dentro de cada caso, quase todo teste segue três passos: organizar, agir e verificar.

Um teste de unidade escrito com Vitest, a ferramenta de testes que combina com o Vite.

describe('aplicarCupom', () => {
  it('dá 10% de desconto com o cupom TRILHA10', () => {
    const total = 200;
    const resultado = aplicarCupom(total, 'TRILHA10');
    expect(resultado).toBe(180);
  });
});
  • describe: Agrupa os testes de um mesmo assunto. O nome aparece no relatório, então escreva o que está sendo testado.
  • it: Um caso de teste. Leia em voz alta: “ele dá 10% de desconto com o cupom”. Se a frase não faz sentido, o teste provavelmente confere coisas demais.
  • Organizar: Prepare o cenário: os dados de entrada e o que mais o caso precisar. Em inglês, esse padrão é chamado de Arrange-Act-Assert.
  • Agir: Execute a única coisa que está sendo testada. Um teste com várias ações fica difícil de diagnosticar quando falha.
  • Verificar: expect recebe o valor que o código produziu, o valor real.
  • Comparador: Diz o que você espera. toBe compara com ===. Existem outros, como toEqual para objetos e toContain para listas.

Complete o teste para conferir que formatarPreco(5) devolve R$ 5,00.

____('formata valor inteiro', () => {
  const resultado = formatarPreco(5);
  ____(resultado).____('R$ 5,00');
});

Coloque em ordem o jeito de escrever um bom teste.

  • Escolher um comportamento que a pessoa usuária espera
  • Preparar os dados e o cenário (organizar)
  • Fazer a ação, como chamar a função ou clicar (agir)
  • Conferir o resultado (verificar)
  • Quebrar o código de propósito e ver o teste falhar

Seu primeiro teste de unidade

Um teste de unidade confere uma parte pequena isolada, quase sempre uma função. Os melhores candidatos são funções puras: as que sempre devolvem o mesmo resultado para a mesma entrada e não mexem em nada fora delas, como formatar preço ou validar CEP.

Uma função, o arquivo de teste e o que aparece no terminal

formatarPreco.ts

export function formatarPreco(valor: number): string {
  return 'R$ ' + valor.toFixed(2).replace('.', ',');
}

formatarPreco.test.ts

import { describe, it, expect } from 'vitest';
import { formatarPreco } from './formatarPreco';

describe('formatarPreco', () => {
  it('usa vírgula e duas casas decimais', () => {
    expect(formatarPreco(10.5)).toBe('R$ 10,50');
  });

  it('formata zero', () => {
    expect(formatarPreco(0)).toBe('R$ 0,00');
  });
});

Terminal

$ npx vitest run

 ✓ src/formatarPreco.test.ts (2 tests)
   ✓ formatarPreco > usa vírgula e duas casas decimais
   ✓ formatarPreco > formata zero

 Test Files  1 passed (1)
      Tests  2 passed (2)

Sem instalar nada, dá para sentir como isso funciona. O exercício abaixo traz um executor de testes de dez linhas, parecido com o Vitest, e uma função com defeito. Os testes já estão escritos e falhando.

Faça os testes passarem

Rode e leia o console: cada ✗ diz o que era esperado e o que veio. Conserte só a função formatarPreco até todos os testes mostrarem ✓. Dica: toFixed(2) fixa duas casas e replace troca o ponto pela vírgula.

// Mini executor de testes (não precisa mexer aqui)
function teste(nome, fn) {
  try {
    fn();
    console.log('✓ ' + nome);
  } catch (erro) {
    console.log('✗ ' + nome + ': ' + erro.message);
  }
}

function esperar(valor) {
  return {
    toBe(esperado) {
      if (valor !== esperado) {
        throw new Error('esperava ' + JSON.stringify(esperado) + ', recebeu ' + JSON.stringify(valor));
      }
    },
  };
}

// A função com defeito: conserte aqui
function formatarPreco(valor) {
  return 'R$ ' + valor;
}

// Os testes (não mude)
teste('formata valor inteiro com centavos', () => {
  esperar(formatarPreco(10)).toBe('R$ 10,00');
});
teste('usa vírgula e duas casas', () => {
  esperar(formatarPreco(10.5)).toBe('R$ 10,50');
});
teste('arredonda para duas casas', () => {
  esperar(formatarPreco(3.999)).toBe('R$ 4,00');
});
teste('formata zero', () => {
  esperar(formatarPreco(0)).toBe('R$ 0,00');
});
  • formatarPreco(10.5) devolve R$ 10,50
  • Funciona com inteiros, zero e arredondamento
  • Os quatro testes aparecem com ✓ e nenhum com ✗
  • Também acerta um caso que os testes não cobrem: 99.9 vira R$ 99,90
Todos os testes passaram. E formatarPreco(1500)? Ele devolve R$ 1500,00, sem o ponto de milhar. O teste estava errado?

Não: o teste confere só o que alguém pensou em escrever. Testes passando significam “os casos conhecidos funcionam”, não “não há bugs”. Quando achar um caso novo, escreva o teste dele primeiro, veja falhar e depois corrija. Para moeda de verdade, Intl.NumberFormat resolve milhares, mas usa um espaço especial entre R$ e o número, e o teste precisa saber disso.

Teste como a pessoa usuária

Funções puras são fáceis de testar. Mas o que mais quebra no frontend é a tela: o botão que não aparece, a mensagem de erro que sumiu. Para isso existe o teste de componente: ele desenha um componente numa página simulada e interage com ele.

A Testing Library procura elementos do jeito que uma pessoa (ou um leitor de tela) os encontra: pelo papel (botão, título, campo), pelo rótulo do campo ou pelo texto visível. Repare que isso reaproveita tudo o que você aprendeu em acessibilidade.

Teste de componente com Vitest e Testing Library

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

const produtos = [
  { id: 1, nome: 'Caneca' },
  { id: 2, nome: 'Camiseta' },
];

it('mostra só os produtos que combinam com a busca', async () => {
  const pessoa = userEvent.setup();
  render(<Catalogo produtos={produtos} />);

  await pessoa.type(screen.getByLabelText('Buscar produtos'), 'cam');

  expect(screen.getByRole('heading', { name: 'Camiseta' })).toBeInTheDocument();
  expect(screen.queryByRole('heading', { name: 'Caneca' })).not.toBeInTheDocument();
});

Quais buscas encontram o elemento como uma pessoa faria e quais dependem de detalhes internos?

Como a pessoa usuária · Detalhe interno

  • getByRole('button', { name: 'Adicionar ao carrinho' })
  • getByLabelText('E-mail')
  • getByText('Nenhum produto encontrado')
  • getByRole('heading', { name: 'Camiseta' })
  • container.querySelector('.btn-3')
  • querySelector('div > div:nth-child(2) span')
  • Ler o valor de uma variável interna do componente

E a falha de rede? Num teste você não quer depender de uma API real, que pode estar fora do ar. Você troca o fetch por um dublê que responde o que você mandar. Esse dublê se chama mock.

Simulando a API fora do ar para conferir a mensagem de erro

it('avisa quando a API falha', async () => {
  vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('sem rede'));
  render(<Catalogo />);

  const alerta = await screen.findByRole('alert');
  expect(alerta).toHaveTextContent('Não foi possível carregar os produtos');
});

Unidade, componente e ponta a ponta

Existe um terceiro tipo: o teste de ponta a ponta (em inglês, end-to-end ou e2e). Ele abre um navegador de verdade, entra no site rodando e faz o caminho completo, como uma pessoa faria.

Muitos testes rápidos na base, poucos testes realistas no topo.

  • Ponta a ponta: Navegador real, site inteiro. Prova que a pessoa consegue concluir a tarefa. Lento e mais frágil: guarde para os caminhos críticos, como busca e compra.
  • Componente: Um componente ou tela numa página simulada, com a API trocada por mocks. Prova que a interface reage certo a cliques, digitação e erros.
  • Unidade: Uma função isolada, em milissegundos. Prova regras e casos de borda: formatação, cálculo de frete, validação.

Um teste de ponta a ponta com Playwright

import { test, expect } from '@playwright/test';

test('pessoa busca e favorita um produto', async ({ page }) => {
  await page.goto('http://localhost:5173/');

  await page.getByLabel('Buscar produtos').fill('camiseta');
  await page.getByRole('button', { name: 'Favoritar Camiseta' }).click();

  await expect(page.getByText('Favoritos: 1')).toBeVisible();
});

Qual tipo de teste combina melhor com cada caso?

Unidade · Componente · Ponta a ponta

  • formatarPreco usa vírgula e duas casas
  • Um CEP precisa ter 8 dígitos
  • O formulário mostra erro quando o e-mail está vazio
  • A lista mostra “Nenhum produto” quando a API devolve vazio
  • A pessoa entra, adiciona ao carrinho e finaliza a compra
  • Depois da publicação, a página inicial abre e a busca funciona

Um teste passa no seu computador e falha de vez em quando na CI. Ele clica em “Buscar”, espera 2 segundos fixos e confere a lista. O que está acontecendo?

  • É um teste instável: na CI a resposta às vezes demora mais de 2 segundos. Troque a espera fixa por uma que aguarda o elemento aparecer
  • Aumente a espera para 10 segundos e o problema some
  • A CI está com defeito; rode de novo até passar

Você trocou a classe .card por .cartao-produto. A tela ficou idêntica, mas 12 testes quebraram. O que isso indica?

  • Os testes dependem de detalhes de implementação, e não do que a pessoa vê
  • Os testes funcionaram: pegaram uma mudança
  • É melhor nunca mudar nomes de classes depois de escrever testes

Testes que rodam sozinhos

Teste que só roda quando alguém lembra acaba esquecido. Por isso os projetos usam CI (integração contínua): um serviço que roda lint, testes e build automaticamente a cada push ou pull request.

  1. Deixe os testes rodando localmente

    Confira que npx vitest run e npx playwright test passam no seu computador.

  2. Crie o arquivo de workflow

    No GitHub Actions, a CI do próprio GitHub, um arquivo em .github/workflows/ diz o que rodar. O Playwright precisa saber subir o site: configure webServer no playwright.config.ts.

    name: Testes
    on: [push, pull_request]
    jobs:
      testes:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: 22
              cache: npm
          - run: npm ci
          - run: npx vitest run
          - run: npx playwright install --with-deps
          - run: npx playwright test
  3. Abra um pull request

    O resultado aparece no próprio PR: verde se tudo passou, vermelho com o log do passo que falhou.

  4. Quebre de propósito

    Mude a função para errar, faça push e veja a CI ficar vermelha. Depois corrija e veja voltar ao verde. Agora você confia nela.

A CI ficou vermelha no seu pull request, mas no seu computador tudo passa. Qual o primeiro passo?

  • Abrir o log do passo que falhou e ler qual teste quebrou e com qual mensagem
  • Desativar o teste para conseguir juntar o PR
  • Juntar mesmo assim, já que funciona localmente

Fechamento

  • Um teste automatizado usa seu código e confere o resultado; ele protege contra regressões.
  • Todo teste segue organizar, agir e verificar, com describe, it e expect.
  • Busque elementos como a pessoa usuária: por papel, rótulo e texto, nunca por classe ou posição.
  • Muitos testes de unidade, vários de componente e poucos de ponta a ponta nos fluxos críticos.
  • Testes instáveis e presos a detalhes internos perdem a confiança do time; a CI roda tudo a cada pull request.

Proteja o catálogo com testes

No projeto de catálogo que você está construindo, escreva testes para os três momentos que mais quebram em telas reais e coloque tudo para rodar sozinho.

  1. Escreva um teste de unidade para uma função pura, como formatar preço ou filtrar produtos
  2. Teste a busca com Testing Library, encontrando o campo pelo rótulo
  3. Simule uma falha da API com um mock e confira a mensagem de erro
  4. Teste que um formulário inválido mostra o erro e não envia
  5. Crie o workflow do GitHub Actions e veja um pull request ficar verde

Referências

Cursos relacionados