doctest – Prueba ejemplos interactivos de Python

Código fuente: Lib/doctest.py

El módulo doctest busca pedazos de texto que lucen como sesiones interactivas de Python, y entonces ejecuta esas sesiones para verificar que funcionen exactamente como son mostradas. Hay varias maneras de usar doctest:

  • Para revisar que los docstrings de un módulo están al día al verificar que todos los ejemplos interactivos todavía trabajan como está documentado.

  • Para realizar pruebas de regresión al verificar que los ejemplos interactivos de un archivo de pruebas o un objeto de pruebas trabaje como sea esperado.

  • Para escribir documentación de tutorial para un paquete, generosamente ilustrado con ejemplos de entrada-salida. Dependiendo si los ejemplos o el texto expositivo son enfatizados, tiene el sabor de «pruebas literarias» o «documentación ejecutable».

Aquí hay un módulo de ejemplo completo pero pequeño:

"""
This is the "example" module.

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

>>> factorial(5)
120
"""

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0

    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
        ...
    ValueError: n must be exact integer
    >>> factorial(30.0)
    265252859812191058636308480000000

    It must also not be ridiculously large:
    >>> factorial(1e100)
    Traceback (most recent call last):
        ...
    OverflowError: n too large
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result


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

Si tu ejecutas example.py directamente desde la línea de comandos, doctest hará su magia:

$ python example.py
$

¡No hay salida! Eso es normal, y significa que todos los ejemplos funcionaron. Pasa -v al script, y doctest imprime un registro detallado de lo que está intentando, e imprime un resumen al final:

$ python example.py -v
Trying:
    factorial(5)
Expecting:
    120
ok
Trying:
    [factorial(n) for n in range(6)]
Expecting:
    [1, 1, 2, 6, 24, 120]
ok

Y demás, eventualmente terminando con:

Trying:
    factorial(1e100)
Expecting:
    Traceback (most recent call last):
        ...
    OverflowError: n too large
ok
2 items passed all tests:
   1 tests in __main__
   8 tests in __main__.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$

¡Eso es todo lo que necesitas saber para empezar a hacer uso productivo de doctest! Lánzate. Las siguientes secciones proporcionan detalles completos. Note que hay muchos ejemplos de doctests en el conjunto de pruebas estándar de Python y bibliotecas. Especialmente ejemplos útiles se pueden encontrar en el archivo de pruebas estándar Lib/test/test_doctest.py.

Uso simple: verificar ejemplos en docstrings

La forma más simple para empezar a usar doctest (pero no necesariamente la forma que continuarás usándolo) es terminar cada módulo M con:

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

doctest entonces examina docstrings en el módulo M.

Ejecutar el módulo como un script causa que los ejemplos en los docstrings se ejecuten y verifiquen:

python M.py

No mostrará nada a menos que un ejemplo falle, en cuyo caso el ejemplo fallido o ejemplos fallidos y sus causas de la falla son imprimidas a stdout, y la línea final de salida es ***Test Failed*** N failures., donde N es el número de ejemplos que fallaron.

Ejecútalo con el modificador -v en su lugar:

python M.py -v

y un reporte detallado de todos los ejemplos intentados es impreso a la salida estándar, junto con resúmenes clasificados al final.

Puedes forzar el modo verboso al pasar verbose=True a testmod(), o prohibirlo al pasarlo verbose=False. En cualquiera de estas casos, sys.argv no es examinado por testmod() (por lo que pasar o no -v, no tiene efecto).

También hay un atajo de línea de comandos para ejecutar testmod(). Puedes instruir al intérprete de Python para ejecutar el módulo doctest directamente de la biblioteca estándar y pasar los nombres del módulo en la línea de comandos:

python -m doctest -v example.py

Esto importará example.py como un módulo independiente y ejecutará a testmod(). Note que esto puede no funcionar correctamente si el archivo es parte de un paquete e importa otros submódulos de ese paquete.

Para más información de testmod(), véase la sección API básica.

Uso Simple: Verificar ejemplos en un Archivo de Texto

Otra simple aplicación de doctest es probar ejemplos interactivos en un archivo de texto. Esto puede ser hecho con la función testfile():

import doctest
doctest.testfile("example.txt")

Este script corto ejecuta y verifica cualquier ejemplo interactivo de Python contenido en el archivo example.txt. El contenido del archivo es tratado como si fuese un solo gran docstring; ¡el archivo no necesita contener un programa de Python! Por ejemplo, tal vez example.txt contenga esto:

The ``example`` module
======================

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(6)
    120

Ejecutar doctest.testfile("example.txt") entonces encuentra el error en esta documentación:

File "./example.txt", line 14, in example.txt
Failed example:
    factorial(6)
Expected:
    120
Got:
    720

Como con testmod(), testfile() no mostrará nada a menos que un ejemplo falle. Si un ejemplo no falla, entonces los ejemplos fallidos y sus causas son impresas a stdout, usando el mismo formato como testmod().

Por defecto, testfile() busca archivos en el directorio del módulo al que se llama. Véase la sección API básica para una descripción de los argumentos opcionales que pueden ser usados para decirle que busque archivos en otros lugares.

Como testmod(), la verbosidad de testfile() puede ser establecida con el modificador de la línea de comandos -v o con el argumento por palabra clave opcional verbose.

También hay un atajo de línea de comandos para ejecutar testfile(). Puedes indicar al intérprete de Python para correr el módulo doctest directamente desde la biblioteca estándar y pasar el nombre de los archivos en la línea de comandos:

python -m doctest -v example.txt

Porque el nombre del archivo no termina con .py, doctest infiere que se debe ejecutar con testfile(), no testmod().

Para más información en testfile(), véase la sección API básica.

Cómo funciona

Esta sección examina en detalle cómo funciona doctest: qué docstrings revisa, cómo encuentra ejemplos interactivos, qué contexto de ejecución usa, cómo maneja las excepciones, y cómo las banderas pueden ser usadas para controlar su comportamiento. Esta es la información que necesitas saber para escribir ejemplos de doctest; para información sobre ejecutar doctest en estos ejemplos, véase las siguientes secciones.

¿Qué docstrings son examinados?

Se busca en el docstring del módulo, y todos los docstrings de las funciones, clases, y métodos. Los objetos importados en el módulo no se buscan.

Además, si M.__test__ existe y «es verdaderos», debe ser un diccionario, y cada entrada mapea un nombre (cadena de caracteres) a un objeto de función, objeto de clase, o cadena de caracteres. Se buscan los docstrings de los objetos de función o de clase encontrados de M.__test__, y las cadenas de caracteres son tratadas como si fueran docstrings. En la salida, una clave K en M.__test__ aparece con el nombre:

<name of M>.__test__.K

Todas las clases encontradas se buscan recursivamente de manera similar, para probar docstrings en sus métodos contenidos y clases anidadas.

¿Cómo se reconocen los ejemplos de docstring?

En la mayoría de los casos un copiar y pegar de una sesión de consola interactiva funciona bien, pero doctest no está intentando hacer una emulación exacta de ningún shell específico de Python.

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>

Cualquier salida esperada debe seguir inmediatamente el final de la línea '>>>' o '...' conteniendo el código, y la salida esperada (si la hubiera) se extiende hasta el siguiente '>>>' o la línea en blanco.

