Diferenças entre as versões de 4 e 17 (13 versões de distância)

doctest: Assegurando que documentação e implementação estejam sempre corretos

Um bom programador procura documentar o código que escreve. A linguagem Python é amiga do programador nesse aspecto com utilização de DocStrings.

Por exemplo:

   1 # minhasfuncoes.py
   2 
   3 def fat(n):
   4   """Calcula o fatorial de n.
   5 
   6   Exemplo de uso:
   7   >>> fat(0)
   8   1
   9   >>> fat(5)
  10   120
  11   """
  12   if x == 0:
  13     return 1
  14   else:
  15     return x * fat(x-1)

é uma implementação bem documentada da função fatorial dentro de um possível módulo chamado minhasfuncoes.

Uma preocupação maior seria sempre assegurar que o que escrevemos, código e documentação, estejam sempre em sincronia e corretos, mesmo quando procuramos melhorar ou até mesmo reescrever o que fizemos. Mas como certificar que não quebramos nada enquanto mudamos?

Repare nos exemplos apresentados para descrever a função fatorial, que tal usá-los como garantia de que não fizemos bobagem? Isto tudo é possível através do módulo doctest do Python. vejamos como

   1 # minhasfuncoes.py
   2 
   3 def fat(n):
   4   """Calcula o fatorial de n.
   5 
   6   Exemplo de uso:
   7   >>> fat(0)
   8   1
   9   >>> fat(5)
  10   120
  11   """
  12   if n == 0:
  13     return 1
  14   else:
  15     return n * fat(n-1)
  16 
  17 def _test():
  18   import doctest, minhasfuncoes
  19   return doctest.testmod(minhasfuncoes)
  20 
  21 if __name__ == '__main__':
  22   _test()

O que se quer executar e testar formata-se igual ao que se usaria no modo interativo do Python (repare nos >>> antes). a saída esperada é indicada na linha logo a baixo, conforme deveria ser numa seção interativa.

Para rodar o teste é simples, python minhasfuncoes.py. Se nenhum erro acontecer a saída é muda, nada aparece na tela.

Digamos que eu mude if x == 0: return 1 para if x == 0: return 0 na implementação, a execução do teste me dirá que

$ python minhasfuncoes.py
*****************************************************************
Failure in example: fat(0)
from line #1 of minhasfuncoes.fat
Expected: 1
Got: 0
*****************************************************************
Failure in example: fat(5)
from line #3 of minhasfuncoes.fat
Expected: 120
Got: 0
*****************************************************************
1 items had failures:
   2 of   2 in minhasfuncoes.fat
***Test Failed*** 2 failures.

para fat(0) era esperado o valor 1, veio 0. Para fat(5) era esperado 120, veio 0 também. Dois erros foram indicados através da própria documentação da função.

Para saber mais

Procure a documentação do doctest (>>> help(doctest)).
Um exemplo de uso em VerificadorDeCpf.

--BR RudaMoura

-  ⇤ ← Revisão  4e 2004-07-19 19:01:26 → 
  Tamanho: 1905
  Editor: RudaMoura
  Comentário:
+   ← Revisão  17e 2004-07-19 21:36:06 → ⇥
  Tamanho: 2669
  Editor: RudaMoura
  Comentário:
-Deleções são marcadas assim.
+Adições são marcadas assim.
 Linha 1:
-= doctest: teste automatizado utilizando DocStrings =
+= doctest: Assegurando que documentação e implementação estejam sempre corretos =
 Linha 3:
-Você que é bom programador e cuidadoso, aposto que procuras documentar
direito o código que escreves. A linguagem Python é bem amiga nesse aspecto,
com a utilização de DocStrings. Por exemplo:
+Um bom programador procura documentar o código que escreve.
A linguagem Python é amiga do programador nesse aspecto
com utilização de DocStrings.
 Linha 7:
+Por exemplo:
-Linha 8:
+Linha 9:
+# minhasfuncoes.py
-Linha 10:
+Linha 13:
-  >>> f(0)
+  Exemplo de uso:
  >>> fat(0)
