doctest

doctest es un módulo incluido en la biblioteca estándar del lenguaje de programación Python que permite generar fácilmente pruebas basadas en la salida del intérprete de comandos estándar de Python, copiada y pegada en cadenas de documentación (docstrings) .

Doctest hace un uso innovador ^{[ 1 ]} de las siguientes capacidades de Python: ^{[ 2 ]}

• docstrings
• El intérprete interactivo de Python (tanto la línea de comandos como la aplicación idle incluida).
• Introspección en Python

Al usar la consola de Python, el indicador principal: >>> , va seguido de nuevos comandos. El indicador secundario: ... , se usa para continuar comandos en varias líneas; el resultado de la ejecución del comando se espera en las líneas siguientes. Una línea en blanco u otra línea que comience con el indicador principal se considera el final de la salida del comando.

El módulo doctest busca secuencias de indicaciones similares en una cadena de documentación, vuelve a ejecutar el comando extraído y compara el resultado con el del comando proporcionado en el ejemplo de prueba de cadenas de documentación.

Por defecto, al ejecutar doctests, no se muestra ninguna salida cuando las pruebas se superan. Esto se puede modificar mediante opciones en el ejecutor de doctests. Además, doctest se ha integrado con el módulo de pruebas unitarias de Python, lo que permite ejecutar doctests como casos de prueba estándar de unittest. Los ejecutores de casos de prueba de unittest ofrecen más opciones al ejecutar pruebas, como la generación de informes de estadísticas, por ejemplo, pruebas superadas y fallidas.

Aunque Doctest no permite insertar un programa Python en texto narrativo, sí permite insertar ejemplos verificables en cadenas de documentación (docstrings), las cuales pueden contener otro texto. Estas cadenas de documentación se pueden extraer de los archivos del programa para generar documentación en otros formatos, como HTML o PDF . Un archivo de programa puede contener la documentación, las pruebas y el código, y las pruebas se pueden verificar fácilmente con respecto al código. Esto permite que el código, las pruebas y la documentación evolucionen conjuntamente.

Las pruebas de documentación (doctests) son muy adecuadas para proporcionar una introducción a una biblioteca, demostrando cómo se utiliza la API.

A partir de la salida del intérprete interactivo de Python, se puede combinar texto con pruebas que ejercitan la biblioteca, mostrando los resultados esperados.

El primer ejemplo muestra cómo se puede intercalar texto narrativo con ejemplos comprobables en una cadena de documentación. En el segundo ejemplo, se muestran más características de doctest, junto con su explicación. El tercer ejemplo está configurado para ejecutar todas las pruebas de documentación de un archivo al ejecutarlo, pero cuando se importa como módulo, las pruebas no se ejecutarán.

def list_to_0_index ( lst ): """Una solución al problema planteado en:  https://rgrig.blogspot.com/2005/11/writing-readable-code.html 'Dada una lista, lst, digamos que para cada elemento el índice 0 es donde aparece por  primera vez. Así, la lista x = [0, 1, 4, 2, 4, 1, 0, 2] se  transforma en y = [0, 1, 2, 3, 2, 1, 0, 3]. Nótese que para todo  i tenemos x[y[i]] = x[i]. Utilice cualquier lenguaje de programación y cualquier  representación de datos que desee.' >>> x = [0, 1, 4, 2, 4, 1, 0, 2]  >>> list_to_0_index(x)  [0, 1, 2, 3, 2, 1, 0, 3]  >>>  """devolver [ lst . índice ( i ) para i en lst ]

====================== Pruebas de documentación de demostración ======================Este es solo un ejemplo de cómo se ve un texto README que se puede usar con la función doctest.DocFileSuite() del módulo doctest de Python.Normalmente, el archivo README explicaría la API del módulo, como por ejemplo:>>> a = 1 >>> b = 2 >>> a + b 3Como puedes ver, acabamos de demostrar cómo sumar dos números en Python y cómo será el resultado.Una opción especial te permite ser un poco impreciso con tus ejemplos:>>> o = objeto () >>> o # doctest: +ELLIPSIS <objeto objeto en 0x...>Las excepciones también se pueden probar de forma muy sencilla:>>> x Traceback (última llamada): ... NameError : el nombre 'x' no está definido

def unique_words ( page ): """Devuelve el conjunto de las palabras únicas en una lista de líneas de texto. Ejemplo: >>> from StringIO import StringIO  >>> fileText = '''el gato se sentó en la alfombra  ... la alfombra estaba sobre el gato  ... un pez dos peces pez rojo  ... pez azul  ... Este pez tiene un coche amarillo  ... Este pez tiene una estrella amarilla'''  >>> file = StringIO(fileText)  >>> page = file.readlines()  >>> words = unique_words(page)  >>> print sorted(list(words))  ["This", "a", "blue", "car", "cat", "fish", "has", "mat",  "on", "ondur", "one", "red", "sat", "star", "the", "two",  "was", "yellow"]  >>>  """ return set ( word for line in page for word in line . split ())def _test ( ) : import doctest doctest.testmod ( )if __name__ == "__main__" : _test ()

Tanto el formato EpyText de Epydoc como el formato reStructuredText de Docutils admiten el marcado de secciones doctest dentro de las docstrings.

En C++ , el marco de trabajo doctest es la implementación más cercana posible del concepto: las pruebas se pueden escribir directamente en el código de producción con una sobrecarga mínima y la opción de eliminarlas del binario. ^{[ 3 ]}

La biblioteca ExUnit.DocTest de Elixir implementa una funcionalidad similar a la de Doctest. ^{[ 4 ]}

Una implementación de Doctest para Haskell . ^{[ 5 ]}

Escribir pruebas de documentación en Elm . ^{[ 6 ]}

Cómo escribir pruebas de documentación en Rust . ^{[ 7 ]}

Cómo escribir pruebas de documentación en Elixir . ^{[ 8 ]}

byexample^{[ 9 ]} admite la escritura de doctests para varios lenguajes de programación populares (por ejemplo, Python, Ruby, Shell,JavaScript, C/C++, Java, Go, Rust) dentro deMarkdown,reStructuredTexty otros documentos de texto.

• doctest: prueba de ejemplos interactivos de Python