La letra pequeña:

  • La salida esperada no puede contener una línea de espacios en blanco, ya que ese tipo de línea se toma para indicar el fin de la salida esperada. Si la salida esperada de verdad contiene una línea en blanco, pon <BLANKLINE> en tu ejemplo de doctest en cada lugar donde una línea en blanco sea esperada.

  • Todos los caracteres de tabulación se expanden a espacios, usando paradas de tabulación de 8 -columnas. Las tabulaciones generadas por el código en pruebas no son modificadas. Ya que todas las tabulaciones en la salida de prueba son expandidas, significa que si el código de salida incluye tabulaciones, la única manera de que el doctest pueda pasar es si la opción NORMALIZE_WHITESPACE o directive está en efecto. Alternativamente, la prueba puede ser reescrita para capturar la salida y compararla a un valor esperado como parte de la prueba. Se llegó a este tratamiento de tabulaciones en la fuente a través de prueba y error, y ha demostrado ser la manera menos propensa a errores de manejarlos. Es posible usar un algoritmo diferente para manejar tabulaciones al escribir una clase DocTestParser personalizada.

  • La salida a stdout es capturada, pero no la salida a stderr (los rastreos de la excepción son capturados a través de maneras diferentes).

  • Si continuas una línea poniendo una barra invertida en una sesión interactiva, o por cualquier otra razón usas una barra invertida, debes usar un docstring crudo, que preservará tus barras invertidas exactamente como las escribes:

    >>> def f(x):
...     r'''Backslashes in a raw docstring: m\n'''
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n

    De otra manera, la barra invertida será interpretada como parte de una cadena. Por ejemplo, el \n arriba sería interpretado como un carácter de nueva línea. Alternativamente, puedes duplicar cada barra invertida en la versión de doctest (y no usar una cadena de caracteres cruda):

    >>> def f(x):
...     '''Backslashes in a raw docstring: m\\n'''
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n

  • La columna inicial no importa:

    >>> assert "Easy!"
      >>> import math
          >>> math.floor(1.9)
          1

    y tantos espacios en blanco al principio se eliminan de la salida esperada como aparece en la línea '>>>' inicial que empezó el ejemplo.

¿Cuál es el contexto de ejecución?

Por defecto, cada vez que un doctest encuentre un docstring para probar, usa una copia superficial de los globales de M, por lo que ejecutar pruebas no cambia los globales reales del módulo, y por lo que una prueba en M no puede dejar atrás migajas que permitan a otras pruebas trabajar. Significa que los ejemplos pueden usar libremente cualquier nombre definido en el nivel superior en M, y nombres definidos más temprano en los docstrings siendo ejecutados. Los ejemplos no pueden ver nombres definidos en otros docstrings.

Puedes forzar el uso de tus propios diccionarios como contexto de ejecución al pasar globs=your_dict a testmod() o testfile() en su lugar.

¿Y las excepciones?

No hay problema, siempre que el rastreo sea la única salida producida por el ejemplo: sólo copia el rastreo. 1 Ya que los rastreos contienen detalles que probablemente cambien rápidamente (por ejemplo, rutas de archivos exactas y números de línea), este es un caso donde doctest trabaja duro para ser flexible en lo que acepta.

Ejemplo simple:

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list

El doctest tiene éxito si se lanza ValueError, con el detalle list.remove(x): x not in list como se muestra.

La salida esperada para una excepción debe empezar con una cabecera de rastreo, que puede ser una de las siguientes dos líneas, con el mismo sangrado de la primera línea del ejemplo:

Traceback (most recent call last):
Traceback (innermost last):

La cabecera de rastreo es seguida por una pila de rastreo opcional, cuyo contenido es ignorado por doctest. La pila de rastreo es típicamente omitida, o copiada palabra por palabra de una sesión interactiva.

La pila de rastreo es seguida por la parte más interesante: la línea o líneas conteniendo el tipo de excepción y detalle. Esto es usualmente la última línea de un rastreo, pero se puede extender a través de múltiples líneas si la excepción tiene un detalle de varias líneas:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail

Las últimas tres líneas (empezando con ValueError) son comparados con el tipo de excepción y detalle, y el resto es ignorado.

La mejor práctica es omitir la pila de rastreo, a menos que añada valor de documentación significante al ejemplo. Por lo que el último ejemplo es probablemente mejor como:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail

Note que los rastreos son tratados de manera especial. En particular, en el ejemplo reescrito, el uso de ... es independiente de la opción ELLIPSIS de doctest. Se pueden excluir los puntos suspensivos en ese ejemplo, así como también pueden haber tres (o trescientas) comas o dígitos, o una transcripción sangrada de un sketch de Monty Python.

Algunos detalles que debes leer una vez, pero no necesitarás recordar:

  • Doctest no puede adivinar si tu salida esperada vino de una excepción de rastreo o de una impresión ordinaria. Así que, un ejemplo que espera ValueError: 42 is prime pasará, ya sea si de hecho se lance ValueError o si el ejemplo simplemente imprime ese texto de rastreo. En la práctica, la salida ordinaria raramente comienza con una línea de cabecera de rastreo, por lo que esto no crea problemas reales.

  • Cada línea de la pila de rastreo (si se presenta) debe estar más sangrada que la primera línea del ejemplo, o empezar con un carácter no alfanumérico. la primera línea que sigue a la cabecera de rastreo sangrada de igual forma y empezando con un alfanumérico es considerado el inicio del detalle de la excepción. Por supuesto que esto es lo correcto para rastreos genuinos.

  • Cuando se especifica la opción IGNORE_EXCEPTION_DETAIL de doctest. todo lo que sigue a los dos puntos más a la izquierda y cualquier otra información del módulo en el nombre de la excepción se ignora.

  • El shell interactivo omite la línea de la cabecera de rastreo para algunos SyntaxError. Pero doctest usa la línea de la cabecera de rastreo para distinguir excepciones de los que no son. Así que en algunos casos raros donde necesitas probar un SyntaxError que omite la cabecera de rastreo, necesitarás poner manualmente la línea de cabecera de rastreo en tu ejemplo de prueba.

  • Para algunos SyntaxError, Python muestra la posición del carácter del error de sintaxis, usando un marcador ^:

    >>> 1 1
  File "<stdin>", line 1
    1 1
      ^
SyntaxError: invalid syntax

    Ya que las líneas mostrando la posición del error vienen antes del tipo de excepción y detalle, no son revisadas por doctest. Por ejemplo, el siguiente test pasaría, a pesar de que pone el marcador ^ en la posición equivocada:

    >>> 1 1
Traceback (most recent call last):
  File "<stdin>", line 1
    1 1
    ^
SyntaxError: invalid syntax

Banderas de Opción

Varias banderas de opción controlan diversos aspectos del comportamiento de doctest. Los nombres simbólicos para las banderas son proporcionados como constantes del módulo, que se pueden conectar mediante *OR* bit a bit y pasar a varias funciones. Los nombres también pueden ser usados en las directivas de doctest, y se pueden pasar a la interfaz de la línea de comandos de doctest a través de la opción -o.

Nuevo en la versión 3.4: La opción de la línea de comandos -o.

El primer grupo de opciones definen las semánticas de la prueba, controlando aspectos de cómo doctest decide si la salida de hecho concuerda con la salida esperada del ejemplo:

doctest.DONT_ACCEPT_TRUE_FOR_1

