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:
expectrecebe o valor que o código produziu, o valor real. - Comparador: Diz o que você espera.
toBecompara com===. Existem outros, comotoEqualpara objetos etoContainpara 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)devolveR$ 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.9viraR$ 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
formatarPrecousa 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.
Deixe os testes rodando localmente
Confira que
npx vitest runenpx playwright testpassam no seu computador.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: configurewebServernoplaywright.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 testAbra um pull request
O resultado aparece no próprio PR: verde se tudo passou, vermelho com o log do passo que falhou.
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,iteexpect. - 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.
- Escreva um teste de unidade para uma função pura, como formatar preço ou filtrar produtos
- Teste a busca com Testing Library, encontrando o campo pelo rótulo
- Simule uma falha da API com um mock e confira a mensagem de erro
- Teste que um formulário inválido mostra o erro e não envia
- Crie o workflow do GitHub Actions e veja um pull request ficar verde