-Linha 12:
+Linha 17:
-  >>> f(5)
+  >>> fat(5)
-Linha 18:
+Linha 23:
-    return x * f(x-1)
+    return x * fat(x-1)
-Linha 21:
+Linha 26:
-é uma implementação bem documentada da função fatorial dentro de um hipotético
módulo {{{minhasfuncoes.py}}}.
+é uma implementação bem documentada da função fatorial dentro de um
possível módulo chamado {{{minhasfuncoes}}}.
-Linha 24:
+Linha 29:
-Uma preocupação maior seria sempre assegurar que o que escrevemos
está correto, mesmo quando procuramos melhorar ou até mesmo reescrever
a implementação de uma função ou classe em Python. Mas como certificar
que não quebramos nada enquanto mudamos?
+Uma preocupação maior seria sempre assegurar que o que escrevemos,
código e documentação, estejam sempre em sincronia e corretos,
mesmo quando procuramos melhorar ou até mesmo reescrever
o que fizemos. Mas como certificar que não quebramos nada enquanto mudamos?
-Linha 29:
+Linha 34:
-A resposta está nos testes automatizados.
Escolher bem o que testar e como testar é uma arte em si.
Repare nos exemplos que eu escrevi para
descrever a função fatorial, que tal eu usar esses exemplos
como teste?
+Repare nos exemplos apresentados para descrever a função fatorial,
que tal usá-los como garantia de que não fizemos bobagem?
Isto tudo é possível através do
módulo {{{doctest}}} do Python. vejamos como
{{{#!python
# minhasfuncoes.py
-Linha 35:
+Linha 41:
-Eu poderia escrever a uma função test() e assim escrever
novamente esses exemplos dentro desta função e conferir
se não tem nada errado com a entrada e a saída da função.

{{{#!python
-Linha 42:
+Linha 43:
-  >>> f(0)
+  Exemplo de uso:
  >>> fat(0)
-Linha 44:
+Linha 47:
-  >>> f(5)
+  >>> fat(5)
-Linha 47:
+Linha 50:
-  if x == 0:
+  if n == 0:
-Linha 50:
+Linha 53:
-    return x * f(x-1)

def test():
  assert f(0) == 1
  assert f(5) == 120

if __name__ == '__main__':
  test()
}}}

Mas tem um jeito melhor e mais amigo de fazer isso, através do módulo
{{{doctest}}} do Python. Aproveitando os próprios exemplos documentados
e sem copiar tudo novamente (passível de falha isso).

{{{#!python
def fat(n):
  """Calcula o fatorial de n.
  >>> f(0)
  1
  >>> f(5)
  120
  """
  if x == 0:
    return 1
  else:
    return x * f(x-1)
+    return n * fat(n-1)
-Linha 85:
+Linha 63:
+O que se quer executar e testar formata-se igual
ao que se usaria no modo interativo do Python (repare nos {{{>>>}}} antes).
a saída esperada é indicada na linha logo a baixo,
conforme deveria ser numa seção interativa.
-Linha 86:
+Linha 68:
+Para rodar o teste é simples, {{{python minhasfuncoes.py}}}.
Se nenhum erro acontecer a saída é muda, nada aparece na tela.
-Linha 87:
+Linha 71:
+Digamos que eu mude {{{if x == 0: return 1}}} para
{{{if x == 0: return 0}}} na implementação,
a execução do teste me dirá que
{{{
$ python minhasfuncoes.py
*****************************************************************
Failure in example: fat(0)
from line #1 of minhasfuncoes.fat
Expected: 1
Got: 0
*****************************************************************
Failure in example: fat(5)
from line #3 of minhasfuncoes.fat
Expected: 120
Got: 0
*****************************************************************
1 items had failures:
   2 of   2 in minhasfuncoes.fat
***Test Failed*** 2 failures.
}}}

para {{{fat(0)}}} era esperado o valor 1, veio 0.
Para {{{fat(5)}}} era esperado 120, veio 0 também.
Dois erros foram indicados através da própria documentação da função.

== Para saber mais ==
  * Procure a documentação do doctest ({{{>>> help(doctest)}}}).
  * Um exemplo de uso em VerificadorDeCpf.

--[[BR]]
RudaMoura

Veja também:

Diferenças para "DocTest"

doctest: Assegurando que documentação e implementação estejam sempre corretos

Para saber mais