Python Doctest

Verificando Exceções em Python Usando `doctest`

Ao escrever código em Python, frequentemente precisamos garantir que nossas funções se comportem conforme o esperado, especialmente em relação ao tratamento de erros. Um cenário comum é testar se uma função gera uma exceção sob certas condições. Se você está usando o módulo doctest do Python para realizar seus testes, pode estar se perguntando: Posso verificar se uma exceção é gerada com doctest? A resposta é um sonoro sim! Vamos explorar como utilizar doctest para verificar exceções em suas funções Python.

O Problema: Testando Exceções

Considere uma função chamada foo(x). Essa função é projetada para levantar uma exceção se seu argumento for menor que zero. A pergunta central aqui é como escrever um doctest que confirme que a função se comporta corretamente nesse cenário. Especificamente, quando passamos um valor menor que zero, queremos garantir que uma exceção seja levantada para indicar que algo deu errado.

Função de Exemplo

Aqui está uma versão simples da função foo(x):

def foo(x):
    if x < 0:
        raise ValueError("x deve ser não-negativo")
    return x

A Solução: Escrevendo um `doctest`

Para criar um doctest que verifica exceções, utilizaremos a seguinte abordagem. Em nosso doctest, podemos especificar que esperamos que uma exceção seja levantada ao chamar foo() com um valor que deve acionar o erro. Aqui está como fazer isso passo a passo:

Passo 1: Escreva o Doctest

Na docstring da sua função, você pode adicionar um caso de teste demonstrando a exceção esperada. Veja como fica:

def foo(x):
    """
    Retorna x se for não-negativo.
    
    Levanta:
        ValueError: Se x < 0.
    
    Exemplos:
    >>> foo(-1)
    Traceback (most recent call last):
      ...
    ValueError: x deve ser não-negativo
    >>> foo(3)
    3
    """
    if x < 0:
        raise ValueError("x deve ser não-negativo")
    return x

Passo 2: Execute o Doctest

Para executar o doctest, inclua o seguinte trecho no final do seu script Python:

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Passo 3: Saída Esperada

Quando você executar o script, o doctest irá processar os exemplos na docstring. Se tudo estiver funcionando corretamente, você não verá nenhuma saída (indicando que todos os testes passaram). Se a exceção não for levantada como esperado, o doctest irá reportar um erro.

Recursos Adicionais

Para mais informações sobre como usar eficazmente o doctest em seus módulos, consulte a documentação oficial do módulo doctest.

Conclusão

Usar o doctest para verificar se as exceções são levantadas corretamente não é apenas possível; é simples! Ao adicionar algumas linhas na docstring de sua função, você pode efetivamente documentar e testar o comportamento do seu código, garantindo que ele se adeque aos padrões esperados. Seja escrevendo novas funções ou testando as existentes, o doctest oferece uma maneira poderosa de incluir testes orientados a exemplos diretamente ao lado do seu código. Aproveite para tornar seu código robusto e boas codificações!

Verificando Exceções em Python Usando doctest