A biblioteca Gomega, amplamente adotada como o conjunto de matchers preferido para o framework de testes Ginkgo em Go, oferece funcionalidades robustas para o tratamento e verificação de erros. Este artigo tem como objetivo explorar em profundidade dois matchers cruciais para a validação de erros: MatchError e MatchErrorStrictly. Ao compreender suas diferenças e cenários de uso, desenvolvedores podem aprimorar a exatidão e resiliência de seus testes em Go.

Análise dos Principais Matchers de Erro

1. MatchError: A Abordagem Flexível

O MatchError é um dos matchers mais versáteis do Gomega para trabalhar com erros. Ele oferece diversas estratégias de correspondência, adequando-se a variados cenários de teste:

• Comparação de Mensagens: Verifica se a mensagem de erro corresponde a uma string específica.
• Validação de Instância ou Tipo: Utiliza a função errors.Is para identificar se o erro é ou contém uma instância de erro específica na sua cadeia.
• Funções de Verificação Personalizadas: Aceita funções que permitem uma lógica de validação de erro customizada.
• Aninhamento com Sub-Matchers: Permite combinar com outros matchers, como ContainSubstring, para validações mais complexas de strings dentro da mensagem de erro.

Internamente, MatchError vai além de uma simples comparação, aplicando errors.Is para checar a cadeia de erros e, se necessário, percorrendo-a com errors.Unwrap para buscar correspondências profundas.

2. MatchErrorStrictly: Verificação Estrita da Identidade

Em contraste, MatchErrorStrictly adota uma postura mais rigorosa na validação de erros. Sua funcionaldiade é focada exclusivamente na identificação precisa da instância de erro, dependendo estritamente de errors.Is. Este matcher não suporta comparações de string, aninhamento com sub-matchers ou funções de validação personalizadas. Sua principal finalidade é assegurar que o erro correspondente seja exatamente o tipo ou a instância esperada na cadeia de erro, sem se preocupar com a mensagem.

Comparativo de Diferenças Chave

A tabela a seguir resume as capacidades de correspondência de cada matcher:

Cenários de Uso Distintos

• MatchError é ideal para:
  • Validar o conteúdo da mensagem de erro (total ou parcial).
  • Verificar a presença de um erro específico em uma cadeia de erros.
  • Situações que exigem flexibilidade nos critérios de correspondência.
• MatchErrorStrictly é ideal para:
  • Confirmar a identidade exata de um tipo ou instância de erro.
  • Garantir que o erro retornado seja precisamente o que foi definido.
  • Evitar falhas em testes devido a pequenas alterações nas mensagens de erro.

Exemplos Práticos de Código

Para ilustrar o uso de ambos os matchers, considere os seguintes exemplos:

Utilização Básica de MatchError

Abaixo, demonstramos como MatchError pode ser usado para diferentes tipos de validação.

package main_test // ou outro pacote de teste

import (
    "errors"
    "fmt"
    "os"
    "strings"
    . "github.com/onsi/gomega"
    "github.com/onsi/gomega/types" // Para tipos de matcher personalizados
)

// Erro base específico para o teste de função personalizada
var ErroPermissaoBase = errors.New("permissão insuficiente")

// Função auxiliar que simula um processo que retorna erros
func processarRecurso(id string) error {
    if id == "invalido" {
        return errors.New("identificador de recurso inválido")
    }
    if id == "nao_encontrado" {
        return os.ErrNotExist // Um erro predefinido de sistema
    }
    if id == "acesso_negado" {
        return fmt.Errorf("falha de permissão de acesso: %w", ErroPermissaoBase) // Erro encadeado
    }
    return nil
}

// Exemplo de uso em um contexto de teste (Ginkgo "It" ou função de teste Go padrão)
func TestMatchErrorExamples() {
    // 1. Correspondência por string da mensagem de erro
    erro := processarRecurso("invalido")
    Expect(erro).To(MatchError("identificador de recurso inválido"))

    // 2. Correspondência por instância de erro (usando errors.Is)
    erro = processarRecurso("nao_encontrado")
    Expect(erro).To(MatchError(os.ErrNotExist))

    // 3. Correspondência parcial da mensagem com sub-matcher
    erro = processarRecurso("acesso_negado")
    Expect(erro).To(MatchError(ContainSubstring("permissão de acesso")))

    // 4. Correspondência com função de validação personalizada
    // Verifica se o erro contém ErroPermissaoBase em sua cadeia
    erro = processarRecurso("acesso_negado")
    Expect(erro).To(MatchError(types.GomegaMatcher(
        func(actual interface{}) (bool, error) {
            e, ok := actual.(error)
            if !ok {
                return false, fmt.Errorf("esperava um erro, mas recebeu %T", actual)
            }
            // Verifica se ErroPermissaoBase está na cadeia de erros
            return errors.Is(e, ErroPermissaoBase), nil
        },
        fmt.Sprintf("deve conter o erro base '%s' na cadeia", ErroPermissaoBase.Error()), // Mensagem de falha para o matcher
    )))
}

Utilização de MatchErrorStrictly

Este matcher é empregado quando a identidade exata do erro é primordial.

package main_test // ou outro pacote de teste

import (
    "errors"
    "fmt"
    . "github.com/onsi/gomega"
)

// Erros personalizados para os testes
var (
    ErroDeConfiguracao = errors.New("erro de configuração do sistema")
    ErroDeConexao = errors.New("falha na conexão com o serviço")
)

// Função auxiliar que pode retornar erros específicos
func iniciarServico(configOK bool) error {
    if !configOK {
        return ErroDeConfiguracao
    }
    // Simula um erro encadeado, onde ErroDeConexao é o erro base
    return fmt.Errorf("não foi possível conectar ao backend: %w", ErroDeConexao)
}

// Exemplo de uso em um contexto de teste
func TestMatchErrorStrictlyExamples() {
    // 1. Correspondência estrita de uma instância de erro
    errConfig := iniciarServico(false)
    Expect(errConfig).To(MatchErrorStrictly(ErroDeConfiguracao))

    // 2. Correspondência de um erro base dentro de uma cadeia de erros (via errors.Is)
    errConexaoWrapper := iniciarServico(true) // Retorna um erro encadeado
    Expect(errConexaoWrapper).To(MatchErrorStrictly(ErroDeConexao))

    // Este teste falharia: o erro retornado não é ErroDeConfiguracao nem o contém via errors.Is
    // var outroErro = errors.New("outro erro completamente diferente")
    // Expect(outroErro).To(MatchErrorStrictly(ErroDeConfiguracao))
}

Recomendações para Boas Práticas

1. Priorize MatchErrorStrictly para Identidade: Quando o teste exige a validação da *identidade* de um erro (por exemplo, se é uma instância específica ou um erro base em uma cadeia), MatchErrorStrictly é a escolha mais robusta. Isso ajuda a evitar que testes quebrem por mudanças triviais nas mensagens de erro.
2. Use MatchError para Validação de Mensagens: Se a verificação do conteúdo da mensagem de erro for crucial, MatchError deve ser usado, possivelmente em conjunto com matchers de string como ContainSubstring.
3. Cuidado com a Rigidez Excessiva: Ao lidar com bibliotecas de terceiros que podem alterar mensagens de erro, MatchError com ContainSubstring pode ser uma opção mais flexível do que uma correspondência de string exata, garantindo que o teste não seja excessivamente frágil.
4. Verificação de Erros nil: Para verificar a ausência de um erro (ou seja, um erro nil), utilize Expect(err).ToNot(HaveOccurred()). Esta forma é mais legível e intencional do que tentar combinar nil com MatchError.