Як написати та використовувати doctest для написання тестового коду в docstrings на Python.

Бізнес

Python постачається зі стандартним модулем doctest, який перевіряє вміст рядка документів, що полегшує запис прикладів введення та виведення в рядок документів і полегшує розуміння документації.

Тут наведено наступну інформацію.

  • Простий приклад тестування за допомогою doctest
    • Якщо немає помилки
    • Якщо є помилка
  • Контроль результатів виведення за параметрами та аргументами
    • -vВаріант
    • verboseаргумент (наприклад, функція, програма, програма)
  • Запустіть модуль doctest з командного рядка
  • Написання тестів у зовнішньому текстовому файлі
    • Як написати текстовий файл
    • Викликається з файлу py
    • Безпосереднє виконання текстового файлу

Простий приклад тестування за допомогою doctest

Рядок документації — це рядок, укладений в одне з наступного: (1) назва функції, яка буде перевірена, (2) назва функції, яка буде перевірена, і (3) очікуване вихідне значення в інтерактивному режимі Python.

  • """
  • ''

Якщо немає помилки

Переконайтеся, що код правильний у вмісті функції та рядка документів.

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

    return a + b


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

Запустіть цей файл.

$ python3 doctest_example.py

Якщо немає помилок, нічого не буде виведено.

if __name__ == '__main__'Це означає «виконувати подальшу обробку лише тоді, коли відповідний файл сценарію виконується з командного рядка.

Якщо є помилка

Якщо ви створите та виконаєте наступний неправильний код, буде виведена помилка.

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.

Це показано наступним чином.

Очікувані вихідні значення, записані в doctest.Expected
Фактична вихідна величинаGot

Контроль результатів виведення за параметрами та аргументами

-vВаріант

Якщо ви хочете, щоб результати виводу відображалися навіть за відсутності помилок, запустіть команду з параметром -v у командному рядку.

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

verboseаргумент (наприклад, функція, програма, програма)

Якщо ви хочете завжди відображати результати виведення, вкажіть аргумент verbose=True у doctest.testmod() у файлі py.

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

Результати виведення завжди відображатимуться без параметра -v під час виконання.

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

Запустіть модуль doctest з командного рядка

if __name__ == '__main__'Якщо ви хочете зробити в ньому щось інше, ви можете запустити модуль doctest безпосередньо з командного рядка, не викликаючи doctest.testmod() у файлі py.

Наприклад, у наступних випадках

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)

Він може отримувати аргументи командного рядка і виконувати процес як зазвичай.

$ python3 doctest_example_without_import.py 3 4
7

Якщо ви запускаєте doctest як сценарій з опцією -m, тест буде запущено з функцією, в якій написаний doctest. Якщо ви хочете відобразити результати виведення, додайте -v, як і раніше.

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

Написання тестів у зовнішньому текстовому файлі

Ви також можете написати тестовий код у зовнішньому текстовому файлі, а не в рядку документів.

Як написати текстовий файл

Напишіть у форматі інтерактивного режиму Python, як описано в docstring. Необхідно імпортувати функції, які будуть використовуватися.

Якщо ви хочете помістити текстовий файл у той самий каталог, що й файл .py для перевірки, просто імпортуйте його наступним чином.

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

Викликається з файлу py

Викличте doctest.testfile() в іншому файлі .py для тестування.

Вкажіть шлях до текстового файлу, в який записується тестовий код, як аргумент doctest.testfile().

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

Запустіть цей файл 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.

Безпосереднє виконання текстового файлу

Навіть якщо у вас немає файлу py, ви можете прочитати текстовий файл безпосередньо з командного рядка та запустити тести.

Виконайте команду Python з опцією -m, щоб запустити doctest як сценарій. Ви можете вказати шлях до текстового файлу як аргумент командного рядка.

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