Como escrever testes em Python usando doctest

Como desenvolvedores, muitas vezes escrevemos casos de teste e comentários para explicar nosso código. Os comentários melhoram a legibilidade e a qualidade da base de código. Comentários detalhados podem nos lembrar por que implementamos determinada funcionalidade. Eles também ajudam outros programadores a entender, manter, usar e expandir bases de código.

Uma das boas práticas é escrever primeiro os comentários e os casos de teste das suas funções. Isso ajuda você a produzir código de melhor qualidade e a manter em vista os diferentes casos extremos e requisitos da função. No entanto, os métodos tradicionais consomem muito tempo, pois precisamos preparar um arquivo separado para os casos de teste e escrever funções extensas para cada teste.

A ferramenta doctest do Python é muito útil nessas situações. A comunidade de código aberto desenvolveu o módulo doctest para oferecer uma estrutura eficiente de testes durante o desenvolvimento. Podemos usar o doctest para escrever testes para o código da função, definindo os valores de entrada e saída. Assim, economizamos tempo e esforço ao criar código de alta qualidade.

Parece ótimo, mas como escrever um doctest em Python? Neste artigo, vamos mostrar como configurar, escrever e testar seu primeiro doctest — com todas as informações de que você precisa para começar.

Como escrever seu primeiro doctest

Antes de começar a escrever seu primeiro doctest em Python, verifique se você tem o Python 3 e um ambiente de programação adequado instalados no computador, como o Visual Studio Code (VS Code). Neste tutorial, vamos usar o VS Code como ambiente de desenvolvimento integrado (IDE).

Configurando a IDE

Depois de instalar o Python 3, verifique se a instalação foi concluída com sucesso. No Windows, digite o seguinte trecho de código no prompt de comando:

1py -3 --version

No macOS ou Unix, abra o terminal e digite o seguinte comando:

1python3 --version.

Em seguida, baixe a IDE Visual Studio Code.

Abra o assistente de instalação e siga as instruções na tela para instalar o VS Code.

Depois de abrir o VS Code, baixe a extensão Python na guia Extensões. Agora, você já pode usar Python no VS Code.

Conheça as docstrings

O Python tem um recurso chamado docstring. As docstrings são literais de string que usamos na declaração de uma função, classe ou módulo para incluir comentários e casos de teste nas funções. Por isso, elas são essenciais tanto para a documentação quanto para os testes.

Podemos escrever uma docstring entre três aspas:

1"""

Depois da docstring, podemos escrever os comentários e os testes, também entre três aspas.

1"""

Neste tutorial, vamos aprender a sintaxe dos casos de teste e dos comentários. À primeira vista, uma docstring e um comentário podem parecer iguais. No entanto, eles têm finalidades diferentes. Os comentários explicam a implementação do código, enquanto as docstrings documentam classes, métodos e funções. Elas ajudam outros programadores a entender a finalidade de uma função e como usá-la no trabalho.

O módulo doctest identifica docstrings em definições de funções ou classes. Para distinguir os casos de teste dos comentários, colocamos o símbolo >>> antes dos testes na docstring.

Abra a linha de comando do seu sistema operacional e digite python3.

O shell interativo do Python 3 usa o símbolo >>> como prompt e retorna a saída sem esse símbolo. Suponha que imprimimos um valor. A sessão interativa fica assim:

O módulo doctest procura e identifica na docstring padrões que se parecem com sessões interativas do Python. Quando os encontra, executa-os. Os doctests precisam estar na docstring inicial, logo após a chamada da função ou o cabeçalho do método. Evite espaços extras ao escrever o doctest para prevenir erros ou falhas inesperados.

Escrevendo um doctest

Para usar doctests, primeiro vamos escrever um exemplo de código. Neste tutorial, vamos criar um módulo simples chamado square.py, com uma função chamada square. A função calcula o quadrado do valor de entrada.

1def square(x):
2    return x*x

Agora, incluímos uma docstring na função. Ela contém a documentação que descreve o que a função faz, além de dois casos de teste com os valores de entrada e as saídas esperadas. Esses valores são usados para testar o resultado processado.

1def square(x):
2    """
3    This function returns the square of the input.
4    >>> square(2)
5    4
6    >>> square(5)
7    25
8    """
9    return x*x

Como o resultado processado é testado?

O módulo doctest analisa a docstring e gera texto. Ele executa o texto analisado como um comando do shell do Python. Em seguida, compara o resultado com o valor esperado indicado na docstring.

Como executar um doctest

Para executar o doctest usando nosso módulo, square.py, adicionamos a função testmod do doctest. A função doctest.testmod testa o módulo m ou o módulo "_main_", caso m não seja informado. Essa função é necessária para executar o doctest.

1def square(x):
2    """
3    This function returns the square of the input.
4    >>> square(2)
5    4
6    >>> square(5)
7    25
8    """
9    return x*x
10
11if __name__ == "__main__":
12    import doctest
13    doctest.testmod() #test the whole module.

Depois, basta executar o módulo square.py no terminal com o comando:

1python square.py

Como square.py tem apenas uma função, o módulo doctest testa somente essa função.

Como não há saída, todos os testes passaram. Se algum teste falhar, o erro aparecerá no terminal e poderemos resolvê-lo. Para ver o log, alteramos o script adicionando -v:

1python square.py -v

Os logs mostram os resultados com mais detalhes, incluindo os índices de sucesso e falha dos testes. Também podemos usar um atalho prático para executar a função testmod sem a função main: basta executar diretamente o módulo doctest, que faz parte da biblioteca padrão. Para isso, passamos o nome do módulo à interface de linha de comando:

1python -m doctest -v square.py

Agora, vamos ampliar um pouco o exemplo anterior. E se você quiser especificar os tipos de dados de entrada e saída da função? Para isso, basta fazer uma pequena alteração na docstring. Usando o exemplo anterior, é só adicionar:

1:param a: int
2:return: int

Assim, nossa docstring fica:

1def square(x):
2    """
3    This function returns the square of the input.
4    :param a: int
5    :return: int
6    >>> square(2)
7    4
8    >>> square(5)
9    25
10    """
11    return x*x

Se tivermos mais de um parâmetro de entrada, podemos ajustar :param. Suponha que tenhamos dois parâmetros de entrada. A docstring correspondente seria:

1:param a: int
2:param b: int
3:return: int

Podemos fazer o mesmo para quantos parâmetros de entrada forem necessários.

Parabéns! Você acabou de escrever um doctest.

Conclusão

Neste artigo, apresentamos o módulo doctest do Python e mostramos como os doctests podem melhorar a qualidade do código e contribuir para uma abordagem melhor de programação.

Também mostramos como incluir doctests em funções e executá-los usando o arquivo de código e o terminal — além de demonstrar como é fácil usar o módulo doctest na programação.

A abordagem clássica para testar funções é escrever um script independente com os casos de teste. Os doctests eliminam a necessidade desses scripts e permitem testar o código com mais eficiência. Em resumo, eles simplificam os testes e melhoram a qualidade do código Python.