UnitTest Framework - API Doctest

La API doctest gira en torno a las siguientes dos clases de contenedor que se utilizan para almacenar ejemplos interactivos de docstrings:

• Example - Una sola declaración de Python, emparejada con su resultado esperado.

• DocTest - Una colección de ejemplos, normalmente extraída de una única cadena de documentos o un archivo de texto.

Las siguientes clases de procesamiento adicionales están definidas para buscar, analizar, ejecutar y verificar ejemplos de pruebas de documentación:

• DocTestFinder - Busca todas las cadenas de documentos en un módulo determinado y utiliza un DocTestParser para crear una prueba de documentos a partir de cada cadena de documentos que contiene ejemplos interactivos.

• DocTestParser : Crea un objeto doctest a partir de una cadena (como la cadena de documentos de un objeto).

• DocTestRunner - Ejecuta los ejemplos en un doctest y usa un OutputChecker para verificar su salida.

• OutputChecker - Compara la salida real de un ejemplo de doctest con la salida esperada y decide si coinciden.

Clase DocTestFinder

Es una clase de procesamiento que se utiliza para extraer las pruebas de documentación que son relevantes para un objeto dado, de su cadena de documentación y las cadenas de documentación de sus objetos contenidos. Actualmente, las pruebas de documentos se pueden extraer de los siguientes tipos de objetos: módulos, funciones, clases, métodos, métodos estáticos, métodos de clase y propiedades.

Esta clase define el método find (). Devuelve una lista de los DocTests que están definidos por la cadena de documentos del objeto o por cualquiera de las cadenas de documentos de sus objetos contenidos.

DocTestParser (clase)

Es una clase de procesamiento que se usa para extraer ejemplos interactivos de una cadena y usarlos para crear un objeto DocTest. Esta clase define los siguientes métodos:

• get_doctest() - Extraiga todos los ejemplos de doctest de la cadena dada y recójalos en un DocTest objeto.

• get_examples(string[, name]) - Extraiga todos los ejemplos de doctest de la cadena dada y devuélvalos como una lista de Exampleobjetos. Los números de línea están basados ​​en 0. El nombre de argumento opcional es un nombre que identifica esta cadena y solo se usa para mensajes de error.

• parse(string[, name]) - Divida la cadena dada en ejemplos y texto intermedio, y devuélvalos como una lista de Examplesy cuerdas. Números de línea para elExamplesestán basados ​​en 0. El nombre de argumento opcional es un nombre que identifica esta cadena y solo se usa para mensajes de error.

DocTestRunner (clase)

Esta es una clase de procesamiento que se usa para ejecutar y verificar los ejemplos interactivos en un DocTest. En él se definen los siguientes métodos:

report_start ()

Informe que el ejecutor de pruebas está a punto de procesar el ejemplo dado. Este método se proporciona para permitir subclases deDocTestRunnerpersonalizar su salida; no se debe llamar directamente

report_success ()

Informe que el ejemplo dado se ejecutó correctamente. Este método se proporciona para permitir que las subclases de DocTestRunner personalicen su salida; no debe llamarse directamente.

report_failure ()

Informe que el ejemplo dado falló. Este método se proporciona para permitir subclases deDocTestRunnerpersonalizar su salida; no debe llamarse directamente.

report_unexpected_exception ()

Informe que el ejemplo dado generó una excepción inesperada. Este método se proporciona para permitir que las subclases de DocTestRunner personalicen su salida; no debe llamarse directamente.

ejecutar (prueba)

Ejecutar los ejemplos de prueba (un objeto doctest), y mostrar los resultados utilizando la función de escritor a cabo .

resumir ([detallado])

Imprima un resumen de todos los casos de prueba que ha ejecutado este DocTestRunner y devuelva una tupla con nombre TestResults (fallido, intentado). El argumento detallado opcional controla qué tan detallado es el resumen. Si no se especifica la verbosidad, se usa la verbosidad de DocTestRunner.

OutputChecker (clase)

Esta clase se usa para verificar si el resultado real de un ejemplo de prueba de documento coincide con el resultado esperado.

Los siguientes métodos se definen en esta clase:

check_output ()

Regreso Truesi el resultado real de un ejemplo ( obtenido ) coincide con el resultado esperado ( deseo ). Siempre se considera que estas cadenas coinciden si son idénticas; pero dependiendo de las banderas de opciones que utilice el ejecutor de pruebas, también son posibles varios tipos de coincidencias no exactas. Consulte la sección Indicadores de opciones y directivas para obtener más información sobre los indicadores de opciones.

diferencia_salida ()

Devuelve una cadena que describe las diferencias entre la salida esperada para un ejemplo dado ( ejemplo ) y la salida real ( obtenida ).

Integración de DocTest con Unittest

El módulo doctest proporciona dos funciones que se pueden utilizar para crear conjuntos de pruebas unittest a partir de módulos y archivos de texto que contienen doctests. Para integrarse con el descubrimiento de prueba unittest, incluya una función load_tests () en su módulo de prueba:

import unittest
import doctest
import doctestexample

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

Se formará un TestSuite combinado de pruebas de unittest y doctest y ahora se puede ejecutar mediante el método main () o run () del módulo unittest.

Las siguientes son las dos funciones principales para crear unittest.TestSuite instancias de archivos de texto y módulos con las pruebas de documentación -

doctest.DocFileSuite ()

Se utiliza para convertir pruebas doctest de uno o más archivos de texto a un unittest.TestSuite. El unittest.TestSuite devuelto debe ser ejecutado por el marco unittest y ejecuta los ejemplos interactivos en cada archivo. Si falla alguno de los ejemplos de un archivo, la prueba unitaria sintetizada falla yfailureException Se genera una excepción que muestra el nombre del archivo que contiene la prueba y un número de línea (a veces aproximado).

doctest.DocTestSuite ()

Se utiliza para convertir las pruebas de doctest de un módulo en un unittest.TestSuite.

El unittest.TestSuite devuelto debe ser ejecutado por el marco unittest y ejecuta cada doctest en el módulo. Si alguna de las pruebas de documentación falla, la prueba unitaria sintetizada falla yfailureException se genera una excepción que muestra el nombre del archivo que contiene la prueba y un número de línea (a veces aproximado)

Bajo las sábanas, DocTestSuite () crea un unittest.TestSuite fuera de las instancias de doctest.DocTestCase, y DocTestCase es una subclase de unittest.TestCase.

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

Entonces, ambas formas de crear un unittest.TestSuite ejecutan instancias de DocTestCase. Cuando ejecuta las funciones de doctest usted mismo, puede controlar las opciones de doctest en uso directamente, pasando banderas de opciones a las funciones de doctest.

Sin embargo, si está escribiendo un marco unittest, unittest controla en última instancia cuándo y cómo se ejecutan las pruebas. El autor del marco normalmente quiere controlar las opciones de informes de pruebas de documentación (tal vez, por ejemplo, especificadas por las opciones de la línea de comandos), pero no hay forma de pasar las opciones a través de unittest a los ejecutores de pruebas de pruebas de documentación.