Por defecto, si un bloque de salida esperada contiene sólo 1, se considera igual a un bloque de salida real conteniendo sólo 1 o true, y similarmente para 0 contra False. Cuando se especifica DONT_ACCEPT_TRUE_FOR_1`, no se permite ninguna sustitución. El comportamiento por defecto atiende a que Python cambió el tipo de retorno de muchas funciones de enteros a booleanos; los doctest esperando salidas «de pequeño enteros» todavía trabajan en estos casos. Esta opción probablemente se vaya, pero no por muchos años.

doctest.DONT_ACCEPT_BLANKLINE

Por defecto, si un bloque de salida esperada contiene una línea que sólo tiene la cadena de caracteres <BLANKLINE>, entonces esa línea corresponderá a una línea en blanco en la salida real. Ya que una línea en blanca auténtica delimita la salida esperada, esta es la única manera de comunicar que una línea en blanco es esperada. Cuando se especifica DONT_ACCEPT_BLANKLINE, esta substitución no se permite.

doctest.NORMALIZE_WHITESPACE

Cuando se especifica, todas las secuencias de espacios en blanco (vacías y nuevas líneas) son tratadas como iguales. Cualquier secuencia de espacios en blanco dentro de la salida esperada corresponderá a cualquier secuencia de espacios en blanco dentro de la salida real. Por defecto, los espacios en blanco deben corresponderse exactamente. NORMALIZE_WHITESPACE es especialmente útil cuando una línea de la salida esperada es muy larga, y quieres envolverla a través de múltiples líneas en tu código fuente.

doctest.ELLIPSIS

Cuando se especifica, un marcador de puntos suspensivos (...) en la salida esperada puede corresponder a cualquier cadena de caracteres en la salida real. Esto incluye las cadenas de caracteres que abarcan límites de líneas, y cadenas de caracteres vacías, por lo que es mejor mantener su uso simple. Usos complicados pueden conducir a los mismo tipos de sorpresa de «ups, coincidió demasiado» que .* es propenso a hacer en expresiones regulares.

doctest.IGNORE_EXCEPTION_DETAIL

When specified, doctests expecting exceptions pass so long as an exception of the expected type is raised, even if the details (message and fully qualified exception name) don’t match.

For example, an example expecting ValueError: 42 will pass if the actual exception raised is ValueError: 3*14, but will fail if, say, a TypeError is raised instead. It will also ignore any fully qualified name included before the exception class, which can vary between implementations and versions of Python and the code/libraries in use. Hence, all three of these variations will work with the flag specified:

>>> raise Exception('message')
Traceback (most recent call last):
Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
builtins.Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
__main__.Exception: message

Note that ELLIPSIS can also be used to ignore the details of the exception message, but such a test may still fail based on whether the module name is present or matches exactly.

Distinto en la versión 3.2: IGNORE_EXCEPTION_DETAIL también ignora cualquier información relacionada al módulo conteniendo la excepción bajo prueba.

doctest.SKIP

Cuando se especifica, no ejecuta el ejemplo del todo. Puede ser útil en contextos donde los ejemplos de doctest sirven como documentación y casos de prueba a la vez, y un ejemplo debe ser incluido para propósitos de documentación, pero no debe ser revisado. P. ej., la salida del ejemplo puede ser aleatoria, o el ejemplo puede depender de recursos que no estarían disponibles para el controlador de pruebas.

La bandera SKIP también se puede usar para temporalmente «quitar» ejemplos.

doctest.COMPARISON_FLAGS

Una máscara de bits o juntadas lógicamente todas las banderas de arriba.

El segundo grupo de opciones controla cómo las fallas de las pruebas son reportadas:

doctest.REPORT_UDIFF

Cuando se especifica, las fallas que involucran salidas multilínea esperadas y reales son mostradas usando una diferencia (diff) unificada.

doctest.REPORT_CDIFF

Cuando se especifica, las fallas que involucran salidas multilínea esperadas y reales se mostrarán usando una diferencia (diff) contextual.

doctest.REPORT_NDIFF

Cuando se especifica, las diferencias son computadas por difflib.Differ, usando el mismo algoritmo que la popular utilidad ndiff.py. Este es el único método que marca diferencias dentro de líneas también como a través de líneas. Por ejemplo, si una línea de salida esperada contiene el dígito 1 donde la salida actual contiene la letra l, se inserta una línea con una marca de inserción marcando la posición de las columnas que no coinciden.

doctest.REPORT_ONLY_FIRST_FAILURE

Cuando se especifica, muestra el primer ejemplo fallido en cada doctest, pero suprime la salida para todos ejemplos restantes. Esto evitará que doctest reporte los ejemplos correctos que se rompen por causa de fallos tempranos; pero también puede esconder ejemplos incorrectos que fallen independientemente de la primera falla. Cuando se especifica REPORT_ONLY_FIRST_FAILURE, los ejemplos restantes aún se ejecutan, y aún cuentan para el número total de fallas reportadas, sólo se suprime la salida.

doctest.FAIL_FAST

Cuando se especifica, sale después del primer ejemplo fallido y no intenta ejecutar los ejemplos restantes. Por consiguiente, el número de fallas reportadas será como mucho 1. Esta bandera puede ser útil durante la depuración, ya que los ejemplos después de la primera falla ni siquiera producirán salida de depuración.

La línea de comandos de doctest acepta la opción -f como un atajo para -o FAIL_FAST.

Nuevo en la versión 3.4.

doctest.REPORTING_FLAGS

Una máscara de bits o todas las banderas de reporte arriba combinadas.

También hay una manera de registrar nombres de nuevas opciones de banderas, aunque esto no es útil a menos que intentes extender doctest a través de herencia:

doctest.register_optionflag(name)

Crea una nueva bandera de opción con un nombre dado, y retorna el valor entero de la nueva bandera. se puede usar register_optionflag() cuando se hereda OutputChecker o DocTestRunner para crear nuevas opciones que sean compatibles con tus clases heredadas. register_optionflag() siempre debe ser llamado usando la siguiente expresión:

MY_FLAG = register_optionflag('MY_FLAG')

Directivas

Se pueden usar las directivas de doctest para modificar las banderas de opción para un ejemplo individual. Las directivas de doctest son comentarios de Python especiales que siguen el código fuente de un ejemplo:

directive             ::=  "#" "doctest:" directive_options
directive_options     ::=  directive_option ("," directive_option)*
directive_option      ::=  on_or_off directive_option_name
on_or_off             ::=  "+" | "-"
directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...

No se permite el espacio en blanco entre el + o - y el nombre de la opción de directiva (directive option name). El nombre de la opción de directiva puede ser cualquiera de los nombres de las banderas de opciones explicadas arriba.

Las directivas de doctest de un ejemplo modifican el comportamiento de doctest para ese único ejemplo. Usa + para habilitar el comportamiento nombrado, o - para deshabilitarlo.

For example, this test passes:

>>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

Without the directive it would fail, both because the actual output doesn’t have two blanks before the single-digit list elements, and because the actual output is on a single line. This test also passes, and also requires a directive to do so:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]

Multiple directives can be used on a single physical line, separated by commas:

>>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

If multiple directive comments are used for a single example, then they are combined:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
...                         # doctest: +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

As the previous example shows, you can add ... lines to your example containing only directives. This can be useful when an example is too long for a directive to comfortably fit on the same line:

>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
[0, ..., 4, 10, ..., 19, 30, ..., 39]

Tenga en cuenta que ya que todas las opciones están deshabilitadas por defecto, y las directivas sólo aplican a los ejemplos en los que aparecen, habilitarlas (a través de + en la directiva) usualmente es la única opción significativa. Sin embargo, las banderas de opciones también pueden ser pasadas a funciones que ejecutan doctests, estableciendo valores por defecto diferentes. En tales casos, deshabilitar una opción a través de - en una directiva puede ser útil.

Advertencias

doctest es serio acerca de requerir coincidencias exactas en la salida esperada. Si incluso un solo carácter no coincide, el test falla. Esto probablemente te sorprenderá algunas veces, mientras aprendes exactamente lo que Python asegura y no asegura sobre la salida. Por ejemplo, cuando se imprime un conjunto, Python no asegura que el elemento sea impreso en ningún orden particular, por lo que una prueba como

>>> foo()
{"Hermione", "Harry"}

¡es vulnerable! Una solución puede ser hacer

>>> foo() == {"Hermione", "Harry"}
True

es su lugar. Otra es hacer

>>> d = sorted(foo())
>>> d
['Harry', 'Hermione']

Existen otros casos, pero ya captas la idea.

Another bad idea is to print things that embed an object address, like

>>> id(1.0)  # certain to fail some of the time  
7948648
>>> class C: pass
>>> C()  # the default repr() for instances embeds an address   
<C object at 0x00AC18F0>

The ELLIPSIS directive gives a nice approach for the last example:

>>> C()  # doctest: +ELLIPSIS
<C object at 0x...>

Los números de coma flotante también son sujetos a pequeñas variaciones de la salida a través de las plataformas, porque Python defiere a la librería C de la plataforma para el formato de flotantes, y las librerías de C varían extensamente en calidad aquí.

>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857

Números de la forma I/2.**J son seguros a lo largo de todas las plataformas, y yo frecuentemente planeo ejemplos de doctest para producir números de esa forma:

>>> 3./4  # utterly safe
0.75

Las facciones simples también son más fáciles de entender para las personas, y eso conduce a una mejor documentación.

API básica

Las funciones testmod() y testfile() proporcionan una interfaz simple para doctest que debe ser suficiente para la mayoría de los usos básicos. Para una introducción menos formal a estas funciones, véase las secciones Uso simple: verificar ejemplos en docstrings y Uso Simple: Verificar ejemplos en un Archivo de Texto.

doctest.testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None)

Todos los argumentos excepto filename son opcionales, y deben ser especificados en forma de palabras claves.

Prueba los ejemplos en el archivo con nombre filename. Retorna (failure_count, test_count).

El argumento opcional module_relative especifica cómo el nombre de archivo debe ser interpretado:

  • Si module_relative es True (el valor por defecto), entonces filename especifica una ruta relativa al módulo que es independiente del SO. Por defecto, esta ruta es relativa al directorio del módulo que lo invoca; pero si el argumento package es especificado, entonces es relativo a ese paquete. Para asegurar la independencia del SO, filename debe usar caracteres / para separar segmentos, y no puede ser una ruta absoluta (por ejemplo., no puede empezar con /).

  • Si module_relative es False, entonces filename especifica una ruta especifica del SO. La ruta puede ser absoluta o relativa; las rutas relativas son resueltas con respecto al directorio de trabajo actual.

El argumento opcional name proporciona el nombre de la prueba; por defecto, o si es None, se usa os.path.basename(filename).

El argumento opcional package es un paquete de Python o el nombre de una paquete de Python cuyo directorio debe ser usado como el directorio base para un nombre de archivo relativo al módulo. Si no se especifica ningún paquete, entonces el directorio del módulo que invoca se usa como el directorio base para los nombres de archivos relativos al módulo. Es un error especificar package si module_relative es False.

El argumento opcional globs proporciona un diccionario a ser usado como los globales cuando se ejecuten los ejemplos. Se crea una nueva copia superficial de este diccionario para el doctest, por lo que sus ejemplos empiezan con una pizarra en blanco. Por defecto, o si es None, se usa un nuevo diccionario vacío.

El argumento opcional extraglobs proporciona un diccionario mezclado con los globales usados para ejecutar ejemplos. Funciona como dict.update(): si globs y extraglobs tienen una clave en común, el valor asociado en extraglobs aparece en el diccionario combinado. Por defecto, o si es None, no se usa ninguna variable global. Es una característica avanzada que permite la parametrización de doctests. Por ejemplo, un doctest puede ser escribo para una clase base, usando un nombre genérico para la clase, y luego reusado para probar cualquier número de clases heredadas al pasar un diccionario de extraglobs mapeando el nombre genérico a la clase heredada para ser probada.

El argumento opcional verbose imprime un montón de cosas si es verdadero, e imprime sólo las fallas si es falso; por defecto, o si es None, es verdadero si y sólo si '-v' está en sys.argv.

El argumento opcional report imprime un resumen al final cuando es verdadero; si no, no imprime nada al final. En modo verboso (verbose), el resumen es detallado; si no, el resumen es muy corto (de hecho, vacío si todos las pruebas pasan).

El argumento opcional optionflags (valor por defecto 0) toma las banderas de opciones juntadas lógicamente por un OR. Véase la sección Banderas de Opción.

El argumento opcional raise_on_error tiene como valor por defecto false. Si es true, se lanza una excepción sobre la primera falla o excepción no esperada en un ejemplo. Esto permite que los fallos sean depurados en un análisis a posteriori. El comportamiento por defecto es continuar corriendo los ejemplos.

El argumento opcional parser especifica un DocTestParser (o subclase) que debe ser usado para extraer las pruebas de los archivos. Su valor por defecto es un analizador sintáctico normal (i.e., DocTestParser()).

El argumento opcional encoding especifica una codificación que debe ser usada para convertir el archivo a unicode.

doctest.testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

Todos los argumentos son opcionales, y todos excepto por m deben ser especificados en forma de palabras claves.

Prueba los ejemplos en los docstring de las funciones y clases alcanzables desde el módulo m (o desde el módulo __main__ si m no es proporcionado o es None), empezando con m.__doc__.

También prueba los ejemplos alcanzables desde el diccionario de m.__test__, si existe y no es None. m.__test__ mapea los nombres (cadenas de caracteres) a funciones, clases y cadenas de caracteres; se buscan los ejemplos de las funciones y clases; se buscan las cadenas de caracteres directamente como si fueran docstrings.

Sólo se buscan los docstrings anexados a los objetos pertenecientes al módulo m.

Retorna (failure_count, test_count).

El argumento opcional name proporciona el nombre del módulo; por defecto, o si es None, se usa m.__name__.

El argumento opcional exclude_empty es por defecto false. Si es verdadero, se excluyen los objetos por los cuales no se encuentren doctest. El valor por defecto es un hack de compatibilidad hacia atrás, por lo que el código que use doctest.master.summarize() en conjunto con testmod() continua obteniendo la salida para objetos sin pruebas. El argumento exclude_empty para el más nuevo constructor DocTestFinder es por defecto verdadero.

Los argumentos opcionales extraglobs, verbose, report, optionflags, raise_on_error, y globs son los mismos en cuanto a la función testfile() arriba, excepto que globs es por defecto m.__dict__.

doctest.run_docstring_examples(f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)

Prueba los ejemplos asociados con el objeto f; por ejemplo, f puede ser una cadena de caracteres, un módulo, una función, o un objeto clase.

Una copia superficial del diccionario del argumento globs se usa para la ejecución del contexto.

Se usa el argumento opcional name en mensajes de fallos, y por defecto es "NoName".

Si el argumento opcional verbose es verdadero, la salida se genera incluso si no hay fallas. Por defecto, la salida se genera sólo en caso de la falla de un ejemplo.

El argumento opcional compileflags proporciona el conjunto de banderas que se deben usar por el compilador de Python cuando se corran los ejemplos. Por defecto, o si es None, las banderas se deducen correspondiendo al conjunto de características futuras encontradas en globs.

El argumento opcional optionflags trabaja con respecto a la función testfile() de arriba.

API de unittest

Mientras crece tu colección de módulos probados con doctest, vas a querer una forma de ejecutar todos sus doctests sistemáticamente. doctest proporciona dos funciones que se pueden usar para crear un banco de pruebas (test suite) de unittest desde módulos y archivos de texto que contienen doctests. Para integrarse con el descubrimiento de pruebas de unittest , incluye una función load_tests() en tu módulo de pruebas:

import unittest
import doctest
import my_module_with_doctests

def load_tests(loader, tests, ignore):
    tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
    return tests

Hay dos funciones principales para crear instancias de unittest.TestSuite desde los archivos de texto y módulos con doctests:

doctest.DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

Convierte las pruebas de doctest de uno o más archivos de texto a una unittest.TestSuite.

El unittest.TestSuite que se retorne será ejecutado por el framework de unittest y ejecuta los ejemplos interactivos en cada archivo. Si un ejemplo en cualquier archivo falla, entonces la prueba unitaria sintetizada falla, y una excepción failureException se lanza mostrando el nombre del archivo conteniendo la prueba y un número de línea (algunas veces aproximado).

Pasa una o más rutas (como cadenas de caracteres) a archivos de texto para ser examinados.

Se pueden proporcionar las opciones como argumentos por palabra clave:

El argumento opcional module_relative especifica cómo los nombres de archivos en paths se deben interpretar:

  • Si module_relative is True (el valor por defecto), entonces cada archivo de nombre en paths especifica una ruta relativa al módulo independiente del SO. Por defecto, esta ruta es relativa al directorio del módulo lo está invocando; pero si se especifica el argumento package, entonces es relativo a ese paquete. Para asegurar la independencia del SO, cada nombre de archivo debe usar caracteres / para separar los segmentos de rutas, y puede no ser una ruta absoluta (i.e., puede no empezar con /).

  • Si module_relative es False, entonces cada archivo de nombre en paths especifica una ruta especifica al SO. La ruta puede ser absoluta o relativa; las rutas relativas son resueltas con respecto a directorio de trabajo actual.

El argumento opcional package es un paquete de Python o el nombre de un paquete de Python cuyo directorio debe ser usado como el directorio base para los nombres de archivos relativos al módulo en paths. Si no se especifica ningún paquete, entonces el directorio del módulo que lo está invocando se usa como el directorio base para los archivos de nombres relativos al módulo. Es un error especificar package si module_relative es False.

El argumento opcional setUp especifica una función de configuración para el banco de pruebas. Es invocado antes de ejecutar las pruebas en cada archivo. La función setUp se pasará a un objeto DocTest. La función setUp puede acceder a las variables globales de prueba como el atributo globs de la prueba pasada.

El argumento opcional tearDown especifica una función de destrucción para el banco de pruebas. Es invocado después de ejecutar las pruebas en cada archivo. Se pasará un objeto DocTest a la función tearDown. La función setUp de configuración puede acceder a los globales de la prueba como el atributo globs de la prueba pasada.

El argumento opcional globs es un diccionario que contiene las variables globales iniciales para las pruebas. Se crea una nueva copia de este diccionario para cada prueba. Por defecto, globs es un nuevo diccionario vacío.

El argumento opcional optionflags especifica las opciones de doctest por defecto para las pruebas, creado al juntar lógicamente las opciones de bandera individuales. Véase la sección Banderas de Opción. Véase la función set_unittest_reportflags() abajo para una mejor manera de definir las opciones de informe.

El argumento opcional parser especifica un DocTestParser (o subclase) que debe ser usado para extraer las pruebas de los archivos. Su valor por defecto es un analizador sintáctico normal (i.e., DocTestParser()).

El argumento opcional encoding especifica una codificación que debe ser usada para convertir el archivo a unicode.

Se añade el global __file__ a los globales proporcionados a los doctests cargados desde un archivo de texto usando DocFileSuite().

doctest.DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, checker=None)

Convierte las pruebas de doctest para un módulo a un unittest.TestSuite.

El unittest.TestSuite que se retorne será ejecutado por el framework de unittest y corre cada doctest en el módulo. Si cualquiera de los doctests falla, entonces la prueba unitaria combinada falla, y se lanza una excepción failureException mostrando el nombre del archivo que contiene la prueba y un número de línea (a veces aproximado).

El argumento opcional module proporciona el módulo a probar. Puede ser un objeto de módulo o un nombre (posiblemente punteado) de módulo. Si no se especifica, se usa el módulo que invoca esta función.

El argumento opcional globs es un diccionario que contiene las variables globales iniciales para las pruebas. Se crea una nueva copia de este diccionario para cada prueba. Por defecto, globs es un nuevo diccionario vacío.

El argumento opcional extraglobs especifica un conjunto de variables globales adicionales que son mezcladas con globs. Por defecto, no se usa ningún global adicional.

El argumento opcional test_finder es el objeto DocTestFinder (o un reemplazo directo) que se usa para extraer doctests desde el módulo.

Los argumentos opcionales setUp, tearDown, y optionflags son lo mismo con respecto a la función DocFileSuite() arriba.

Esta función usa la misma técnica de búsqueda que testmod().

Distinto en la versión 3.5: DocTestSuite() retorna un unittest.TestSuite vacío si module no contiene ningún docstring en vez de lanzar un ValueError.

Por detrás, DocTestSuite() crea un unittest.TestSuite de las instancias de doctest.DocTestCase, y DocTestCase es una subclase de unittest.TestCase. DocTestCase no está documentado aquí (es un detalle interno), pero estudiar su código puede responder preguntas sobre los detalles exactos de la integración de unittest.

De manera similar, DocFileSuite() crea un unittest.TestSuite de las instancias de doctest.DocFileCase, y DocFileCase es una subclase de DocTestCase.

Por lo que ambas formas de crear un unittest.TestSuite ejecutan instancias de DocTestCase. Esto es importante por una razón sutil: cuando ejecutas las funciones de doctest por ti mismo, puedes controlar las opciones de doctest en uso directamente, al pasar las banderas de opciones a las funciones de doctest. Sin embargo, si estás escribiendo un framework de unittest, básicamente unittest controla cuándo y cómo se ejecutan las pruebas. El autor del framework típicamente, quiere controlar las opciones de reporte de doctest (quizás, p.ej., especificadas por las opciones de la línea de comandos), pero no hay forma de pasar opciones a través de unittest al probador de ejecución (test runner) de doctest.

Por esta razón, doctest también admite una noción de banderas de informe de doctest específicas para la compatibilidad con unittest, a través de esta función:

doctest.set_unittest_reportflags(flags)

Establece las banderas de informe de doctest a usar.

El argumento flags toma la combinación por el operador OR de las banderas de opciones. Véase la sección Banderas de Opción. Sólo se pueden usar las «banderas de informe».

Esta es una configuración global del módulo, y afecta a todos los doctests futuros a ejecutar por unittest: el método runTest() de DocTestCase revisa las banderas de opciones especificadas para el caso de prueba cuando la instancia de DocTestCase fue construida. Si no se especificó ninguna bandera de informe (que es el caso típico y esperado), las banderas de informe -pertenecientes a doctest- de unittest son combinadas por la operación Or en las banderas de opciones, y las banderas de opciones aumentadas se pasan a la instancia de DocTestRunner creada para ejecutar los doctest. Si se especificó alguna bandera de informe cuando el DocTestCase fue construido, se ignoran las banderas de informe -pertenecientes a doctest- de unittest.

La función retorna el valor de las banderas de informe de unittest en efecto antes de que la función fuera invocada.

API avanzada

La API básica es un simple envoltorio que sirve para hacer los doctest fáciles de usar. Es bastante flexible, y debe cumplir las necesidades de la mayoría de los usuarios; si requieres un control más preciso en las pruebas, o deseas extender las capacidades de doctest, entonces debes usar la API avanzada.

La API avanzada gira en torno a dos clases contenedoras, que se usan para guardar los ejemplos interactivos extraídos de los casos doctest:

  • Example: Un statement de Python, emparejado con su salida esperada.

  • DocTest: Una colección de clases Example, típicamente extraídos de un sólo docstring o archivo de texto.

Se definen clases de procesamiento adicionales para encontrar, analizar sintácticamente, y ejecutar, y comprobar ejemplos de doctest:

Las relaciones entre estas clases de procesamiento se resumen en el siguiente diagrama:

                            list of:
+------+                   +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+    |        ^     +---------+     |       ^    (printed)
            |        |     | Example |     |       |
            v        |     |   ...   |     v       |
           DocTestParser   | Example |   OutputChecker
                           +---------+

Objetos DocTest

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)

Una colección de ejemplos de doctest que deben ejecutarse en un sólo nombre de espacios. Se usan los argumentos del constructor para inicializar los atributos de los mismos nombres.

DocTest define los siguientes atributos. Son inicializados por el constructor, y no deben ser modificados directamente.

examples

Una lista de objetos Example codificando los ejemplos interactivos de Python individuales que esta prueba debe ejecutar.

globs

El nombre de espacios (alias globals) en que los ejemplos se deben ejecutar. Este es un diccionario que mapea nombres a valores. Cualquier cambio al nombre de espacios hecho por los ejemplos (tal como juntar nuevas variables) se reflejará en globs después de que se ejecute la prueba.

name

Un nombre de cadena de caracteres que identifica el DocTest. Normalmente, este es el nombre del objeto o archivo del que se extrajo la prueba.

filename

El nombre del archivo del que se extrajo este DocTest; o None si el nombre del archivo se desconoce, o si DocTest no se extrajo de un archivo.

lineno

El número de línea dentro de filename donde este DocTest comienza, o None si el número de línea no está disponible. Este número de línea es comienza en 0 con respecto al comienzo del archivo.

docstring

La cadena de caracteres del que se extrajo la cadena, o None si la cadena no está disponible, o si la prueba no se extrajo de una cadena de caracteres.

Objetos Example

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)

Un sólo ejemplo interactivo, que consta de una sentencia de Python y su salida esperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

La clase Example define los siguientes atributos. Son inicializados por el constructor, y no deben ser modificados directamente.

source

Una cadena de caracteres que contiene el código fuente del ejemplo. Este código fuente consiste de una sola sentencia Python, y siempre termina en una nueva línea; el constructor añade una nueva línea cuando sea necesario.

want

La salida esperada de ejecutar el código fuente del ejemplo (o desde la salida estándar, o un seguimiento en caso de una excepción). wants termina con una nueva línea a menos que no se espera ninguna salida, en cuyo caso es una cadena vacía. El constructor añade una nueva línea cuando sea necesario.

exc_msg

El mensaje de excepción que el ejemplo genera, si se espera que el ejemplo genere una excepción; o None si no se espera que genere una excepción. Se compara este mensaje de excepción con el valor de retorno de traceback.format_exception_only(). exc_msg termina con una nueva línea a menos que sea None. El constructor añade una nueva línea si se necesita.

lineno

El número de línea dentro de la cadena de caracteres que contiene este ejemplo donde el ejemplo comienza. Este número de línea comienza en 0 con respecto al comienzo de la cadena que lo contiene.

indent

La sangría del ejemplo en la cadena que lo contiene; i.e., el número de caracteres de espacio que preceden la primera entrada del ejemplo.

options

Un diccionario que mapea de las banderas de opciones a True o False, que se usa para anular las opciones por defecto para este ejemplo. Cualquier bandera de opción que no contiene este diccionario se deja con su valor por defecto (como se especifica por los optionflags de DocTestRunner). Por defecto, no se establece ninguna opción.

Objetos DocTestFinder

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

Una clase de procesamiento que se usa para extraer los DocTest que son relevantes para un objeto dado, desde su docstring y los docstring de sus objetos contenidos. Se puede extraer los DocTest de los módulos, clases, funciones, métodos, métodos estáticos, métodos de clase, y propiedades.

Se puede usar el argumento opcional verbose para mostrar los objetos buscados por finder. Su valor por defecto es False (ninguna salida).

El argumento opcional parser especifica el objeto DocTestParser (o un reemplazo directo) que se usa para extraer doctests desde docstrings.

Si el argumento opcional recurse es falso, entonces el método DocTestFinder.find() sólo examinará el objeto dado, y no cualquier objeto contenido.

Si el argumento opcional exclude_empty es falso, entonces DocTestFinder.find() incluirá pruebas para objetos con docstrings vacíos.

DocTestFinder define los siguientes métodos:

find(obj[, name][, module][, globs][, extraglobs])

Retorna una lista de los Doctest que se definen por el docstring de obj, o por cualquiera de los docstring de sus objetos contenidos.

El argumento opcional name especifica el nombre del objeto; este nombre será usado para construir los nombres de los DocTest retornados. Si name no se especifica, entonces se usa obj.__name__.

El parámetro opcional module es el módulo que contiene el objeto dado. Si no se especifica el módulo o si es None, entonces el buscador de pruebas tratará de determinar automáticamente el módulo correcto. Se usa el módulo del objeto:

  • Como un espacio de nombres por defecto, si no se especifica globs.

  • Para evitar que DocTestFinder extraiga DocTests desde objetos que se importan desde otros módulos. (Se ignoran objetos contenidos con módulos aparte de module.)

  • Para encontrar el nombre del archivo conteniendo el objeto.

  • Para ayudar a encontrar el número de línea del objeto dentro de su archivo.

Si module es falso, no se hará ningún intento de encontrar el módulo. Es poco claro, de uso mayormente para probar doctest en si mismo: si module es False, o es None pero no se puede encontrar automáticamente, entonces todos los objetos se consideran que pertenecen al módulo (inexistente), por lo que todos los objetos contenidos se buscarán (recursivamente) por doctests.

Los globales para cada DocTest se forma al combinar globs y extraglobs (los enlaces en extraglobs anulan los enlaces en globs). Se crea una nueva copia superficial del diccionario de globales para cada DocTest. Si globs no se especifica, entonces su valor por defecto es el __dict__ del módulo, si se especifica, o es {} de lo contrario, si extraglobs no se especifica, entonces su valor por defecto es {}.

Objetos DocTestParser

class doctest.DocTestParser

Un clase de procesamiento usada para extraer ejemplos interactivos de una cadena de caracteres, y usarlos para crear un objeto DocTest.

DocTestParser define los siguientes métodos:

get_doctest(string, globs, name, filename, lineno)

Extrae todos los ejemplos de doctest de una cadena dada, y los recolecta en un objeto DocTest.

globs, name, filename, y lineno son atributos para el nuevo objeto DocTest. Véase la documentación de DocTest para más información.

get_examples(string, name='<string>')

Extrae todos los ejemplos de la cadena de caracteres dada, y los retorna como una lista de objetos Example. Los números de línea empiezan en 0. El argumento opcional name es una nombre identificando esta cadena, y sólo es usada para mensajes de errores.

parse(string, name='<string>')

Divide el string dado en ejemplos y texto intermedio, y los retorna como una lista que alterna entre objetos Example y cadenas de caracteres. Los números de línea para los objetos Example empiezan en 0. El argumento opcional name es un nombre identificando esta cadena, y sólo se usa en mensajes de error.

Objetos DocTestRunner

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)

Una clase de procesamiento usada para ejecutar y verificar los ejemplos interactivos en un DocTest.

La comparación entre salidas esperadas y salidas reales se hace por un OutputChecker. Esta comparación puede ser personalizada con un número de banderas de opción; véase la sección Banderas de Opción para más información. Si las banderas de opción son insuficientes, entonces la comparación también puede ser personalizada al pasar una subclase de OutputChecker al constructor.

La salida de la pantalla del test runner se puede controlar de dos maneras. Primero, se puede pasar una función de salida a TestRunner.run(); esta función se invocará con cadenas que deben mostrarse. Su valor por defecto es sys.stdout.write. Si no es suficiente capturar el resultado, entonces la salida de la pantalla también se puede personalizar al heredar de DocTestRunner, y sobreescribir los métodos report_start(), report_success(), report_unexpected_exception(), y report_failure().

El argumento por palabra clave opcional checker especifica el objeto OutputChecker (o un reemplazo directo) que se debe usar para comparar las salidas esperadas con las salidas reales de los ejemplos de doctest.

El argumento por palabra clave opcional verbose controla la verbosidad de DocTestRunner. Si verbose es True, entonces la información de cada ejemplo se imprime , mientras se ejecuta. Si verbose es False, entonces sólo las fallas se imprimen. Si verbose no se especifica, o es None, entonces la salida verbosa se usa si y sólo se usa el modificador de la línea de comandos``-v``.

El argumento por palabra clave opcional optionflags se puede usar para controlar cómo el test runner compara la salida esperada con una salida real, y cómo muestra las fallas. Para más información, véase la sección Banderas de Opción.

DocTestParser define los siguientes métodos:

report_start(out, test, example)

Notifica que el test runner está a punto de procesar el ejemplo dado. Este método es proporcionado para permitir que clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado. test es la prueba que contiene a example. out es la función de salida que se pasó a DocTestRunner.run().

report_success(out, test, example, got)

Notifica que el ejemplo dado se ejecutó correctamente. Este método es proporcionado para permitir que las clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado. got es la salida real del ejemplo. test es la prueba conteniendo example. out es la función de salida que se pasa a DocTestRunner.run().

report_failure(out, test, example, got)

Notifica que el ejemplo dado falló. Este método es proporcionado para permitir que clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado. got es la salida real del ejemplo. test es la prueba conteniendo example. out es la función de salida que se pasa a DocTestRunner.run().

report_unexpected_exception(out, test, example, exc_info)

Notifica que el ejemplo dado lanzó una excepción inesperada. Este método es proporcionado para permitir que las clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado, exc_info es una tupla que contiene información sobre la excepción inesperada (como se retorna por sys.exc_info()). test es la prueba conteniendo example. out es la función de salida que debe ser pasada a DocTestRunner.run().

run(test, compileflags=None, out=None, clear_globs=True)

Ejecuta los ejemplos en test (un objeto DocTest), y muestra los resultados usando función de escritura out.

Los ejemplo se ejecutan en el espacio de nombres test.globs. Si clear_globs es verdadero (el valor por defecto), entonces este espacio de nombres será limpiado después de la prueba se ejecute, para ayudar con la colección de basura. Si quisieras examinar el espacio de nombres después de que la prueba se complete, entonces use clear_globs=False.

compileflags da el conjunto de banderas que se deben usar por el compilador de Python cuando se ejecutan los ejemplos. Si no se especifica, entonces su valor por defecto será el conjunto de banderas de future-import que aplican a globs.

La salida de cada ejemplo es revisada usando el output checker del DocTestRunner, y los resultados se formatean por los métodos de DocTestRunner.report_*().

summarize(verbose=None)

Imprime un resumen de todos los casos de prueba que han sido ejecutados por este DocTestRunner, y retorna un named tuple TestResults(failed, attempted).

El argumento opcional verbose controla qué tan detallado es el resumen. Si no se especifica la verbosidad, entonces se usa la verbosidad de DocTestRunner.

Objetos OutputChecker

class doctest.OutputChecker

Una clase que se usa para verificar si la salida real de un ejemplo de doctest coincide con la salida esperada. OutputChecker define dos métodos: check_output(), que compara un par de salidas dadas, y retorna True si coinciden; y output_difference(), que retorna una cadena que describe las diferencias entre las dos salidas.

OutputChecker define los siguientes métodos:

check_output(want, got, optionflags)

Retorna True si y sólo si la salida real de un ejemplo (got) coincide con la salida esperada (want). Siempre se considera que estas cadenas coinciden si son idénticas; pero dependiendo de qué banderas de opción el test runner esté usando, varias coincidencias inexactas son posibles. Véase la sección Banderas de Opción para más información sobre las banderas de opción.

output_difference(example, got, optionflags)

Retorna una cadena que describe las diferencias entre la salida esperada para un ejemplo dado (example) y la salida real (got). optionflags es el conjunto de banderas de opción usado para comparar want y got.

Depuración

Doctest proporciona varios mecanismos para depurar los ejemplos de doctest:

  • Varias funciones convierten los doctest en programas de Python ejecutables, que pueden ser ejecutadas bajo el depurador de Python, pdb.

  • La clase DebugRunner es una subclase de DocTestRunner que lanza una excepción por el primer ejemplo fallido, conteniendo información sobre ese ejemplo. Esta información se puede usar para realizar depuración a posteriori en el ejemplo.

  • Los casos de unittest generados por DocTestSuite() admiten el método debug() definido por unittest.TestCase.

  • Puedes añadir una llamada a pdb.set_trace() en un ejemplo de doctest, y bajarás al depurador de Python cuando esa línea sea ejecutada. Entonces puedes inspeccionar los valores de las variables, y demás. Por ejemplo, supongamos que a.py contiene sólo este docstring de módulo:

    """
>>> def f(x):
...     g(x*2)
>>> def g(x):
...     print(x+3)
...     import pdb; pdb.set_trace()
>>> f(3)
9
"""

    Entonces una sesión interactiva puede lucir como esta:

    >>> import a, doctest
>>> doctest.testmod(a)
--Return--
> <doctest a[1]>(3)g()->None
-> import pdb; pdb.set_trace()
(Pdb) list
  1     def g(x):
  2         print(x+3)
  3  ->     import pdb; pdb.set_trace()
[EOF]
(Pdb) p x
6
(Pdb) step
--Return--
> <doctest a[0]>(2)f()->None
-> g(x*2)
(Pdb) list
  1     def f(x):
  2  ->     g(x*2)
[EOF]
(Pdb) p x
3
(Pdb) step
--Return--
> <doctest a[2]>(1)?()->None
-> f(3)
(Pdb) cont
(0, 3)
>>>

Funciones que convierten los doctest a código de Python, y posiblemente ejecuten el código sintetizado debajo del depurador:

doctest.script_from_examples(s)

Convierte texto con ejemplos a un script.

El argumento s es una cadena que contiene los ejemplos de doctest. La cadena se convierte a un script de Python, donde los ejemplos de doctest en s se convierten en código regular, y todo lo demás se convierte en comentarios de Python. El script generado se retorna como una cadena: Por ejemplo,

import doctest
print(doctest.script_from_examples(r"""
    Set x and y to 1 and 2.
    >>> x, y = 1, 2

    Print their sum:
    >>> print(x+y)
    3
"""))

muestra:

# Set x and y to 1 and 2.
x, y = 1, 2
#
# Print their sum:
print(x+y)
# Expected:
## 3

Esta función se usa internamente por otras funciones (véase más abajo), pero también pueden ser útiles cuando quieres transformar una sesión de Python interactiva en un script de Python.

doctest.testsource(module, name)

Convierte el doctest para un objeto en un script.

El argumento module es un objeto módulo, o un nombre por puntos de un módulo, que contiene el objeto cuyos doctest son de interés. El argumento name es el nombre (dentro del módulo) del objeto con los doctest de interés. El resultado es una cadena de caracteres, que contiene el docstring del objeto convertido en un script de Python, como se describe por script_from_examples() arriba. Por ejemplo, si el módulo a.py contiene un función de alto nivel f(), entonces

import a, doctest
print(doctest.testsource(a, "a.f"))

imprime una versión de script del docstring de la función f(), con los doctest convertidos en código, y el resto puesto en comentarios.

doctest.debug(module, name, pm=False)

Depura los doctest para un objeto.

Los argumentos module y name son los mismos que para la función testsource() arriba. El script de Python sintetizado para el docstring del objeto nombrado es escrito en un archivo temporal, y entonces ese archivo es ejecutado bajo el control del depurador de PYthon, pdb.

Se usa una copia superficial de module.__dict__ para el contexto de ejecución local y global.

El argumento opcional pm controla si se usa la depuración post-mortem. Si pm tiene un valor verdadero, el archivo de script es ejecutado directamente, y el depurador está involucrado sólo si el script termina a través del lanzamiento de una excepción. Si lo hace, entonces la depuración post-mortem es invocada, a través de pdb.post_mortem(), pasando el objeto de rastreo desde la excepción sin tratar. Si no se especifica pm, o si es falso, el script se ejecuta bajo el depurador desde el inicio, a través de una llamada de exec() apropiada a pdb.run().

doctest.debug_src(src, pm=False, globs=None)

Depura los doctest en una cadena de caracteres.

Es como la función function debug() arriba, excepto que una cadena de caracteres que contiene los ejemplos de doctest se especifica directamente, a través del argumento src.

El argumento opcional pm tiene el mismo significado como en la función debug() arriba.

El argumento opcional globs proporciona un diccionario a usar como contexto de ejecución local y global. Si no se especifica, o es None, se usa un diccionario vacío. Si se especifica, se usa una copia superficial del diccionario.

La clase DebugRunner, y las excepciones especiales que puede lanzar, son de más interés a los autores de frameworks de pruebas, y sólo serán descritos brevemente aquí. Véase el código fuente, y especialmente el docstring de DebugRunner (¡que es un doctest!) para más detalles:

class doctest.DebugRunner(checker=None, verbose=None, optionflags=0)

Una subclase de DocTestRunner que lanza una excepción tan pronto como se encuentra una falla. Si ocurre una excepción inesperada, se lanza una excepción UnexpectedException, conteniendo la prueba, el ejemplo, y la excepción original. Si la salida no coincide, entonces se lanza una excepción DocTestFailure, conteniendo la prueba, el ejemplo, y la salida real.

Para información sobre los parámetros de construcción y los métodos, véase la documentación para DocTestRunner en la sección API avanzada.

Hay dos excepciones que se pueden lanzar por instancias de DebugRunner:

exception doctest.DocTestFailure(test, example, got)

Una excepción lanzada por DocTestRunner para señalar que la salida real del ejemplo de un doctest no coincidió con su salida esperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

DocTestFailure define los siguientes atributos:

DocTestFailure.test

El objeto DocTest que estaba siendo ejecutado cuando el ejemplo falló.

DocTestFailure.example

El objeto Example que falló.

DocTestFailure.got

La salida real del ejemplo.

exception doctest.UnexpectedException(test, example, exc_info)

Una excepción lanzada por DocTestRunner para señalar que un ejemplo de doctest lanzó una excepción inesperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

UnexpectedException define los siguientes atributos:

UnexpectedException.test

El objeto DocTest que estaba siendo ejecutado cuando el ejemplo falló.

UnexpectedException.example

El objeto Example que falló.

UnexpectedException.exc_info

Una tupla que contiene información sobre la excepción inesperada, como es retornado por sys.exc_info().

Plataforma improvisada

Como se menciona en la introducción, doctest ha crecido para tener tres usos primarios:

  1. Verificar los ejemplos en los docstring.

  2. Pruebas de regresión.

  3. Documentación ejecutable / pruebas literarias.

Estos usos tienen diferentes requerimientos, y es importante distinguirlos. En particular, llenar tus docstring con casos de prueba desconocidos conduce a mala documentación.

Cuando se escribe un docstring, escoja ejemplos de docstring con cuidado. Hay un arte para eso que se debe aprender – puede no ser natural al comienzo. Los ejemplos deben añadir valor genuino a la documentación. Un buen ejemplo a menudo puede valer muchas palabras. Si se hace con cuidado, los ejemplos serán invaluables para tus usuarios, y compensarán el tiempo que toma recolectarlos varias veces mientras los años pasan y las cosas cambian. Todavía estoy sorprendido de qué tan frecuente uno de mis ejemplos de doctest paran de funcionar después de un cambio «inofensivo».

Doctest también es una excelente herramienta para pruebas de regresión, especialmente si no escatimas en texto explicativo. Al intercalar prosa y ejemplos, se hace mucho más fácil mantener el seguimiento de lo que realmente se está probando, y por qué. Cuando una prueba falla, buena prosa puede hacer mucho más fácil comprender cuál es el problema, y cómo debe ser arreglado. Es verdad que puedes escribir comentarios extensos en pruebas basadas en código, pero pocos programadores lo hacen. Quizás es porque simplemente doctest hace escribir pruebas mucho más fácil que escribir código, mientras que escribir comentarios en código es mucho más difícil. Pienso que va más allá de eso: la actitud natural cuando se escribe una prueba basada en doctest es que quieres explicar los puntos finos de tu software, e ilustrarlos con ejemplos. Esto naturalmente lleva a archivos de pruebas que empiezan con las características más simples, y lógicamente progresan a complicaciones y casos extremos. Una narrativa coherente es el resultado, en vez de una colección de funciones aisladas que pruebas trozos aislados de funcionalidad aparentemente al azar. Es una actitud diferente, y produce resultados diferentes, difuminando la distinción entre probar y explicar.

Pruebas de regresión se limitan mejor a objetos o archivos dedicados. Hay varias opciones para organizar pruebas:

  • Escribe archivos de texto que contienen los casos de prueba como ejemplos interactivos, y prueba los archivos usando testfile() o DocFileSuite(). Esto es lo recomendado, aunque es más fácil hacerlo para nuevos proyectos, diseñados desde el comienzo para usar doctest.

  • Define funciones nombradas _regrtest_topic que consisten en docstrings únicas, que contienen casos de prueba por los tópicos nombrados. Estas funciones se pueden incluir en el mismo archivo que el módulo, o separadas en un archivo de prueba separado.

  • Define un diccionario __test__ que asigna desde temas de prueba de integración a los docstring que contienen casos de prueba.

Cuando has puesto tus pruebas en un módulo, el módulo puede ser el mismo test runner. Cuando una prueba falla, puedes hacer que tu test runner vuelva a ejecutar sólo los doctest fallidos mientras que tu depuras el problema. Aquí hay un ejemplo mínimo de tal test runner:

if __name__ == '__main__':
    import doctest
    flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
    if len(sys.argv) > 1:
        name = sys.argv[1]
        if name in globals():
            obj = globals()[name]
        else:
            obj = __test__[name]
        doctest.run_docstring_examples(obj, globals(), name=name,
                                       optionflags=flags)
    else:
        fail, total = doctest.testmod(optionflags=flags)
        print("{} failures out of {} tests".format(fail, total))

Notas al pie de página

1

No se admiten los ejemplos que contienen una salida esperada y una excepción. Intentar adivinar dónde una termina y la otra empieza es muy propenso a errores, y da lugar a una prueba confusa.