Python: Documentação e testes

Palavras-chave: testes, unittest, docstring, documentação, testes unitários, rest, docutils

Todo desenvolvedor sabe que fazer testes é superimportante e que fazer documentação também é algo que melhora a qualidade de seus produtos. Mas num primeiro momento, fazer testes é trabalhoso e documentar o nosso código também costuma ser muito chato.

E se a gente conseguisse fazer as duas coisas ao mesmo tempo e obter bons testes e boa documentação? Com o módulo doctest do Python é possível fazer isso. Veja o exemplo abaixo (que foi parcialmente tirado da documentação do módulo):

# -*- coding: utf-8 -*-
import doctest

def fatorial(valor):
    """fatorial(int) -> int
    A função fatorial pode ser usada para calcular
    o fatorial de um número n onde n > 0 vejam os exemplos::
       >>> fatorial(15)
       1307674368000L
       >>> fatorial(-1)
       Traceback (most recent call last):
       ...
       ValueError: valor precisa ser > 0
       >>> fatorial(15.1)
       Traceback (most recent call last):
       ...
       ValueError: valor precisa ser inteiro
    """
    if valor < 0:
        raise ValueError("valor precisa ser > 0")

    if not isinstance(valor, (int,long)):
        raise ValueError("valor precisa ser inteiro")

    if valor:
        return valor * fatorial(valor - 1)
    return 1

if __name__ == '__main__':
    doctest.testmod()

Agora, para rodar nossos testes basta executar esse exemplo:

$ python fatorial.py -v
:
1 items passed all tests:
   3 tests in __main__.fatorial
3 tests in 2 items.
3 passed and 0 failed.
Test passed.

Além de colocar os testes dentro das docstrings também podemos usar arquivos texto convencionais para essa mesma finalidade. A documentação pode usar o formato ReST usado pelos utilitários docutils.