Python inclou un mòdul de doctest estàndard que prova el contingut d’una docstring, facilitant l’escriptura d’exemples d’entrada i sortida a la docstring i facilitant la comprensió de la documentació.
La informació següent es proporciona aquí.
- Un exemple senzill de prova amb doctest
- Si no hi ha error
- Si hi ha un error
- Controla els resultats de la sortida mitjançant opcions i arguments
-vOpcióverboseargument (per exemple, funció, programa, programa)
- Executeu el mòdul doctest des de la línia d’ordres
- Redacció de proves en un fitxer de text extern
- Com escriure un fitxer de text
- S’ha cridat des del fitxer py
- Executar directament un fitxer de text
Un exemple senzill de prova amb doctest
Una docstring és una cadena inclosa en un dels següents: (1) el nom de la funció que s’ha de provar, (2) el nom de la funció que s’ha de provar i (3) el valor de sortida esperat en el mode interactiu de Python.
"""''
Si no hi ha error
Assegureu-vos que el codi sigui correcte a la funció i al contingut de la cadena de documents.
def add(a, b):
'''
>>> add(1, 2)
3
>>> add(5, 10)
15
'''
return a + b
if __name__ == '__main__':
import doctest
doctest.testmod()
Executeu aquest fitxer.
$ python3 doctest_example.py
Si no hi ha errors, no sortirà res.
if __name__ == '__main__'Això significa “executar el processament posterior només quan el fitxer de script corresponent s’executa des de la línia d’ordres.
Si hi ha un error
Si creeu i executeu el següent codi incorrecte, sortirà un error.
def add(a, b):
'''
>>> add(1, 2)
3
>>> add(5, 10)
10
'''
return a * b
if __name__ == '__main__':
import doctest
doctest.testmod()
$ python3 doctest_example_error.py
**********************************************************************
File "doctest_example_error.py", line 3, in __main__.add
Failed example:
add(1, 2)
Expected:
3
Got:
2
**********************************************************************
File "doctest_example_error.py", line 5, in __main__.add
Failed example:
add(5, 10)
Expected:
10
Got:
50
**********************************************************************
1 items had failures:
2 of 2 in __main__.add
***Test Failed*** 2 failures.
Es mostra de la següent manera.
| Valors de sortida esperats escrits a doctest. | Expected |
| Valor de sortida real | Got |
Controla els resultats de la sortida mitjançant opcions i arguments
-vOpció
Si voleu que es mostrin els resultats de la sortida encara que no hi hagi errors, executeu l’ordre amb l’opció -v a la línia d’ordres.
$ python3 doctest_example.py -v
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items had no tests:
__main__
1 items passed all tests:
2 tests in __main__.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
verboseargument (per exemple, funció, programa, programa)
Si voleu mostrar sempre els resultats de sortida, especifiqueu l’argument verbose=True a doctest.testmod() al fitxer py.
if __name__ == '__main__':
import doctest
doctest.testmod(verbose=True)
Els resultats de sortida sempre es mostraran sense l’opció -v en temps d’execució.
$ python3 doctest_example_verbose.py
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items had no tests:
__main__
1 items passed all tests:
2 tests in __main__.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
Executeu el mòdul doctest des de la línia d’ordres
if __name__ == '__main__'Si voleu fer-hi alguna cosa més, podeu executar el mòdul doctest directament des de la línia d’ordres sense cridar a doctest.testmod() al fitxer py.
Per exemple, en els casos següents
def add(a, b):
'''
>>> add(1, 2)
3
>>> add(5, 10)
15
'''
return a + b
if __name__ == '__main__':
import sys
result = add(int(sys.argv[1]), int(sys.argv[2]))
print(result)
Pot rebre arguments de línia d’ordres i executar el procés com de costum.
$ python3 doctest_example_without_import.py 3 4
7
Si executeu doctest com a script amb l’opció -m, la prova s’executarà amb la funció en què està escrit doctest. Si voleu mostrar els resultats de sortida, afegiu -v com abans.
$ python3 -m doctest doctest_example_without_import.py
$ python3 -m doctest -v doctest_example_without_import.py
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items had no tests:
doctest_example_without_import
1 items passed all tests:
2 tests in doctest_example_without_import.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
Redacció de proves en un fitxer de text extern
També podeu escriure el codi de prova en un fitxer de text extern en lloc de fer-ho a la cadena de documents.
Com escriure un fitxer de text
Escriu en format de mode interactiu Python, tal com es descriu a docstring. Cal importar les funcions a utilitzar.
Si voleu posar el fitxer de text al mateix directori que el fitxer .py que voleu provar, només heu d’importar-lo de la següent manera.
>>> from doctest_example import add
>>> add(1, 2)
3
>>> add(5, 10)
15
S’ha cridat des del fitxer py
Truqueu a doctest.testfile() en un altre fitxer .py per a la prova.
Especifiqueu la ruta del fitxer de text on s’escriu el codi de prova com a argument de doctest.testfile().
import doctest
doctest.testfile('doctest_text.txt')
Executeu aquest fitxer py.
$ python3 doctest_example_testfile.py -v
Trying:
from doctest_example import add
Expecting nothing
ok
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items passed all tests:
3 tests in doctest_text.txt
3 tests in 1 items.
3 passed and 0 failed.
Test passed.
Executar directament un fitxer de text
Fins i tot si no teniu el fitxer py, podeu llegir el fitxer de text directament des de la línia d’ordres i executar les proves.
Executeu l’ordre de Python amb l’opció -m per executar doctest com a script. Podeu especificar la ruta del fitxer de text com a argument de línia d’ordres.
$ python3 -m doctest -v doctest_text.txt
Trying:
from doctest_example import add
Expecting nothing
ok
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items passed all tests:
3 tests in doctest_text.txt
3 tests in 1 items.
3 passed and 0 failed.
Test passed.