Учебники

UnitTest Framework — Doctest

Август 17, 2018

Стандартный дистрибутив Python содержит модуль Doctest. Функциональность этого модуля позволяет искать фрагменты текста, которые выглядят как интерактивные сеансы Python, и выполняет эти сеансы, чтобы увидеть, работают ли они точно так, как показано.

Doctest может быть очень полезен в следующих сценариях —

  • Чтобы проверить актуальность строк документации модуля, убедитесь, что все интерактивные примеры по-прежнему работают так, как описано в документации.

  • Выполнить регрессионное тестирование, проверив, что интерактивные примеры из тестового файла или тестового объекта работают должным образом.

  • Чтобы написать учебную документацию для пакета, подробно иллюстрированного примерами ввода-вывода

Чтобы проверить актуальность строк документации модуля, убедитесь, что все интерактивные примеры по-прежнему работают так, как описано в документации.

Выполнить регрессионное тестирование, проверив, что интерактивные примеры из тестового файла или тестового объекта работают должным образом.

Чтобы написать учебную документацию для пакета, подробно иллюстрированного примерами ввода-вывода

В Python строка документации — это строковый литерал, который появляется как первое выражение в классе, функции или модуле. Он игнорируется при выполнении набора, но он распознается компилятором и помещается в атрибут __doc__ включающего класса, функции или модуля. Поскольку он доступен через самоанализ, он является каноническим местом для документирования объекта.

Обычная практика — помещать пример использования различных частей кода Python в строку документации. Модуль doctest позволяет проверить, соответствуют ли эти строки документации прерывистым изменениям в коде.

В следующем коде факториальная функция определяется с использованием примера использования. Чтобы проверить правильность использования примера, вызовите функцию testmod () в модуле doctest. 

"""
This is the "example" module.

The example module supplies one function, factorial(). For example,

>>> factorial(5)
120
"""

def factorial(x):
   """Return the factorial of n, an exact integer >= 0.
   >>> factorial(-1)
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
   """
   
   if not x >= 0:
      raise ValueError("x must be >= 0")
   f = 1
   for i in range(1,x+1):
      f = f*i
   return f
   
if __name__ == "__main__":
   import doctest
   doctest.testmod()

Введите и сохраните приведенный выше скрипт как FactDocTest.py и попробуйте выполнить этот скрипт из командной строки. 

Python FactDocTest.py

Выходные данные не будут показаны, если пример не удался. Теперь измените командную строку на следующее — 

Python FactDocTest.py –v

Консоль теперь покажет следующий вывод — 

C:\Python27>python FactDocTest.py -v
Trying:
   factorial(5)
Expecting:
   120
ok
Trying:
   factorial(-1)
Expecting:
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
ok
2 items passed all tests:
   1 tests in __main__
   1 tests in __main__.factorial
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

Если, с другой стороны, код функции factorial () не дает ожидаемого результата в строке документации, будет отображаться результат ошибки. Например, измените f = 2 вместо f = 1 в приведенном выше сценарии и снова запустите doctest. Результат будет следующим: 

Trying:
   factorial(5)
Expecting:
   120
**********************************************************************
File "docfacttest.py", line 6, in __main__
Failed example:
factorial(5)
Expected:
   120
Got:
   240
Trying:
   factorial(-1)
Expecting:
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
ok
1 items passed all tests:
   1 tests in __main__.factorial
**********************************************************************
1 items had failures:
   1 of 1 in __main__
2 tests in 2 items.
1 passed and 1 failed.
***Test Failed*** 1 failures.

Doctest: проверка примеров в текстовом файле

Еще одно простое приложение doctest — тестирование интерактивных примеров в текстовом файле. Это можно сделать с помощью функции testfile ().

Следующий текст хранится в текстовом файле с именем «example.txt». 

Using ''factorial''
-------------------
This is an example text file in reStructuredText format. First import
''factorial'' from the ''example'' module:
   >>> from example import factorial
Now use it:
   >>> factorial(5)
   120

Содержимое файла обрабатывается как строка документации. Чтобы проверить примеры в текстовом файле, используйте функцию testfile () модуля doctest.

Как и в случае с testmod (), testfile () ничего не отобразит, если не удастся выполнить пример. Если пример терпит неудачу, то неудачный пример (ы) и причина (и) сбоя (ей) выводятся на консоль, используя тот же формат, что и testmod ().

В большинстве случаев копирование и вставка сеанса интерактивной консоли работает нормально, но doctest не пытается выполнить точную эмуляцию какой-либо конкретной оболочки Python.

Любой ожидаемый вывод должен следовать сразу за последней строкой «>>>» или «…», содержащей код, а ожидаемый вывод (если таковой имеется) продолжается до следующей строки «>>>» или пробела.

Ожидаемый вывод не может содержать строку, в которой есть все пробелы, поскольку такая строка используется для обозначения конца ожидаемого вывода. Если ожидаемый результат содержит пустую строку, поместите <BLANKLINE> в ваш пример документа каждый раз, когда ожидается пустая строка.

48
Share: