Diferenças entre as versões de 6 e 11 (5 versões de distância)

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

Um bom programador procura documentar direito o código que escreve. A linguagem Python é amiga do programador 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 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, estão 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 é possível através do módulo doctest do Python. vejamos como

   1 # este é o módulo minhasfuncoes.py
   2 
   3 def fat(n):
   4   """Calcula o fatorial de n.
   5 
   6   >>> fat(0)
   7   1
   8   >>> fat(5)
   9   120
  10   """
  11   if n == 0:
  12     return 1
  13   else:
  14     return n * fat(n-1)
  15 
  16 def _test():
  17   import doctest, minhasfuncoes
  18   return doctest.testmod(minhasfuncoes)
  19 
  20 if __name__ == '__main__':
  21   _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.

-- RudaMoura

-  ⇤ ← Revisão  6e 2004-07-19 19:15:37 → 
  Tamanho: 2526
  Editor: RudaMoura
  Comentário:
+   ← Revisão  11e 2004-07-19 19:43:40 → ⇥
  Tamanho: 2603
  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 4:
-A linguagem Python é bem amiga nesse aspecto com utilização de DocStrings.
+A linguagem Python é amiga do programador nesse aspecto
com utilização de DocStrings.
-Linha 23:
+Linha 24:
-possível módulo {{{minhasfuncoes.py}}}.
+possível módulo chamado {{{minhasfuncoes}}}.
-Linha 25:
+Linha 26:
-Uma preocupação maior seria sempre assegurar que o que escrevemos
está correto, mesmo quando procuramos melhorar ou até mesmo reescrever
o que fizemos com a função fatorial. 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, estão corretos,
mesmo quando procuramos melhorar ou até mesmo reescrever
o que fizemos. Mas como certificar que não quebramos nada enquanto mudamos?
-Linha 30:
+Linha 31:
-A resposta está nos testes automatizados, que vão garantir (se bem escolhido)
que não quebramos nada ou indicar quando isso acontecer.
Escolher bem o que testar e como testar é uma arte em si.
+Repare nos exemplos apresentados para descrever a função fatorial,
que tal usá-los como garantia de que não fizemos bobagem?
Isto é possível através do
módulo {{{doctest}}} do Python. vejamos como
{{{#!python
# este é o módulo minhasfuncoes.py
-Linha 34:
+Linha 38:
-Repare nos exemplos que eu escrevi para
descrever a função fatorial, que tal se eu usar esses exemplos
como teste?

Isto é possível através do módulo {{{doctest}}} do Python. vejamos
como utilizar
{{{#!python
-Linha 62:
+Linha 59:
-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,
+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,
-Linha 67:
+Linha 64:
-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
+Para rodar o teste é simples,
{{{
$ python minhasfuncoes.py
}}}.
Se nenhum erro acontecer a saída é muda, nada aparece na tela.
-Linha 72:
+Linha 70:
+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
-Linha 90:
+Linha 91:
-fat(0) era esperado o valor 1, veio 0. fat(5) era esperado 120, veio 0 também.
+para {{{fat(0)}}} era esperado o valor 1, veio 0.
Para {{{fat(5)}}} era esperado 120, veio 0 também.
-Linha 92:
+Linha 94:
+== Para saber mais ==
  * Procure a documentação do doctest ({{{>>> help(doctest)}}}).
  * Um exemplo de uso em VerificadorDeCpf.

--
RudaMoura

Veja também:

Diferenças para "DocTest"

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

Para saber mais