Cum să scrieți și să utilizați doctest pentru a scrie cod de testare în docstrings în Python.

Afaceri

Python vine cu un modul doctest standard care testează conținutul unui docstring, facilitând scrierea exemplelor de intrare și ieșire în docstring și făcând documentația mai ușor de înțeles.

Aici sunt furnizate următoarele informații.

  • Un exemplu simplu de testare cu doctest
    • Dacă nu există nicio eroare
    • În cazul în care există o eroare
  • Controlul rezultatelor de ieșire prin opțiuni și argumente
    • -vOpțiunea
    • verboseargument (de exemplu, funcție, program, program)
  • Rulați modulul doctest din linia de comandă
  • Scrierea testelor într-un fișier text extern
    • Cum se scrie un fișier text
    • Apelat din fișierul py
    • Executarea directă a unui fișier text

Un exemplu simplu de testare cu doctest

Un șir de documente este un șir de caractere încadrat într-unul dintre următoarele: (1) numele funcției care urmează să fie testată, (2) numele funcției care urmează să fie testată și (3) valoarea de ieșire așteptată în modul interactiv Python.

  • """
  • '''

Dacă nu există nicio eroare

Asigurați-vă că codul este corect în funcție și în conținutul docstring-ului.

def add(a, b):
    '''
    >>> add(1, 2)
    3
    >>> add(5, 10)
    15
    '''

    return a + b


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

Rulați acest fișier.

$ python3 doctest_example.py

Dacă nu există erori, nu se va afișa nimic.

if __name__ == '__main__'Aceasta înseamnă „execută procesarea ulterioară numai atunci când fișierul script corespunzător este executat din linia de comandă.

În cazul în care există o eroare

Dacă creați și executați următorul cod greșit, se va afișa o eroare.

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.

Aceasta se prezintă după cum urmează.

Valorile de ieșire așteptate scrise în doctest.Expected
Valoarea reală de ieșireGot

Controlul rezultatelor de ieșire prin opțiuni și argumente

-vOpțiunea

Dacă doriți ca rezultatele de ieșire să fie afișate chiar și atunci când nu există erori, rulați comanda cu opțiunea -v în linia de comandă.

$ 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 (de exemplu, funcție, program, program)

Dacă doriți să afișați întotdeauna rezultatele de ieșire, specificați argumentul verbose=True în doctest.testmod() din fișierul py.

if __name__ == '__main__':
    import doctest
    doctest.testmod(verbose=True)

Rezultatele de ieșire vor fi întotdeauna afișate fără opțiunea -v în timpul execuției.

$ 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.

Rulați modulul doctest din linia de comandă

if __name__ == '__main__'Dacă doriți să faceți altceva în el, puteți rula modulul doctest direct din linia de comandă fără a apela doctest.testmod() în fișierul py.

De exemplu, în următoarele cazuri

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)

Acesta poate primi argumente din linia de comandă și poate executa procesul ca de obicei.

$ python3 doctest_example_without_import.py 3 4
7

Dacă rulați doctest ca un script cu opțiunea -m, testul va fi executat în funcție de funcția în care este scris doctest. Dacă doriți să afișați rezultatele de ieșire, adăugați -v ca mai înainte.

$ 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.

Scrierea testelor într-un fișier text extern

Puteți, de asemenea, să scrieți codul de testare într-un fișier text extern în loc să îl scrieți în docstring.

Cum se scrie un fișier text

Scrieți în format Python interactive mode, așa cum este descris în docstring. Este necesar să se importe funcțiile care urmează să fie utilizate.

Dacă doriți să puneți fișierul text în același director cu fișierul .py care urmează să fie testat, importați-l după cum urmează.

>>> from doctest_example import add
>>> add(1, 2)
3
>>> add(5, 10)
15

Apelat din fișierul py

Apelați doctest.testfile() într-un alt fișier .py pentru testare.

Precizați calea fișierului text în care este scris codul de testare ca argument al doctest.testfile().

import doctest
doctest.testfile('doctest_text.txt')

Rulați acest fișier 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.

Executarea directă a unui fișier text

Chiar dacă nu aveți fișierul py, puteți citi fișierul text direct din linia de comandă și puteți rula testele.

Rulați comanda Python cu opțiunea -m pentru a rula doctest ca un script. Puteți specifica calea fișierului text ca argument de linie de comandă.

$ 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.