Matchers do Jest: Dominando as Comparações nos Testes

Matchers Comuns

Esses são os matchers que você mais vai usar no dia a dia:

Copiar
-.toBe()  
//Usa `===` para comparar valores primitivos.  
expect(1 + 1).toBe(2);

- .toEqual()  
//Compara objetos e arrays profundamente.  
expect({ nome: 'Ana' }).toEqual({ nome: 'Ana' });

- .toContain()  
//Verifica se um item está presente em um array ou string.  
expect(['JS', 'Jest']).toContain('Jest');
expect('Testando').toContain('ando');

- .toHaveLength()  
//.Testa o tamanho de arrays, strings ou objetos com propriedade `.length`.  
expect([1, 2, 3]).toHaveLength(3);


- .toBeTruthy()` / `.toBeFalsy() 
//Verifica se um valor é avaliado como verdadeiro ou falso.  
expect(true).toBeTruthy();
expect(0).toBeFalsy();

🚨 Matchers para Erros e Exceções

Quando esperamos que uma função lance um erro, usamos o .toThrow():

Copiar
function erro() {
  throw new Error('Erro inesperado!');
}

expect(erro).toThrow();
expect(erro).toThrow('Erro inesperado');

Esse matcher é muito útil para testar funções que precisam tratar exceções corretamente.

---

✨ Criando Matchers Customizados

Os matchers são funções que o Jest usa para comparar o valor retornado pelo seu código com o valor esperado. Por padrão, o Jest oferece vários, como .toBe(), .toEqual(), etc.

Mas às vezes, você quer escrever um teste que faz uma verificação bem específica — por exemplo, testar se um número é par, se um texto está em formato de e-mail, ou se um objeto representa um usuário válido. É aí que entram os matchers customizados.

Como criar?

O Jest oferece a função expect.extend(), que você usa para registrar novos matchers.

Aqui está o exemplo com comentários:

Copiar
expect.extend({
  toBeEven(received) {
    const pass = received % 2 === 0;
    if (pass) {
      return {
        message: () => `Esperava que ${received} não fosse par`,
        pass: true,
      };
    } else {
      return {
        message: () => `Esperava que ${received} fosse par`,
        pass: false,
      };
    }
  },
});

// Uso:
expect(4).toBeEven(); // Passa
expect(5).toBeEven(); // Falha

Por que criar seus próprios matchers?

Criar matchers customizados no Jest não é apenas um recurso "avançado" — é uma forma de deixar seus testes mais legíveis, reutilizáveis e fáceis de manter.

🔹 Clareza nos testes Quando você escreve um teste como:

Copiar
expect(valor % 2 === 0).toBe(true);

Ele funciona, mas não é tão legível, especialmente para quem está lendo o teste pela primeira vez. Já com um matcher customizado, como:

Copiar
expect(valor).toBeEven();

o teste parece quase uma frase natural — direto ao ponto, sem lógica exposta no teste. Isso melhora a compreensão do propósito do teste, tanto para você quanto para quem revisa seu código.

🔹 Evita duplicação de lógica Imagine que você precisa testar se números são pares em vários testes diferentes. Em vez de escrever a mesma condição repetidamente (valor % 2 === 0), você escreve isso uma única vez dentro do matcher, e depois apenas o utiliza onde for necessário. Assim, se a regra mudar (por exemplo, aceitar somente números pares positivos), você altera a lógica em um lugar só.

🔹 Mensagens de erro mais úteis Com matchers personalizados, você pode definir mensagens específicas para falhas, o que ajuda bastante na hora de depurar testes que quebraram.

Compare:

Copiar
expect(valor % 2 === 0).toBe(true);
// Falha: Expected value to be true, received false

Com:

Copiar
expect(valor).toBeEven();
// Falha: Esperava que 5 fosse par

No segundo exemplo, a mensagem já diz exatamente o que aconteceu, sem você precisar interpretar a lógica do teste.

Dica: use matchers customizados quando…

• Você repete muito a mesma verificação em diferentes testes.
• A condição testada é um pouco mais complexa do que o comum.
• Você quer que seus testes fiquem mais legíveis, como se fossem frases.
• Você está escrevendo testes para regras de negócio específicas (ex: “usuário válido”, “transação aprovada”, etc).