Jak napisać i używać doctest do pisania kodu testowego w docstringach w Pythonie.

Biznes

Python posiada standardowy moduł doctest, który testuje zawartość docstringów, ułatwiając pisanie przykładów wejścia i wyjścia w docstringach i czyniąc dokumentację łatwiejszą do zrozumienia.

Podane są tu następujące informacje.

  • Prosty przykład testowania za pomocą doctest
    • Jeśli nie wystąpił błąd
    • Jeśli wystąpi błąd
  • Kontrola wyników wyjściowych za pomocą opcji i argumentów
    • -vOpcja
    • verboseargument (np. funkcja, program, program)
  • Uruchom moduł doctest z linii poleceń
  • Zapisywanie testów w zewnętrznym pliku tekstowym
    • Jak napisać plik tekstowy
    • Wywoływane z pliku py
    • Bezpośrednie wykonanie pliku tekstowego

Prosty przykład testowania za pomocą doctest

Ciąg docstring to łańcuch zawarty w jednym z następujących elementów: (1) nazwą funkcji, która ma być testowana, (2) nazwą funkcji, która ma być testowana, oraz (3) oczekiwaną wartością wyjściową w trybie interaktywnym Pythona.

  • """
  • '''

Jeśli nie wystąpił błąd

Upewnij się, że kod jest poprawny w funkcji i zawartości docstring.

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

    return a + b


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

Uruchom ten plik.

$ python3 doctest_example.py

Jeśli nie ma błędów, nic nie zostanie wysłane.

if __name__ == '__main__'Oznacza to, że „wykonaj kolejne przetwarzanie tylko wtedy, gdy odpowiedni plik skryptu jest wykonywany z linii poleceń.

Jeśli wystąpi błąd

Jeśli utworzysz i wykonasz następujący błędny kod, zostanie wyświetlony błąd.

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.

Przedstawia się to w następujący sposób.

Oczekiwane wartości wyjściowe zapisane w doctest.Expected
Rzeczywista wartość wyjściowaGot

Kontrola wyników wyjściowych za pomocą opcji i argumentów

-vOpcja

Jeśli chcesz, aby wyniki wyjściowe były wyświetlane nawet wtedy, gdy nie ma błędów, uruchom polecenie z opcją -v w wierszu poleceń.

$ 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 (np. funkcja, program, program)

Jeśli chcesz zawsze wyświetlać wyniki wyjściowe, podaj argument verbose=True w doctest.testmod() w pliku py.

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

Wyniki wyjściowe będą zawsze wyświetlane bez opcji -v w trybie runtime.

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

Uruchom moduł doctest z linii poleceń

if __name__ == '__main__'Jeśli chcesz zrobić w nim coś innego, możesz uruchomić moduł doctest bezpośrednio z linii poleceń, bez wywoływania doctest.testmod() w pliku py.

Na przykład, w następujących przypadkach

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)

Może on otrzymywać argumenty z wiersza poleceń i wykonywać proces jak zwykle.

$ python3 doctest_example_without_import.py 3 4
7

Jeśli uruchomisz doctest jako skrypt z opcją -m, test zostanie wykonany względem funkcji, w której napisany jest doctest. Jeśli chcesz wyświetlić wyniki wyjściowe, dodaj -v, jak poprzednio.

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

Zapisywanie testów w zewnętrznym pliku tekstowym

Możesz również napisać kod testowy w zewnętrznym pliku tekstowym zamiast w docstring.

Jak napisać plik tekstowy

Napisz w formacie trybu interaktywnego Pythona, jak opisano w docstring. Konieczne jest zaimportowanie funkcji, które mają być użyte.

Jeśli chcesz umieścić plik tekstowy w tym samym katalogu co plik .py, który ma być testowany, po prostu zaimportuj go w następujący sposób.

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

Wywoływane z pliku py

Wywołaj doctest.testfile() w innym pliku .py w celu przetestowania.

Jako argument funkcji doctest.testfile() podaj ścieżkę do pliku tekstowego, w którym zapisany jest kod testowy.

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

Uruchom ten plik 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.

Bezpośrednie wykonanie pliku tekstowego

Nawet jeśli nie masz pliku py, możesz odczytać plik tekstowy bezpośrednio z linii poleceń i uruchomić testy.

Uruchom polecenie Pythona z opcją -m, aby uruchomić doctest jako skrypt. Jako argument wiersza poleceń można podać ścieżkę do pliku tekstowego.

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