Diferenças entre as versões de 2 e 8 (6 versões de distância)

doctest: teste automatizado utilizando DocStrings

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

Por exemplo:

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

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

Uma preocupação maior seria sempre assegurar que o que escrevemos está correto, mesmo quando procuramos melhorar ou até mesmo reescrever o que fizemos. Mas como certificar que não quebramos nada enquanto mudamos?

A resposta está nos testes automatizados que vão garantir (se bem escolhidos) que a nossa nova implemenmtação funciona como a anterior.

Repare nos exemplos apresentados para descrever a função fatorial, que tal usar esses exemplos como teste?

Isto é possível através do módulo doctest do Python. vejamos como utilizar

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

O que eu quero executar e testar eu formato igualzinho como eu usaria no modo interativo do Python (repare nos >>> antes). a saída esperada eu acrescento 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 o if x == 0: return 1 para if x == 0: return 0, 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.

-  ⇤ ← Revisão  2e 2004-07-19 18:53:23 → 
  Tamanho: 1223
  Editor: RudaMoura
  Comentário:
+   ← Revisão  8e 2004-07-19 19:24:40 → ⇥
  Tamanho: 2589
  Editor: RudaMoura
  Comentário:
-Deleções são marcadas assim.
+Adições são marcadas assim.
 Linha 1:
-DocTest - teste automatizado de módulos utilizando as DocStrings.
+= doctest: teste automatizado utilizando DocStrings =
 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 direito o código que escreve.
A linguagem Python é bem amiga nesse aspecto, com utilização de DocStrings.
-Linha 7:
+Linha 6:
+Por exemplo:
 Linha 10:
-  >>> f(0)
+  >>> fat(0)
-Linha 12:
+Linha 13:
-  >>> f(5)
+  >>> fat(5)
-Linha 18:
+Linha 19:
-    return x * f(x-1)
+    return x * fat(x-1)
-Linha 21:
+Linha 22:
-É uma definição bem documentada da função fatorial, digamos, no módulo
minhasfuncoes.py.
+é uma implementação documentada da função fatorial, dentro de um
possível módulo {{{minhasfuncoes.py}}}.
-Linha 26:
+Linha 27:
-a implementação de uma função ou classe em Python. Mas como certificar
que não quebramos nada enquanto mudamos?
A resposta está nos testes. 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
+o que fizemos. Mas como certificar que não quebramos nada enquanto mudamos?

A resposta está nos testes automatizados que vão garantir (se bem escolhidos)
que a nossa nova implemenmtação funciona como a anterior.

Repare nos exemplos apresentados para
descrever a função fatorial, que tal usar esses exemplos
-Linha 33:
+Linha 36:
-Em vez de eu escrever a minha função test() e assim escrever
novamente esses exemplos dentro desta função, eu posso usar
o módulo doctest do Python, para automaticamente testar e assegurar
que o que eu escrevi ou reescrevi continua correto.
+Isto é possível através do módulo {{{doctest}}} do Python. vejamos
como utilizar
{{{#!python
def fat(n):
  """Calcula o fatorial de n.

  >>> fat(0)
  1
  >>> fat(5)
  120
  """
  if n == 0:
    return 1
  else:
    return n * fat(n-1)

def _test():
  import doctest, minhasfuncoes
  return doctest.testmod(minhasfuncoes)

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

O que eu quero executar e testar eu formato igualzinho
como eu usaria no modo interativo do Python (repare nos >>> antes).
a saída esperada eu acrescento 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 o {{{if x == 0: return 1}}} para {{{if x == 0: return 0}}},
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.

Veja também:

Diferenças para "DocTest"

doctest: teste automatizado utilizando DocStrings

Para saber mais