unittest — Infraestructura de tests unitarios

Código fuente: Lib/unittest/__init__.py

---

(Si ya estás familiarizado con los conceptos básicos de realización de tests, puedes saltar a la lista de métodos de aserción.)

La infraestructura de tests unitarios unittest se inspiró en primera instancia en JUnit y ofrece aspectos similares a las principales estructuras de tests unitarios más importantes de otros lenguajes. Da soporte a automatización de tests, inicialización compartida, código de cierre de los tests, agregación de los tests en colecciones e independencia de los tests de la infraestructura que los reporta.

Para conseguir esto, unittest da soporte a ciertos conceptos importantes de una forma orientada a objetos:

configuración de prueba (fixture)

Un test fixture representa los preparativos para realizar una o más pruebas y las acciones de limpieza asociadas. Esto puede incluir, por ejemplo, la creación de bases de datos temporales, directorios o el arranque de procesos del servidor.

caso de prueba

Un test case es la unidad mínima de prueba. Verifica la respuesta específica a un juego particular de entradas. unittest proporciona una clase base, TestCase, que se puede utilizar para crear nuevos casos de uso.

conjunto de pruebas

Un test suite es una colección de casos de prueba, juegos de prueba o ambos. Se usa para agrupar pruebas que se han de ejecutar juntas.

ejecutor de pruebas

Un test runner es un componente que dirige la ejecución de las pruebas y proporciona un resultado. El ejecutor puede disponer de una interfaz gráfica, de texto o devolver un valor especial que indique el resultado de la ejecución de las pruebas.

Ver también

Módulo doctest

Otro módulo de soporte a pruebas con una solución muy diferente.

Simple Smalltalk Testing: With Patterns

El documento original de Kent Beck sobre infraestructuras de prueba mediante el patrón que utiliza unittest.

pytest

Una infraestructura de pruebas unitarias de otro proveedor con una sintaxis más ligera de escritura de pruebas, por ejemplo: assert func(10) == 42.

The Python Testing Tools Taxonomy

Una lista extensa de herramientas de prueba para Python incluyendo infraestructuras de pruebas funcionales y librerías de objetos sucedáneos.

Testing in Python Mailing List

Grupo especializado en debate sobre las pruebas y las herramientas de prueba de Python.

The script Tools/unittestgui/unittestgui.py in the Python source distribution is a GUI tool for test discovery and execution. This is intended largely for ease of use for those new to unit testing. For production environments it is recommended that tests be driven by a continuous integration system such as Buildbot, Jenkins, GitHub Actions, or AppVeyor.

Ejemplo sencillo

El módulo unittest proporciona un conjunto de herramientas para construir y ejecutar pruebas. Esta sección demuestra que un pequeño subconjunto de las herramientas es suficiente para satisfacer las necesidades de la mayoría.

He aquí un breve script para probar estros tres métodos de cadena:

import unittest

class TestStringMethods(unittest.TestCase):

    def test_upper(self):
        self.assertEqual('foo'.upper(), 'FOO')

    def test_isupper(self):
        self.assertTrue('FOO'.isupper())
        self.assertFalse('Foo'.isupper())

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', 'world'])
        # check that s.split fails when the separator is not a string
        with self.assertRaises(TypeError):
            s.split(2)

if __name__ == '__main__':
    unittest.main()

Para crear un caso de prueba se genera una subclase de unittest.TestCase. Las tres pruebas se definen con métodos cuyos nombres comienzan por las letras test. Esta convención sobre nombres indica al ejecutor de pruebas qué métodos representan pruebas.

El quid de cada test es la llamada a assertEqual() para verificar un resultado esperado; assertTrue() o assertFalse() para verificar una condición; o assertRaises() para asegurar que se lanza una excepción específica. Se utilizan estos métodos en lugar de la sentencia assert para que el ejecutor de pruebas pueda acumular todos los resultados de la prueba de cara a realizar un informe.

Los métodos setUp() y tearDown() permiten definir instrucciones que han de ser ejecutadas antes y después, respectivamente, de cada método de prueba. Se describen con mas detalle en la sección Organización del código de pruebas.

El bloque final muestra un modo sencillo de ejecutar las pruebas. unittest.main() proporciona una interfaz de línea de órdenes para el script de prueba. Cuando se ejecuta desde la línea de órdenes, el script anterior produce una salida como:

...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

Si se le pasa una opción -v al script de prueba, se establecerá un nivel mayor de detalle del proceso de unittest.main() y se obtendrá la siguiente salida:

test_isupper (__main__.TestStringMethods.test_isupper) ... ok
test_split (__main__.TestStringMethods.test_split) ... ok
test_upper (__main__.TestStringMethods.test_upper) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

Los ejemplos anteriores muestra las características más usuales de unittest, que son suficientes para solventar las necesidades cotidianas de pruebas. El resto de la documentación explora el juego completo de características, que abundan en los mismos principios.

Distinto en la versión 3.11: El comportamiento de retornar un valor de un método de prueba (que no sea el valor por defecto None), ahora está obsoleto.

Interfaz de línea de comandos

Se puede usar el módulo unittest desde la línea de órdenes para ejecutar pruebas de módulos, clases o hasta métodos de prueba individuales:

python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method

Se puede pasar una lista con cualquier combinación de nombres de módulo, así como clases o métodos completamente cualificados.

Se puede especificar los módulos de prueba por ruta de fichero también:

python -m unittest tests/test_something.py

Esto permite usar el completado automático de nombre de fichero de la shell para especificar el módulo de pruebas. El fichero especificado aún debe ser susceptible de importarse como módulo. La ruta se convierte en nombre de módulo eliminando “.py” y convirtiendo el separador de directorios por “.”. Si se desea ejecutar un fichero de prueba que no se puede importar como módulo, se ha de ejecutar el fichero directamente.

Se pueden ejecutar las pruebas con más nivel de detalle (mayor verbosidad) pasando el parámetro -v:

python -m unittest -v test_module

Cuando se ejecuta sin argumentos, se inicia Descubrimiento de pruebas:

python -m unittest

Para obtener una lista de todas las opciones de línea de órdenes:

python -m unittest -h

Distinto en la versión 3.2: En versiones anteriores sólo era posible ejecutar métodos de prueba individuales, pero no módulos ni clases.

Opciones de la línea de órdenes

unittest da soporte a las siguientes opciones de línea de órdenes:

-b, --buffer

Los flujos de datos de salida estándar y error estándar se acumulan en un búfer durante la ejecución de pruebas. La salida de las pruebas correctas se descarta. La salida de las pruebas que fallan o devuelven un error se añade a los mensajes de fallo.

-c, --catch

La pulsación de Control-C durante la ejecución de pruebas espera a que termine la prueba en curso y da un informe de los resultados hasta ese momento. Una segunda pulsación de Control-C lanza la excepción KeyboardInterrupt usual.

Consultar en Gestión de señales las funciones que proporcionan esta funcionalidad.

-f, --failfast

Finaliza la ejecución tras el primer error o fallo.

-k

Ejecutar solamente los métodos y clases de prueba que coincidan con el patrón o subcadena de caracteres. Esta opción se puede usar más de una vez, en cuyo caso se incluirán todos los casos de prueba que coincidan con cualquiera de los patrones dados.

Los patrones que contengan un comodín (*) se comprueban contra el nombre de la prueba usando fnmatch.fnmatchcase(); si no lo contienen, se usa una comprobación de contenido simple sensible a mayúsculas.

Los patrones se comprueban contra el nombre del método completamente cualificado como lo importa el cargador de pruebas.

Por ejemplo, -k foo coincide con foo_tests.SomeTest.test_something y con bar_tests.SomeTest.test_foo, pero no con bar_tests.FooTest.test_something.

--locals

Mostrar las variables locales en las trazas.

Nuevo en la versión 3.2: Se añadieron las opciones de línea de órdenes -b, -c y -f.

Nuevo en la versión 3.5: La opción de línea de órdenes --locals.

Nuevo en la versión 3.7: La opción de línea de órdenes -k.

La línea de órdenes también se puede usar para descubrimiento de pruebas, para ejecutar todas las pruebas de un proyecto o un subconjunto de éstas.

Descubrimiento de pruebas

Nuevo en la versión 3.2.

Unittest da soporte al descubrimiento de pruebas simples. Para ser compatible con el descubrimiento de pruebas, todos los ficheros de prueba deben ser módulos o paquetes importables desde el directorio superior del proyecto (por lo que sus nombres han de ser identificadores válidos).

El descubrimiento de pruebas está implementado en TestLoader.discover(), pero también se puede usar desde la línea de órdenes. La línea de órdenes básica es:

cd project_directory
python -m unittest discover

Nota

Como atajo, python -m unittest es el equivalente de python -m unittest discover. Si se desea pasar argumentos al descubrimiento de pruebas, hay que pasar la sub-orden discover explícitamente.

La sub-orden discover cuenta con las siguientes opciones:

-v, --verbose

Salida verbosa

-s, --start-directory directory

Directorio de inicio para el descubrimiento (. si se omite)

-p, --pattern pattern

Patrón para la búsqueda de ficheros de prueba (test*.py si se omite)

-t, --top-level-directory directory

Directorio superior del proyecto (el directorio inicial si se omite)

Las opciones -s, -p, y -t se pueden pasar por posición en el orden mostrado. Las siguientes líneas de órdenes son equivalentes:

python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"

Además de pasar una ruta, es posible pasar el nombre de un paquete, por ejemplo myproject.subpackage.test, como directorio de inicio. El nombre de paquete proporcionado será importado y su ubicación en el sistema de archivos será utilizada como directorio de inicio.

Prudencia

El descubrimiento de pruebas carga las pruebas importándolas. Una vez que el descubrimiento ha encontrado todos los ficheros de prueba a partir del directorio inicial, especificado, convierte las rutas en nombres de paquetes a importar. Por ejemplo, foo/bar/baz.py será importado como foo.bar.baz.

Si hay un paquete instalado globalmente y se intenta hacer un descubrimiento sobre una copia diferente a la instalada del paquete, podría ocurrir que se importe la versión incorrecta. Si ocurre esto, el descubrimiento lanza una advertencia y abandona.

Si se proporciona el directorio de inicio como nombre de paquete en lugar de ruta a un directorio, el descubrimiento asume que la ubicación importada es la deseada, así que no se da la advertencia descrita.

Los módulos y paquetes de prueba pueden personalizar la carta y descubrimiento de pruebas mediante el protocolo load_tests.

Distinto en la versión 3.4: El descubrimiento de pruebas admite paquetes nominales para el directorio de inicio. Tenga en cuenta que también se necesita el directorio de nivel superior. (por ejemplo, python -m unittest discover -s root/namespace -t root).

Distinto en la versión 3.11: unittest dropped the namespace packages support in Python 3.11. It has been broken since Python 3.7. Start directory and subdirectories containing tests must be regular package that have __init__.py file.

Los directorios que contienen el directorio de inicio aún pueden ser un paquete de espacio de nombres. En este caso, es necesario especificar el directorio de inicio como nombre de paquete con puntos, y el directorio de destino explícitamente. Por ejemplo:

# proj/  <-- current directory
#   namespace/
#     mypkg/
#       __init__.py
#       test_mypkg.py

python -m unittest discover -s namespace.mypkg -t .

Organización del código de pruebas

Los bloques de construcción básicos de las pruebas unitarias son los test cases, escenarios simples que se han de configurar y cuya corrección hay que comprobar. En unittest, los casos de prueba están representados por instancias de unittest.TestCase. Para crear nuevos casos de prueba, hay que escribir subclases de TestCase o usar FunctionTestCase.

El código de pruebas de una instancia de TestCase debería ser completamente autónomo, de tal modo que se pueda ejecutar aisladamente o en una combinación arbitraria con otras clases de prueba.

La subclase más simple de TestCase se limita a implementar un método test (o un método que empiece por test) para realizar código de prueba específico:

import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def test_default_widget_size(self):
        widget = Widget('The widget')
        self.assertEqual(widget.size(), (50, 50))

Note that in order to test something, we use one of the assert* methods provided by the TestCase base class. If the test fails, an exception will be raised with an explanatory message, and unittest will identify the test case as a failure. Any other exceptions will be treated as errors.

Las pruebas pueden ser muchas y su preparación puede ser repetitiva. Por suerte, se puede «sacar factor común» a la preparación implementando un método setUp(), al que la infraestructura de prueba llamará para cada prueba que se ejecute:

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def test_default_widget_size(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

    def test_widget_resize(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')

Nota

El orden en que se ejecutan las diversas pruebas se determina por orden alfabético de los nombres de métodos de prueba.

Si el método setUp() lanza una excepción mientras se ejecuta la prueba, la infraestructura considerará que la prueba ha sufrido un error y no se ejecutará el método de prueba propiamente dicho.

Análogamente, se puede proporcionar un método tearDown() que haga limpieza después de que se ejecute el método de prueba:

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()

Si setUp() se ejecuta sin errores, tearDown() se ejecutará tanto si el método de prueba tuvo éxito como si no.

Un entorno de trabajo así para el código de pruebas se llama test fixture . Se crea una nueva instancia de TestCase como juego de datos de prueba que se utiliza para cada método de prueba. De este modo, setUp(), tearDown() y __init__() se llamarán una vez por prueba.

Se recomienda usar implementaciones de TestCase para agrupar las pruebas de acuerdo con las características probadas. unittest proporciona una mecanismo para esto: el test suite, representado por la clase TestSuite de unittest. En la mayor parte de los casos, llamar a unittest.main() hará lo correcto y recolectará todos los casos de prueba del módulo para su ejecución.

Sin embargo, si se desea personalizar la construcción del paquete de pruebas, se puede hacer:

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('test_default_widget_size'))
    suite.addTest(WidgetTestCase('test_widget_resize'))
    return suite

if __name__ == '__main__':
    runner = unittest.TextTestRunner()
    runner.run(suite())

Se puede poner las definiciones de los casos de prueba y de los paquetes de prueba en los mismos módulos que el código que prueban.(tal como widget.py), pero sacarlos a un módulo aparte como test_widget.py tiene diversas ventajas:

• El módulo de pruebas se puede ejecutar aisladamente desde la línea de órdenes.

• El código de pruebas se puede separar con más facilidad del código de producción.

• Disminuye la tentación de cambiar el código de prueba para ajustarse al código bajo prueba.

• El código de pruebas debería modificarse con mucha menor frecuencia que el código bajo prueba.

• Es más sencillo refactorizar el código bajo prueba.

• El código para probar módulos escritos en C ha de estar en módulos aparte, así que ¿por qué no mantener la consistencia?

• Si cambia la estrategia de prueba, no hay razón para cambiar el código fuente principal.

Reutilización de código de prueba anterior

Habrá personas que tengan código de prueba previo que deseen ejecutar desde unittest, sin conversión previa de cada antigua función de prueba a una subclase de TestCase.

Por esto, unittest proporciona una clase FunctionTestCase. Se puede utilizar esta subclase de TestCase para envolver una función de prueba existente. Se pueden proporcionar también funciones de preparación y desmontaje.

Dada la siguiente función de prueba:

def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...

se puede crear una instancia de caso de prueba de la siguiente manera, con métodos opcionales de preparación y desmontaje:

testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)

Nota

Aunque se puede usar FunctionTestCase para convertir rápidamente unas pruebas existentes a un sistema basado en unittest, no es una vía recomendada. Tomarse el tiempo de construir subclases bien construidas de TestCase hará las futuras refactorizaciones de pruebas futura considerablemente más fácil.

En algunos casos, los tests existentes pueden haber sido escritos usando el módulo doctest. En ese caso, doctest tiene una clase DocTestSuite que puede construir automáticamente instancias de unittest.TestSuite partiendo de los test basados en doctest.

Omitir tests y fallos esperados

Nuevo en la versión 3.1.

Unittest soporta omitir métodos individuales de tests e incluso clases completas de tests. Además, soporta marcar un test como un «fallo esperado», un test que está roto y va a fallar, pero no debería ser contado como fallo en TestResult.

Omitir un test es solo cuestión de emplear el decorator skip() o una de sus variantes condicionales, llamando a TestCase.skipTest() dentro de setUp() o en un método de test, o lanzando SkipTest directamente.

La omisión más básica tiene la siguiente forma:

class MyTestCase(unittest.TestCase):

    @unittest.skip("demonstrating skipping")
    def test_nothing(self):
        self.fail("shouldn't happen")

    @unittest.skipIf(mylib.__version__ < (1, 3),
                     "not supported in this library version")
    def test_format(self):
        # Tests that work for only a certain version of the library.
        pass

    @unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
    def test_windows_support(self):
        # windows specific testing code
        pass

    def test_maybe_skipped(self):
        if not external_resource_available():
            self.skipTest("external resource not available")
        # test code that depends on the external resource
        pass

Esta es la salida de ejecutar el ejemplo superior en modo verboso:

test_format (__main__.MyTestCase.test_format) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase.test_nothing) ... skipped 'demonstrating skipping'
test_maybe_skipped (__main__.MyTestCase.test_maybe_skipped) ... skipped 'external resource not available'
test_windows_support (__main__.MyTestCase.test_windows_support) ... skipped 'requires Windows'

----------------------------------------------------------------------
Ran 4 tests in 0.005s

OK (skipped=4)

Las clases pueden ser omitidas igual que los métodos:

@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass

TestCase.setUp() puede omitir también el test. Esto es útil cuando un recurso que necesita ser puesto a punto no está disponible.

Los fallos esperados emplean el decorador expectedFailure().

class ExpectedFailureTestCase(unittest.TestCase):
    @unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")

Es fácil lanzar tus propios decoradores que omitan haciendo un decorador que llame a skip() en el test cuando quiere ser omitido. Este decorador omite el test a menos que el objeto pasado tenga un cierto atributo:

def skipUnlessHasattr(obj, attr):
    if hasattr(obj, attr):
        return lambda func: func
    return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))

Los siguientes decoradores y la excepción implementan la omisión de tests y los fallos esperados:

@unittest.skip(reason)

Omitir incondicionalmente el test decorado. reason debe describir porqué el test está siendo omitido.

@unittest.skipIf(condition, reason)

Omitir el test decorado si condition es verdadero.

@unittest.skipUnless(condition, reason)

Omitir el test decorado a menos que condition sea verdadero.

@unittest.expectedFailure

Marca el test como un fallo esperado. Si falla el test o hay errores en la función de test misma (en lugar de en alguno de los métodos test fixture) será considerado un éxito. Si el test pasa, será considerado un fallo.

exception unittest.SkipTest(reason)

Esta excepción es lanzada para omitir un test.

Normalmente puedes usar directamente TestCase.skipTest() o uno de los decoradores de omisión en vez de lanzar esta excepción.

Los tests omitidos no ejecutarán setUp() o tearDown(). Las clases omitidas no ejecutarán setUpClass() o tearDownClass(). Los módulos omitidos no ejecutarán setUpModule() o tearDownModule().

Distinguiendo iteraciones de tests empleando subtests

Nuevo en la versión 3.4.

Cuando hay diferencias muy pequeñas entre tus tests, por ejemplo algunos parámetros, unittest te permite distinguirlos dentro del cuerpo de un método de test empleando el administrador de contexto subTest() .

Por ejemplo, el siguiente test:

class NumbersTest(unittest.TestCase):

    def test_even(self):
        """
        Test that numbers between 0 and 5 are all even.
        """
        for i in range(0, 6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)

producirá la siguiente salida:

======================================================================
FAIL: test_even (__main__.NumbersTest.test_even) (i=1)
Test that numbers between 0 and 5 are all even.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 11, in test_even
    self.assertEqual(i % 2, 0)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest.test_even) (i=3)
Test that numbers between 0 and 5 are all even.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 11, in test_even
    self.assertEqual(i % 2, 0)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest.test_even) (i=5)
Test that numbers between 0 and 5 are all even.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 11, in test_even
    self.assertEqual(i % 2, 0)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 0

Sin usar un subtest, la ejecución se pararía después del primer fallo, y el error sería más difícil de diagnosticar porque el valor de i no se mostraría:

======================================================================
FAIL: test_even (__main__.NumbersTest.test_even)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

Clases y funciones

Esta sección describe en detalle la API de unittest.

Casos de test

class unittest.TestCase(methodName='runTest')

Las instancias de la clase TestCase representan las unidades lógicas de test en el universo de unittest. Esta clase está pensada para ser utilizada como clase base, con los test específicos siendo implementados por subclases concretas. Esta clase implementa la interfaz que necesita el ejecutor de tests para permitirle llevar a cabo los tests, y métodos que el código de test puede utilizar para chequear y reportar distintos tipos de fallo.

Cada instancia de TestCase ejecutará un solo método base: el método llamado methodName. En la mayoría de usos de TestCase, no tendrás que cambiar el methodName ni reimplementar el método por defecto runTest().

Distinto en la versión 3.2: TestCase puede instancias con éxito sin dar un methodName. Esto permite experimentar de manera sencilla con TestCase en el intérprete interactivo.

Las instancias de TestCase proveen tres grupos de métodos: un grupo empleado para ejecutar el test, otro usado para que la implementación del test chequee condiciones y reporte fallos, y algunos métodos de indagación que permiten recopilar información sobre el test en si mismo.

Los métodos en el primer grupo (ejecutando el test) son:

setUp()

Método llamado para preparar el banco de test. Es invocado inmediatamente antes de llamar al método de test; cualquier excepción lanzada por este método que no sea AssertionError o SkipTest será considerada un error en vez de un fallo del test. La implementación por defecto no hace nada.

tearDown()

Método llamado inmediatamente después de que se haya llamado el método de prueba y se haya registrado el resultado. Se llama así aunque el método de ensayo haya planteado una excepción, por lo que la aplicación en las subclases puede tener que ser especialmente cuidadosa en cuanto a la comprobación del estado interno. Cualquier excepción, que no sea AssertionError o SkipTest, planteada por este método se considerará un error adicional en lugar de un fallo de la prueba (aumentando así el número total de errores reportados). Este método sólo se llamará si setUp() tiene éxito, independientemente del resultado del método de prueba. La implementación por defecto no hace nada.

setUpClass()

Un método de clase llamado antes de que los tests en una clase individual sean ejecutados. setUpClass es llamado con la clase como el único argumento y debe ser decorada como classmethod():

@classmethod
def setUpClass(cls):
    ...

Vea Class and Module Fixtures para más detalles.

Nuevo en la versión 3.2.

tearDownClass()

Un método de clase llamado después de que se hayan realizado tests en una clase individual. tearDownClass se llama con la clase como único argumento y debe ser decorado como un classmethod():

@classmethod
def tearDownClass(cls):
    ...

Vea Class and Module Fixtures para más detalles.

Nuevo en la versión 3.2.

run(result=None)

Ejecutar la prueba, recogiendo el resultado en el objeto TestResult pasado como result. Si se omite result o None, se crea un objeto resultado temporal (llamando al método defaultTestResult()) y se emplea ese. El objeto resultante se devuelve al invocador de run().

El mismo efecto puede conseguirse simplemente llamando a la instancia TestCase.

Distinto en la versión 3.3: Las versiones previas de run no retornaban el resultado. Tampoco lo hacía la llamada a una instancia.

skipTest(reason)

Llamar a esto durante un método de prueba o setUp() se salta el test actual. Ver Omitir tests y fallos esperados para más información.

Nuevo en la versión 3.1.

subTest(msg=None, **params)

Retorna un gestor de contexto que ejecuta el bloque de código adjunto como un subtest. msg y params son valores opcionales y arbitrarios que se muestran cuando falla un subtest, permitiéndole identificarlos claramente.

Un caso de test puede contener cualquier número de declaraciones de subtest, y pueden anidarse arbitrariamente.

Ver Distinguiendo iteraciones de tests empleando subtests para más información.

Nuevo en la versión 3.4.

debug()

Realice el test sin recoger el resultado. Esto permite que las excepciones planteadas por el test se propaguen al invocado, y puede utilizarse para apoyar la ejecución de tests bajo un depurador.

La clase TestCase proporciona varios métodos de afirmación para comprobar y reportar fallos. En la siguiente tabla se enumeran los métodos más utilizados (consulte las tablas siguientes para ver más métodos de afirmación):

Método	Comprueba que	Nuevo en
assertEqual(a, b)	a == b
assertNotEqual(a, b)	a != b
assertTrue(x)	bool(x) is True
assertFalse(x)	bool(x) is False
assertIs(a, b)	a is b	3.1
assertIsNot(a, b)	a is not b	3.1
assertIsNone(x)	x is None	3.1
assertIsNotNone(x)	x is not None	3.1
assertIn(a, b)	a in b	3.1
assertNotIn(a, b)	a not in b	3.1
assertIsInstance(a, b)	isinstance(a, b)	3.2
assertNotIsInstance(a, b)	not isinstance(a, b)	3.2

Todos los métodos de aserción aceptan un argumento msg que, si se especifica, se utiliza como mensaje de error en caso de fallo (véase también longMessage). Tenga en cuenta que el argumento de la palabra clave msg puede pasarse a assertRaises(), assertRaisesRegex(), assertWarns(), assertWarnsRegex() sólo cuando se utilizan como gestor de contexto.

assertEqual(first, second, msg=None)

Testea que first y second son iguales. Si los valores no comparan como iguales, el test fallará.

Además, si first y second son exactamente del mismo tipo y uno de lista, tuple, dict, set, frozenset o str o cualquier tipo que una subclase registre con addTypeEqualityFunc() se llamará a la función de igualdad específica del tipo para generar un mensaje de error por defecto más útil (véase también la lista de métodos específicos del tipo).

Distinto en la versión 3.1: Añadida la llamada automática de la función de igualdad de tipo específico.

Distinto en la versión 3.2: assertMultiLineEqual() añadido como la función por defecto para igualdad de tipos cuando se comparan cadenas.

assertNotEqual(first, second, msg=None)

Testea que first y second no son iguales. Si los valores son iguales, el test fallará.

assertTrue(expr, msg=None)

assertFalse(expr, msg=None)

Testea que expr es verdadero (o falso).

Note que esto es equivalente a bool(expr) is True y no a expr is True (use assertIs(expr, True) para lo último). Este método también debe evitarse cuando se disponga de métodos más específicos (por ejemplo, assertEqual(a, b) en lugar de assertTrue(a == b)), porque proporcionan un mejor mensaje de error en caso de fallo.

assertIs(first, second, msg=None)

assertIsNot(first, second, msg=None)

Testea si first y second son (o no) el mismo objeto.

Nuevo en la versión 3.1.

assertIsNone(expr, msg=None)

assertIsNotNone(expr, msg=None)

Testea que expr es (o no es) None.

Nuevo en la versión 3.1.

assertIn(member, container, msg=None)

assertNotIn(member, container, msg=None)

Testea que member está (o no está) en container.

Nuevo en la versión 3.1.

assertIsInstance(obj, cls, msg=None)

assertNotIsInstance(obj, cls, msg=None)

Testea que obj es (o no es) una instancia de cls (que puede ser una clase o una tupla de clases, de la misma forma que soporta isinstance()). Para chequear por el tipo exacto, use assertIs(type(obj), cls).

Nuevo en la versión 3.2.

Es también posible chequear la producción de excepciones, advertencias y mensajes de log usando los siguientes métodos:

Método	Comprueba que	Nuevo en
assertRaises(exc, fun, *args, **kwds)	fun(*args, **kwds) lanza exc
assertRaisesRegex(exc, r, fun, *args, **kwds)	fun(*args, **kwds) lanza exc y el mensaje coincide con regex r	3.1
assertWarns(warn, fun, *args, **kwds)	fun(*args, **kwds) lanza warn	3.2
assertWarnsRegex(warn, r, fun, *args, **kwds)	fun(*args, **kwds) lanza warn y el mensaje coincide con regex r	3.2
assertLogs(logger, level)	El bloque with vuelca sus logs a logger con el level mínimo	3.4
assertLogs(logger, level)	El bloque with no ingresa El bloque with vuelca sus logs a logger con el level mínimo	3.10

assertRaises(exception, callable, *args, **kwds)

assertRaises(exception, *, msg=None)

Testea que se lanza una excepción cuando se llama a callable con cualquier argumento posicional o de palabra clave que también se pasa a assertRaises(). El test pasa si se lanza exception, es un error si se lanza otra excepción, o falla si no se lanza ninguna excepción. Para tener en cuenta cualquiera de un grupo de excepciones, una tupla que contenga las clases de excepción puede ser pasada como exception.

Si sólo se dan los argumentos de exception y posiblemente msg, retorna un administrador de contexto para que el código testado pueda ser escrito en línea en lugar de como una función:

with self.assertRaises(SomeException):
    do_something()

Cuando se emplea como un administrador de contexto, assertRaises() acepta el argumento por palabra clave adicional msg.

El gestor de contexto almacenará el objeto de excepción capturado en su atributo exception . Esto puede ser útil si la intención es realizar comprobaciones adicionales sobre la excepción planteada:

with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)

Distinto en la versión 3.1: Añadió la capacidad de usar assertRaises() como gestor de contexto.

Distinto en la versión 3.2: Añadido el atributo exception .

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertRaisesRegex(exception, regex, callable, *args, **kwds)

assertRaisesRegex(exception, regex, *, msg=None)

Como assertRaises() pero también testea que regex coincide en la representación de la cadena de la excepción planteada. regex puede ser un objeto de expresión regular o una cadena que contiene una expresión regular adecuada para ser usada por re.search(). Ejemplos:

self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')

o:

with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')

Nuevo en la versión 3.1: Añadido bajo el nombre de assertRaisesRegexp.

Distinto en la versión 3.2: Renombrado a assertRaisesRegex().

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertWarns(warning, callable, *args, **kwds)

assertWarns(warning, *, msg=None)

Testea que una advertencia se activa cuando se llama a callable con cualquier argumento posicional o de palabra clave que también se pasa a assertWarns(). El test pasa si se activa el warning y falla si no lo hace. Cualquier excepción es un error. Para considerar cualquiera de un grupo de advertencias, una tupla que contenga las clases de advertencia puede ser pasada como warnings.

Si sólo se dan los argumentos de advertencia y msg, retorna un gestor de contexto para que el código testado pueda ser escrito en línea en lugar de como una función:

with self.assertWarns(SomeWarning):
    do_something()

Cuando se usa como gestor de contexto, assertWarns() acepta el argumento de palabra clave adicional msg.

El gestor de contexto almacenará el objeto de advertencia capturado en su atributo warning, y la línea del código que disparó las advertencias en los atributos filename y lineno . Esto puede ser útil si la intención es realizar comprobaciones adicionales sobre la advertencia capturada:

with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)

Este método funciona independientemente de los filtros de aviso que estén en su lugar cuando se llame.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertWarnsRegex(warning, regex, callable, *args, **kwds)

assertWarnsRegex(warning, regex, *, msg=None)

Como assertWarns() pero también testea que regex coincide en el mensaje del aviso disparado. regex puede ser un objeto de expresión regular o una cadena que contiene una expresión regular adecuada para ser usada por re.search(). Ejemplo:

self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')

o:

with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertLogs(logger=None, level=None)

Un gestor de contexto para comprobar que al menos un mensaje está registrado en el logger o en uno de sus hijos, con al menos el level dado.

Si se da, logger debería ser un objeto logging.Logger o un str dando el nombre de un logger. El valor por defecto es el root logger, que captará todos los mensajes.

If given, level should be either a numeric logging level or its string equivalent (for example either "ERROR" or logging.ERROR). The default is logging.INFO.

El test pasa si al menos un mensaje emitido dentro del bloque with coincide con las condiciones de logger y level, de lo contrario falla.

El objeto devuelto por el gestor de contexto es un ayudante de grabación que lleva un registro de los mensajes de registro que coinciden. Tiene dos atributos:

records

Una lista de objetos logging.LogRecord de los mensajes de log coincidentes.

output

Una lista de objetos str con la salida forrajeada en los mensajes coincidentes.

Ejemplo:

with self.assertLogs('foo', level='INFO') as cm:
    logging.getLogger('foo').info('first message')
    logging.getLogger('foo.bar').error('second message')
self.assertEqual(cm.output, ['INFO:foo:first message',
                             'ERROR:foo.bar:second message'])

Nuevo en la versión 3.4.

assertNoLogs(logger=None, level=None)

Un gestor de contexto para comprobar que al menos un mensaje está registrado en el logger o en uno de sus hijos, con al menos el level dado.

Si se da, logger debería ser un objeto logging.Logger o un str dándole el nombre de un logger. El valor por defecto es el root logger, que captará todos los mensajes.

If given, level should be either a numeric logging level or its string equivalent (for example either "ERROR" or logging.ERROR). The default is logging.INFO.

A diferencia de assertLogs(), el gestor de contexto no devolverá nada.

Nuevo en la versión 3.10.

Hay también otros métodos empleados para realizar comprobaciones más específicas, tales como:

Método	Comprueba que	Nuevo en
assertAlmostEqual(a, b)	round(a-b, 7) == 0
assertNotAlmostEqual(a, b)	round(a-b, 7) != 0
assertGreater(a, b)	a > b	3.1
assertGreaterEqual(a, b)	a >= b	3.1
assertLess(a, b)	a < b	3.1
assertLessEqual(a, b)	a <= b	3.1
assertRegex(s, r)	r.search(s)	3.1
assertNotRegex(s, r)	not r.search(s)	3.2
assertCountEqual(a, b)	a y b tienen los mismos elementos y en el mismo número, sin importar su orden.	3.2

assertAlmostEqual(first, second, places=7, msg=None, delta=None)

assertNotAlmostEqual(first, second, places=7, msg=None, delta=None)

Testea que first y second son aproximadamente (o no aproximadamente) iguales calculando su diferencia, redondeando al número dado de puntos places decimales (por defecto 7), y comparado a cero. Nótese que estos métodos redondean los valores al número dado de puntos decimales (por ejemplo como la función round()) y no cifras significativas.

Si se suministra delta en vez de places que entonces la diferencia entre first y second deba ser menor o igual a (o mayor que) delta.

Suministrar tanto delta como places lanza un TypeError.

Distinto en la versión 3.2: assertAlmostEqual() considera automáticamente casi iguales a los objetos que se comparan igual. assertNotAlmostEqual() falla automáticamente si los objetos comparan iguales. Añadido el argumento de palabra clave delta.

assertGreater(first, second, msg=None)

assertGreaterEqual(first, second, msg=None)

assertLess(first, second, msg=None)

assertLessEqual(first, second, msg=None)

Prueba que first es respectivamente >, >=, < o <= que second dependiendo del nombre del método. Si no, el test fallará:

>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"

Nuevo en la versión 3.1.

assertRegex(text, regex, msg=None)

assertNotRegex(text, regex, msg=None)

Testea que una búsqueda regex coincide (o no coincide) con el text. En caso de fallo, el mensaje de error incluirá el patrón y el text (o el patrón y la parte de text que coincida inesperadamente). regex puede ser un objeto de expresión regular o una cadena que contiene una expresión regular adecuada para ser utilizada por re.search().

Nuevo en la versión 3.1: Añadido bajo el nombre de assertRegexpMatches.

Distinto en la versión 3.2: El método assertRegexpMatches() ha sido renombrado a assertRegex().

Nuevo en la versión 3.2: assertNotRegex().

Nuevo en la versión 3.5: El nombre assertNotRegexpMatches es un alias obsoleto para assertNotRegex().

assertCountEqual(first, second, msg=None)

Testea que la secuencia first contiene los mismos elementos que second, independientemente de su orden. Cuando no lo hagan, se generará un mensaje de error con las diferencias entre las secuencias.

Los elementos duplicados no son ignorados cuando se comparan first y second. Verifica si cada elemento tiene la misma cuenta en ambas secuencias. Equivalente a: assertEqual(Counter(list(first)), Counter(list(second))) pero funciona también con secuencias de objetos que no son hashable.

Nuevo en la versión 3.2.

El método assertEqual() envía la comprobación de igualdad de los objetos del mismo tipo a diferentes métodos específicos de tipo. Estos métodos ya están implementados para la mayoría de los tipos incorporados, pero también es posible registrar nuevos métodos usando addTypeEqualityFunc():

addTypeEqualityFunc(typeobj, function)

Registra un método específico de tipo llamado por assertEqual() para comprobar si dos objetos del mismo typeobj (no subclases) comparan como iguales. function debe tomar dos argumentos posicionales y un tercer argumento de palabra clave msg=None tal y como lo hace assertEqual(). Debe lanzar self.failureException(msg) cuando se detecta una desigualdad entre los dos primeros parámetros, posiblemente proporcionando información útil y explicando las desigualdades en detalle en el mensaje de error.

Nuevo en la versión 3.1.

La lista de métodos específicos de tipo utilizados automáticamente por assertEqual() se resumen en la siguiente tabla. Tenga en cuenta que normalmente no es necesario invocar estos métodos directamente.

Método	Usado para comparar	Nuevo en
assertMultiLineEqual(a, b)	strings	3.1
assertSequenceEqual(a, b)	sequences	3.1
assertListEqual(a, b)	lists	3.1
assertTupleEqual(a, b)	tuples	3.1
assertSetEqual(a, b)	sets or frozensets	3.1
assertDictEqual(a, b)	dicts	3.1

assertMultiLineEqual(first, second, msg=None)

Testea que la cadena multilínea first es igual a la cadena second. Cuando no sea igual, una diferencia de las dos cadenas que resalte las diferencias se incluirá en el mensaje de error. Este método se utiliza por defecto cuando se comparan cadenas con assertEqual().

Nuevo en la versión 3.1.

assertSequenceEqual(first, second, msg=None, seq_type=None)

Testea que dos secuencias son iguales. Si se suministra un seq_type, tanto first como second deben ser instancias de seq_type o se lanzará un fallo. Si las secuencias son diferentes se construye un mensaje de error que muestra la diferencia entre las dos.

Este método no es llamado directamente por assertEqual(), pero se usa para implementar assertListEqual() y assertTupleEqual().

Nuevo en la versión 3.1.

assertListEqual(first, second, msg=None)

assertTupleEqual(first, second, msg=None)

Testea que dos listas o tuplas son iguales. Si no es así, se construye un mensaje de error que muestra sólo las diferencias entre las dos. También se lanza un error si alguno de los parámetros es del tipo equivocado. Estos métodos se utilizan por defecto cuando se comparan listas o tuplas con assertEqual().

Nuevo en la versión 3.1.

assertSetEqual(first, second, msg=None)

Testea que dos conjuntos son iguales. Si no es así, se construye un mensaje de error que enumera las diferencias entre los conjuntos. Este método se utiliza por defecto cuando se comparan los conjuntos o frozensets con assertEqual().

Falla si cualquiera de first o second no tiene un método de set.difference().

Nuevo en la versión 3.1.

assertDictEqual(first, second, msg=None)

Testea que dos diccionarios son iguales. Si no es así, se construye un mensaje de error que muestra las diferencias en los diccionarios. Este método se usará por defecto para comparar los diccionarios en las llamadas a assertEqual().

Nuevo en la versión 3.1.

Finalmente, TestCase proporciona los siguientes métodos y atributos:

fail(msg=None)

Señala un fallo del test incondicionalmente, con msg o None para el mensaje de error.

failureException

Este atributo de clase da la excepción lanzada por el método de test. Si un marco de pruebas necesita utilizar una excepción especializada, posiblemente para llevar información adicional, debe subclasificar esta excepción para «jugar limpio» con el marco. El valor inicial de este atributo es AssertionError.

longMessage

Este atributo de clase determina lo que ocurre cuando se pasa un mensaje de fallo personalizado como el argumento msg a una llamada assertXYY que falla. True es el valor por defecto. En este caso, el mensaje personalizado se añade al final del mensaje de fallo estándar. Cuando se establece en False, el mensaje personalizado reemplaza al mensaje estándar.

La configuración de la clase puede ser anulada en los métodos de test individuales asignando un atributo de instancia, self.longMessage, a True o False antes de llamar a los métodos assert.

La configuración de la clase se reajusta antes de cada llamada de test.

Nuevo en la versión 3.1.

maxDiff

Este atributo controla la longitud máxima de las diferencias de salida de métodos assert que reportan diferencias en caso de fallo. El valor predeterminado es de 80*8 caracteres. Los métodos assert afectados por este atributo son assertSequenceEqual() (incluyendo todos los métodos de comparación de secuencias que le delegan), assertDictEqual() y assertMultiLineEqual().

Poner maxDiff en None significa que no hay una longitud máxima de diferencias.

Nuevo en la versión 3.2.

Los marcos de test pueden utilizar los siguientes métodos para reunir información sobre el test:

countTestCases()

Retorna el número de tests representados por este objeto de test. Para las instancias de TestCase, este siempre será 1.

defaultTestResult()

Retorna una instancia de la clase de resultado de test que debería utilizarse para esta clase de caso de test (si no se proporciona otra instancia de resultado al método run()).

Para las instancias de TestCase, ésta siempre será una instancia de TestResult; las subclases de TestCase deben anular esto según sea necesario.

id()

Devuelva una cadena que identifique el caso de test específico. Normalmente es el nombre completo del método de test, incluyendo el nombre del módulo y de la clase.

shortDescription()

Devuelve una descripción de la prueba, o None si no se ha proporcionado ninguna descripción. La implementación por defecto de este método devuelve la primera línea de la docstring del método de test, si está disponible, o None .

Distinto en la versión 3.1: En 3.1 esto se cambió para añadir el nombre del test a la descripción corta incluso en presencia de una docstring. Esto causó problemas de compatibilidad con las extensiones de unittest y la adición del nombre de test fue movida a la TextTestResult en Python 3.2.

addCleanup(function, /, *args, **kwargs)

Añade una función que se llamará después de tearDown() a los recursos de limpieza utilizados durante el test. Las funciones se llamarán en orden inverso al orden en que se agregan (LIFO). Se llaman con cualquier argumento y argumentos de palabra clave que se pase a addCleanup() cuando se agregan.

Si setUp() falla, lo que significa que tearDown() no se llama, entonces cualquier función de limpieza añadida seguirá siendo llamada.

Nuevo en la versión 3.1.

enterContext(cm)

Introduce el gestor de contexto context() suministrado. Si es exitoso, añade también su método __exit__() como función de limpieza mediante addCleanup() y retorna el resultado del método __enter__().

Nuevo en la versión 3.11.

doCleanups()

Este método se llama incondicionalmente después de tearDown(), o después de setUp() si setUp() lanza una excepción.

Es responsable de llamar a todas las funciones de limpieza añadidas por addCleanup(). Si necesitas que las funciones de limpieza se llamen con anterioridad a tearDown() entonces puedes llamar a doCleanups() tú mismo.

doCleanups() saca los métodos de la pila de funciones de limpieza uno a uno, así que se puede llamar en cualquier momento.

Nuevo en la versión 3.1.

classmethod addClassCleanup(function, /, *args, **kwargs)

Añade una función que se llamará después de tearDownClass() para limpiar recursos utilizados durante la clase de test. Las funciones se llamarán en orden inverso al orden en que se agregan (LIFO). Se llaman con cualquier argumento y argumento de palabra clave que se pase a addClassCleanup() cuando se añadan.

Si setUpClass() falla, lo que significa que tearDownClass() no se invoca, entonces cualquier función de limpieza añadida seguirá siendo llamada.

Nuevo en la versión 3.8.

classmethod enterClassContext(cm)

Introduce el context manager suministrado. Si es exitoso, añade también su método __exit__() como función de limpieza mediante addClassCleanup() y retorna el resultado del método __enter__().

Nuevo en la versión 3.11.

classmethod doClassCleanups()

Este método se llama incondicionalmente después de tearDownClass(), o después de setUpClass() si setUpClass() lanza una excepción.

Es responsable de llamar a todas las funciones de limpieza añadidas por addCleanupClass(). Si necesitas que las funciones de limpieza se llamen con anterioridad a tearDownClass() entonces puedes llamar a doCleanupsClass() tú mismo.

doCleanupsClass() saca los métodos de la pila de funciones de limpieza de uno en uno, así que se puede llamar en cualquier momento.

Nuevo en la versión 3.8.

class unittest.IsolatedAsyncioTestCase(methodName='runTest')

Esta clase proporciona una API similar a TestCase y también acepta corutinas como funciones de test.

Nuevo en la versión 3.8.

coroutine asyncSetUp()

Método llamado para preparar la configuración de test. Esto se llama después de setUp(). Se llama inmediatamente antes de llamar al método de test; aparte de AssertionError o SkipTest, cualquier excepción lanzada por este método se considerará un error más que un fallo del test. La implementación por defecto no hace nada.

coroutine asyncTearDown()

Método llamado inmediatamente después de que se haya llamado el método de test y se haya registrado el resultado. Esto se llama antes de tearDown(). Se llama así aunque el método de test haya lanzado una excepción, por lo que la implementación en las subclases puede necesitar ser particularmente cuidadosa en la comprobación del estado interno. Cualquier excepción, que no sea AssertionError o SkipTest, lanzada por este método se considerará un error adicional en lugar de un fallo del test (aumentando así el número total de errores reportados). Este método sólo se llamará si asyncSetUp() tiene éxito, independientemente del resultado del método de test. La implementación por defecto no hace nada.

addAsyncCleanup(function, /, *args, **kwargs)

Este método acepta una corutina que puede ser utilizada como función de limpieza.

coroutine enterAsyncContext(cm)

Introduce el asynchronous context manager suministrado. Si es exitoso, añade también su método __aexit__() como función de limpieza mediante addAsyncCleanup() y retorna el resultado del método __aenter__().

Nuevo en la versión 3.11.

run(result=None)

Establece un nuevo bucle de eventos para ejecutar el test, recogiendo el resultado en el objeto TestResult pasado como result. Si se omite result o None, se crea un objeto resultado temporal (llamando al método defaultTestResult()) y se utiliza. El objeto resultante se devuelve al invocado de run(). Al final del test se cancelan todas las tareas del bucle de eventos.

Un ejemplo ilustrando el orden:

from unittest import IsolatedAsyncioTestCase

events = []


class Test(IsolatedAsyncioTestCase):


    def setUp(self):
        events.append("setUp")

    async def asyncSetUp(self):
        self._async_connection = await AsyncConnection()
        events.append("asyncSetUp")

    async def test_response(self):
        events.append("test_response")
        response = await self._async_connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)
        self.addAsyncCleanup(self.on_cleanup)

    def tearDown(self):
        events.append("tearDown")

    async def asyncTearDown(self):
        await self._async_connection.close()
        events.append("asyncTearDown")

    async def on_cleanup(self):
        events.append("cleanup")

if __name__ == "__main__":
    unittest.main()

Después de ejecutar el test, events contendría [“setUp”, “asyncSetUp”, “test_response”, “asyncTearDown”, “tearDown”, “cleanup”].

class unittest.FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)

Esta clase implementa la porción de la interfaz TestCase que permite al corredor de tests conducir los tests, pero no proporciona los métodos que el código de test puede utilizar para comprobar e informar de los errores. Se utiliza para crear casos de test utilizando código de prueba heredado, lo que permite que se integre en un marco de tests basado en unittest.

Alias obsoletos

Por razones históricas, algunos de los métodos de TestCase tenían uno o más alias que ahora están obsoletos. La siguiente tabla lista los nombres correctos junto con sus alias obsoletos:

Nombre del método	Alias deprecado	Alias deprecado
assertEqual()	failUnlessEqual	assertEquals
assertNotEqual()	failIfEqual	assertNotEquals
assertTrue()	failUnless	assert_
assertFalse()	failIf
assertRaises()	failUnlessRaises
assertAlmostEqual()	failUnlessAlmostEqual	assertAlmostEquals
assertNotAlmostEqual()	failIfAlmostEqual	assertNotAlmostEquals
assertRegex()		assertRegexpMatches
assertNotRegex()		assertNotRegexpMatches
assertRaisesRegex()		assertRaisesRegexp

Obsoleto desde la versión 3.1: Los alias de fail* que figuran en la segunda columna han sido declarados obsoletos.

Obsoleto desde la versión 3.2: Los alias de aserción* que figuran en la tercera columna han sido declarados obsoletos.

Obsoleto desde la versión 3.2: assertRegexpMatches y assertRaisesRegexp han sido renombrados a assertRegex() y assertRaisesRegex().

Obsoleto desde la versión 3.5: El nombre assertNotRegexpMatches se ha declarado obsoleto en favor de assertNotRegex().

Agrupando tests

class unittest.TestSuite(tests=())

Esta clase representa una agregación de casos de test individuales y conjuntos de tests. La clase presenta la interfaz que necesita el corredor de tests para poder ser ejecutado como cualquier otro caso de test. Ejecutar una instancia TestSuite es lo mismo que iterar sobre el conjunto, ejecutando cada test individualmente.

Si se indican tests, debe ser un iterable de casos de test individuales u otros conjuntos de tests que se usarán para construir el conjunto inicialmente. Se proporcionan métodos adicionales para añadir casos de test y conjuntos a la colección más adelante.

Los objetos de TestSuite se comportan de manera muy parecida a los objetos de TestCase, excepto que no implementan un test. En cambio, se usan para agregar tests en grupos de tests que deben ser ejecutados juntos. Existen algunos métodos adicionales para agregar tests a las instancias de TestSuite:

addTest(test)

Añade un TestCase o TestSuite al conjunto.

addTests(tests)

Añade todos los tests de un iterable de TestCase y TestSuite a este conjunto de tests.

Esto equivale a iterar sobre tests, llamando a addTest() para cada elemento.

TestSuite comparte los siguientes métodos con TestCase:

run(result)

Ejecuta los tests asociados a este conjunto, recogiendo el resultado en el objeto de resultado del test pasado como result. Tenga en cuenta que a diferencia de TestCase.run(), TestSuite.run() requiere que se pase el objeto resultado.

debug()

Ejecuta los tests asociados con este conjunto sin recoger los resultados. Esto permite que las excepciones lanzadas por este test sean propagadas al invocador y puedes ser usadas para apoyar tests que están ejecutándose con un debugger.

countTestCases()

Retorna el numero de tests representados por este objeto de test, incluidos todos los test individuales y los sub-conjuntos.

__iter__()

Tests grouped by a TestSuite are always accessed by iteration. Subclasses can lazily provide tests by overriding __iter__(). Note that this method may be called several times on a single suite (for example when counting tests or comparing for equality) so the tests returned by repeated iterations before TestSuite.run() must be the same for each call iteration. After TestSuite.run(), callers should not rely on the tests returned by this method unless the caller uses a subclass that overrides TestSuite._removeTestAtIndex() to preserve test references.

Distinto en la versión 3.2: In earlier versions the TestSuite accessed tests directly rather than through iteration, so overriding __iter__() wasn’t sufficient for providing tests.

Distinto en la versión 3.4: En versiones anteriores, la TestSuite tenía referencias a cada TestCase después de TestSuite.run(). Las subclases pueden restaurar ese comportamiento anulando TestSuite._removeTestAtIndex().

En el uso típico de un objeto TestSuite, el método run() es invocado por un TestRunner en lugar de por el marco de test de pruebas automático del usuario final.

Cargando y ejecutando tests

class unittest.TestLoader

La clase TestLoader se utiliza para crear conjuntos de tests a partir de clases y módulos. Normalmente, no es necesario crear una instancia de esta clase; el módulo unittest proporciona una instancia que puede ser compartida como unittest.defaultTestLoader. Sin embargo, el uso de una subclase o instancia permite la personalización de algunas propiedades configurables.

Los objetos TestLoader tienen los siguientes atributos:

errors

Una lista de los errores no fatales encontrados durante la carga de tests. No reseteados por el cargador en ningún momento. Los errores fatales son señalados por el método relevante que lanza una excepción al invocador. Los errores no fatales también son indicados por una prueba sintética que lanzará el error original cuando se ejecute.

Nuevo en la versión 3.5.

Los objetos TestLoader tienen los siguientes métodos:

loadTestsFromTestCase(testCaseClass)

Devuelve un conjunto de todos los casos de test contenidos en la TestCasederivada de testCaseClass.

Se crea una instancia de caso de test para cada método nombrado por getTestCaseNames(). Por defecto, estos son los nombres de los métodos que comienzan con test. Si getTestCaseNames() no retorna ningún método, pero se implementa el método runTest(), se crea un único caso de test para ese método.

loadTestsFromModule(module, pattern=None)

Devuelva un conjunto de todos los casos de test contenidos en el módulo dado. Este método busca en module clases derivadas de TestCase y crea una instancia de la clase para cada método de test definido para la clase.

Nota

Aunque el uso de una jerarquía de clases derivadas de TestCase puede ser conveniente para compartir configuraciones y funciones de ayuda, la definición de métodos de test en clases base que no están destinadas a ser instanciadas directamente no complementa bien con este método. Hacerlo, sin embargo, puede ser útil cuando las configuraciones son diferentes y están definidas en subclases.

Si un módulo proporciona una función load_tests será llamado para cargar los tests. Esto permite a los módulos personalizar la carga de los tests. Este es el load_tests protocol. El argumento pattern se pasa como tercer argumento a load_tests.

Distinto en la versión 3.2: Se ha añadido soporte para load_tests.

Distinto en la versión 3.5: El argumento por defecto use_load_tests no documentado y no oficial es obsoleto e ignorado, aunque sigue siendo aceptado por la retrocompatibilidad. El método también acepta ahora un argumento de sólo palabra clave pattern que se pasa a load_tests como tercer argumento.

loadTestsFromName(name, module=None)

Retorna un conjunto de todos los casos de test dado un especificador de cadena.

El especificador name es un «nombre punteado» que puede resolverse ya sea a un módulo, una clase de caso de test, un método de test dentro de una clase de caso de test, una instancia TestSuite, o un objeto invocable que devuelve una instancia TestCase o TestSuite. Estas comprobaciones se aplican en el orden que se indica aquí; es decir, un método en una posible clase de caso de test se recogerá como «un método de test dentro de una clase de caso de test”, en lugar de «un objeto invocable”.

Por ejemplo, si tiene un módulo SampleTests que contiene una clase derivada de TestCase SampleTestCase con tres métodos de test (test_one(), test_two(), y test_three()), el especificador SampleTests.SampleTestCase' haría que este método devolviera una suite que ejecutara los tres métodos de prueba. El uso del especificador SampleTests.SampleTestCase.test_two' provocaría que este método devolviera una suite de tests que ejecutaría sólo el método de test test_two(). El especificador puede referirse a los módulos y paquetes que no han sido importados; serán importados como un efecto secundario.

El método opcionalmente resuelve name relativo al module dado.

Distinto en la versión 3.5: Si un ImportError o AttributeError ocurre mientras atraviesa name entonces se devolverá un test sintético que lanza ese error cuando se ejecuta. Estos errores están incluidos en los errores acumulados por self.errors.

loadTestsFromNames(names, module=None)

Similar a loadTestsFromName(), pero toma una secuencia de nombres en lugar de un solo nombre. El valor de retorno es una suite de tests que soporta todos los test definidos para cada nombre.

getTestCaseNames(testCaseClass)

Devuelve una secuencia ordenada de nombres de métodos encontrados dentro de testCaseClass; esta debería ser una subclase de TestCase.

discover(start_dir, pattern='test*.py', top_level_dir=None)

Encuentra todos los módulos de prueba recurriendo a subdirectorios del directorio de inicio especificado, y retorna un objeto de TestSuite que los contenga. Sólo se cargarán los archivos de test que coincidan con el pattern. (Utilizando la coincidencia de patrones de estilo de shell.) Sólo se cargarán los nombres de los módulos que sean importables (es decir, que sean identificadores Python válidos).

Todos los módulos de test deben ser importables desde el nivel superior del proyecto. Si el directorio de inicio no es el directorio de nivel superior, entonces el directorio de nivel superior debe ser especificado por separado.

Si la importación de un módulo falla, por ejemplo debido a un error de sintaxis, entonces esto se registrará como un error único y el descubrimiento continuará. Si el fallo en la importación se debe a que SkipTest se ha lanzado, se registrará como un salto en lugar de un error.

Si se encuentra un paquete (un directorio que contiene un archivo llamado __init__.py), se comprobará si el paquete tiene una función load_tests. Si existe, entonces se invocará package.load_tests(loader, tests, pattern). Test discovery se encarga de asegurar que un paquete sólo se comprueba una vez durante una invocación, incluso si la propia función load_tests llama a loader.discover.

Si load_tests existe, entonces el descubrimiento no recurre en el paquete, load_tests es responsable de cargar todos los tests en el paquete.

El patrón no se almacena deliberadamente como atributo cargador para que los paquetes puedan continuar descubriéndose a sí mismos. top_level_dir se almacena de forma que load_tests no necesita pasar este argumento a loader.discover().

start_dir puede ser un nombre de módulo punteado así como un directorio.

Nuevo en la versión 3.2.

Distinto en la versión 3.4: Los módulos que lanzan SkipTest en la importación se registran como saltos, no como errores.

Distinto en la versión 3.4: start_dir puede ser un paquete de espacios de nombres.

Distinto en la versión 3.4: Las rutas se ordenan antes de ser importadas para que el orden de ejecución sea el mismo, incluso si el orden del sistema de archivos subyacente no depende del nombre del archivo.

Distinto en la versión 3.5: Los paquetes encontrados son ahora comprobados para load_tests sin importar si su ruta coincide con el pattern, porque es imposible que el nombre de un paquete coincida con el patrón por defecto.

Distinto en la versión 3.11: start_dir no puede ser un paquete de espacios de nombres. Ha estado roto desde Python 3.7 y Python 3.11 lo elimina oficialmente.

Los siguientes atributos de un TestLoader pueden ser configurados ya sea por subclasificación o asignación en una instancia:

testMethodPrefix

Cadena que da el prefijo de los nombres de métodos que serán interpretados como métodos de test. El valor por defecto es 'test'.

This affects getTestCaseNames() and all the loadTestsFrom* methods.

sortTestMethodsUsing

Function to be used to compare method names when sorting them in getTestCaseNames() and all the loadTestsFrom* methods.

suiteClass

Objeto invocable que construye un conjunto de pruebas a partir de una lista de pruebas. No se necesitan métodos en el objeto resultante. El valor por defecto es la clase TestSuite.

This affects all the loadTestsFrom* methods.

testNamePatterns

List of Unix shell-style wildcard test name patterns that test methods have to match to be included in test suites (see -k option).

If this attribute is not None (the default), all test methods to be included in test suites must match one of the patterns in this list. Note that matches are always performed using fnmatch.fnmatchcase(), so unlike patterns passed to the -k option, simple substring patterns will have to be converted using * wildcards.

This affects all the loadTestsFrom* methods.

Nuevo en la versión 3.7.

class unittest.TestResult

Esta clase se utiliza para recopilar información sobre qué tests han tenido éxito y cuáles han fracasado.

Un objeto TestResult almacena los resultados de una serie de pruebas. Las clases TestCase y TestSuite aseguran que los resultados se registren correctamente; los autores de los tests no tienen que preocuparse de registrar el resultado de las mismas.

Los marcos de pruebas construidos sobre unittest pueden querer acceder al objeto TestResult generado por la ejecución de un conjunto de tests con fines de reporte; una instancia TestResult es devuelta por el método TestRunner.run() para este propósito.

Las instancias de TestResult tienen los siguientes atributos que serán de interés cuando se inspeccionen los resultados de la ejecución de un conjunto de tests:

errors

Una lista que contiene 2 tuplas de instancias TestCase y cadenas con formato de tracebacks. Cada tupla representa una prueba que lanzó una excepción inesperada.

failures

A list containing 2-tuples of TestCase instances and strings holding formatted tracebacks. Each tuple represents a test where a failure was explicitly signalled using the assert* methods.

skipped

Una lista que contiene 2 tuplas de instancias de TestCase y cadenas que contienen la razón para saltarse el test.

Nuevo en la versión 3.1.

expectedFailures

Una lista que contiene 2 tuplas de instancias TestCase y cadenas con formato de traceback. Cada tupla representa un fallo esperado del caso de test.

unexpectedSuccesses

Una lista que contiene instancias de TestCase que fueron marcadas como fracasos esperados, pero tuvieron éxito.

shouldStop

Puesto en True cuando la ejecución de los tests se detenga por stop().

testsRun

El número total de tests realizados hasta ahora.

buffer

Si se ajusta a true, sys.stdout y sys.stderr serán almacenados entre startTest() y stopTest() siendo llamados. La salida recolectada sólo tendrá eco en el verdadero sys.stdout y sys.stderr si la prueba falla o se equivoca. Cualquier salida también se adjunta al mensaje de fallo / error.

Nuevo en la versión 3.2.

failfast

Si se ajusta a true stop() se llamará al primer fallo o error, deteniendo la ejecución de la prueba.

Nuevo en la versión 3.2.

tb_locals

Si se ajusta a true entonces las variables locales se mostrarán en los tracebacks.

Nuevo en la versión 3.5.

wasSuccessful()

Devuelve True si todas las pruebas realizadas hasta ahora han pasado, de lo contrario devuelve False.

Distinto en la versión 3.4: Devuelve False si hubo algún unexpectedSuccesses de las pruebas marcadas con el decorador expectedFailure().

stop()

Este método puede ser llamado para señalar que el conjunto de pruebas que se están ejecutando debe ser abortado poniendo el atributo shouldStop en True. TestRunner los objetos deben respetar esta bandera y regresar sin ejecutar ninguna prueba adicional.

Por ejemplo, esta característica es utilizada por la clase TextTestRunner para detener el marco de pruebas cuando el usuario señala una interrupción desde el teclado. Las herramientas interactivas que proporcionan implementaciones de TestRunner pueden usar esto de manera similar.

Los siguientes métodos de la clase TestResult se utilizan para mantener las estructuras de datos internos, y pueden ampliarse en subclases para apoyar los requisitos de información adicionales. Esto es particularmente útil para construir herramientas que apoyen la presentación de informes interactivos mientras se ejecutan las pruebas.

startTest(test)

Llamado cuando el caso de prueba test está a punto de ser ejecutado.

stopTest(test)

Llamado después de que el caso de prueba prueba haya sido ejecutado, independientemente del resultado.

startTestRun()

Llamado una vez antes de que se ejecute cualquier prueba.

Nuevo en la versión 3.1.

stopTestRun()

Llamado una vez después de que se ejecuten todas las pruebas.

Nuevo en la versión 3.1.

addError(test, err)

Llamado cuando el caso de prueba test plantea una excepción inesperada. err es una tupla de la forma devuelta por sys.exc_info(): (type, value, traceback).

La implementación por defecto añade una tupla (test, formatted_err) al atributo errors de la instancia, donde formatted_err es una traza formateada derivada de err.

addFailure(test, err)

Llamado cuando el caso de prueba test señala un fallo. err es una tupla de la forma devuelta por sys.exc_info(): (type, value, traceback).

La implementación por defecto añade una tupla (test, formatted_err) al atributo failures de la instancia, donde formatted_err es una traza formateada derivada de err.

addSuccess(test)

Llamado cuando el caso de prueba test tenga éxito.

La implementación por defecto no hace nada.

addSkip(test, reason)

Llamado cuando se salta el caso de prueba test. reason es la razón que la prueba dio para saltarse.

La implementación por defecto añade una tupla (test, reason) al atributo skipped de la instancia.

addExpectedFailure(test, err)

Llamó cuando el caso de prueba test falla, pero fue marcado con el decorador expectedFailure().

La implementación por defecto añade una tupla (test, formatted_err) al atributo expectedFailures de la instancia, donde formatted_err es una traza formateada derivada de err.

addUnexpectedSuccess(test)

Llamó cuando el caso de prueba test se marcó con el decorador expectedFailure(), pero tuvo éxito.

La implementación por defecto añade la prueba al atributo unexpectedSuccesses de la instancia.

addSubTest(test, subtest, outcome)

Llamado cuando termina una subtest. test es el caso de prueba correspondiente al método de test. subtest es una instancia personalizada TestCase que describe el test.

Si outcome es None, el subtest tuvo éxito. De lo contrario, falló con una excepción en la que outcome es una tupla de la forma devuelta por sys.exc_info(): (type, value, traceback).

La implementación por defecto no hace nada cuando el resultado es un éxito, y registra los fallos del subtest como fallos normales.

Nuevo en la versión 3.4.

class unittest.TextTestResult(stream, descriptions, verbosity)

Una implementación concreta de TestResult utilizado por el TextTestRunner.

Nuevo en la versión 3.2: Esta clase se llamaba anteriormente _TextTestResult. El antiguo nombre todavía existe como un alias pero está obsoleto.

unittest.defaultTestLoader

Instancia de la clase TestLoader destinada a ser compartida. Si no es necesario personalizar la clase TestLoader, esta instancia puede utilizarse en lugar de crear repetidamente nuevas instancias.

class unittest.TextTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False)

Una implementación básica del test runner que produce resultados en una corriente. Si stream es None, el valor por defecto, sys.stderr se utiliza como flujo de salida. Esta clase tiene unos pocos parámetros configurables, pero es esencialmente muy simple. Las aplicaciones gráficas que ejecutan las suites de prueba deben proporcionar implementaciones alternativas. Tales implementaciones deberían aceptar **kwargs como interfaz para construir los cambios de los corredores cuando se añaden características a unittest.

Por defecto este runner muestra DeprecationWarning, PendingDeprecationWarning, ResourceWarning y ImportWarning aunque estén ignorados por defecto. Las advertencias de deprecación causadas por métodos deprecated unittest también tienen un caso especial y, cuando los filtros de advertencia están 'default' o 'always', aparecerán sólo una vez por módulo, para evitar demasiados mensajes de advertencia. Este comportamiento puede ser anulado usando las opciones -Wd o -Wa de Python (ver Control de advertencias) y dejando warnings a None.

Distinto en la versión 3.2: Añadió el argumento warnings.

Distinto en la versión 3.2: El flujo por defecto está configurado como sys.stderr en tiempo de instanciación en lugar de tiempo de importación.

Distinto en la versión 3.5: Añadido el parámetro tb_locals.

_makeResult()

Este método devuelve la instancia de TestResult usada por run(). No está destinado a ser llamado directamente, pero puede ser anulado en subclases para proporcionar un TestResult personalizado.

_makeResult() instanciando la clase o el pasaje llamado en el constructor TextTestRunner como el argumento de resultclass. Por defecto es TextTestResult si no se proporciona ninguna resultclass. La clase de resultado se instanciará con los siguientes argumentos:

stream, descriptions, verbosity

run(test)

Este método es la principal interfaz pública del TextTestRunner. Este método toma una instancia TestSuite o TestCase. Se crea una TestResult llamando a _makeResult() y se ejecuta(n) la(s) prueba(s) y se imprimen los resultados a stdout.

unittest.main(module='__main__', defaultTest=None, argv=None, testRunner=None, testLoader=unittest.defaultTestLoader, exit=True, verbosity=1, failfast=None, catchbreak=None, buffer=None, warnings=None)

Un programa de línea de comandos que carga un conjunto de pruebas de módulo y las ejecuta; esto es principalmente para hacer los módulos de prueba convenientemente ejecutables. El uso más simple de esta función es incluir la siguiente línea al final de un guión de prueba:

if __name__ == '__main__':
    unittest.main()

Puedes hacer pruebas con información más detallada pasando el argumento de la verbosity:

if __name__ == '__main__':
    unittest.main(verbosity=2)

El argumento defaultTest es el nombre de una prueba única o un iterable de nombres de pruebas a ejecutar si no se especifican nombres de pruebas a través de argv. Si no se especifica o Ninguno y no se proporcionan nombres de pruebas vía argv, se ejecutan todas las pruebas encontradas en modulo.

El argumento argv puede ser una lista de opciones pasadas al programa, siendo el primer elemento el nombre del programa. Si no se especifica o Ninguno, se utilizan los valores de sys.argv.

El argumento testRunner puede ser una clase de corredor de prueba o una instancia ya creada de él. Por defecto main llama sys.exit() con un código de salida que indica el éxito o el fracaso de la ejecución de las pruebas.

El argumento testLoader tiene que ser una instancia TestLoader, y por defecto defaultTestLoader.

main apoya el uso del intérprete interactivo pasando el argumento exit=False. Esto muestra el resultado en la salida estándar sin llamar a sys.exit():

>>> from unittest import main
>>> main(module='test_module', exit=False)

Los parámetros failfast, catchbreak y buffer tienen el mismo efecto que las command-line options del mismo nombre.

El argumento warnings especifica el filtro de aviso que debe ser usado mientras se realizan los tests. Si no se especifica, permanecerá como None si se pasa una opción -W a python (ver Warning control), de lo contrario se establecerá como ’default’.

Invocar main en realidad devuelve una instancia de la clase TestProgram. Esto almacena el resultado de las pruebas ejecutadas como el atributo result.

Distinto en la versión 3.1: El parámetro exit fue añadido.

Distinto en la versión 3.2: Los parámetros verbosity, failfast, catchbreak, buffer y warnings fueron añadidos.

Distinto en la versión 3.4: El parámetro defaultTest fue cambiado para aceptar también un iterable de nombres de pruebas.

load_tests protocolo

Nuevo en la versión 3.2.

Los módulos o paquetes pueden personalizar la forma en que se cargan las pruebas a partir de ellos durante las ejecuciones de prueba normales o el descubrimiento de pruebas mediante la implementación de una función llamada load_tests.

Si un módulo de tests define load_tests será llamado por TestLoader.loadTestsFromModule() con los siguientes argumentos:

load_tests(loader, standard_tests, pattern)

donde pattern se pasa directamente desde loadTestsFromModule. Por defecto es None.

Debe retornar una TestSuite.

loader es la instancia de TestLoader haciendo la carga. standard_tests son los tests que se cargarían por defecto desde el módulo. Es común que los módulos de test sólo quieran añadir o quitar tests del conjunto de tests estándar. El tercer argumento se usa cuando se cargan paquetes como parte del descubrimiento de tests.

Una típica función de load_tests que carga pruebas de un conjunto específico de TestCase`class:`TestCase puede ser como:

test_cases = (TestCase1, TestCase2, TestCase3)

def load_tests(loader, tests, pattern):
    suite = TestSuite()
    for test_class in test_cases:
        tests = loader.loadTestsFromTestCase(test_class)
        suite.addTests(tests)
    return suite

Si discovery se inicia en un directorio que contiene un paquete, ya sea desde la línea de comandos o llamando a TestLoader.discover(), entonces el paquete __init__.py se comprobará por load_tests. Si esa función no existe, discover se reincorporará al paquete como si fuera un directorio más. De lo contrario, el descubrimiento de los tests del paquete se dejará en load_tests que se llama con los siguientes argumentos:

load_tests(loader, standard_tests, pattern)

Esto debería devolver un TestSuite que represente todas las pruebas del paquete. (test_estándar sólo contendrá las pruebas recogidas de __init__.py.)

Debido a que el patrón se pasa a load_tests el paquete es libre de continuar (y potencialmente modificar) el descubrimiento de pruebas. Una función de “no hace nada” load_test para un paquete de pruebas se vería como:

def load_tests(loader, standard_tests, pattern):
    # top level directory cached on loader instance
    this_dir = os.path.dirname(__file__)
    package_tests = loader.discover(start_dir=this_dir, pattern=pattern)
    standard_tests.addTests(package_tests)
    return standard_tests

Distinto en la versión 3.5: Discovery ya no comprueba si los nombres de los paquetes coinciden con el patrón debido a la imposibilidad de que los nombres de los paquetes coincidan con el patrón por defecto.

Instalaciones para clases y módulos

Los accesorios de nivel de clase y módulo se implementan en TestSuite. Cuando el conjunto de pruebas se encuentra con una prueba de una nueva clase entonces se llama tearDownClass() de la clase anterior (si existe), seguido de setUpClass() de la nueva clase.

Del mismo modo, si una prueba es de un módulo diferente de la prueba anterior, entonces se ejecuta DesmontarMódulo del módulo anterior, seguido de DesmontarMódulo del nuevo módulo.

Después de todas las pruebas, se ejecutan los últimos tearDownClass y tearDownModule.

Tenga en cuenta que los accesorios compartidos no juegan bien con las características [potenciales] como la paralelización de la prueba y rompen el aislamiento de la prueba. Deben ser usados con cuidado.

El orden por defecto de las pruebas creadas por los cargadores de pruebas unitarias es agrupar todas las pruebas de los mismos módulos y clases. Esto llevará a que setUpClass / setUpModule (etc) sea llamado exactamente una vez por clase y módulo. Si se aleatoriza el orden, de manera que las pruebas de diferentes módulos y clases sean adyacentes entre sí, entonces estas funciones compartidas de fixture pueden ser llamadas varias veces en una sola ejecución de prueba.

Los accesorios compartidos no están pensados para trabajar con suites con pedidos no estándar. Todavía existe una BaseTestSuite para los marcos de trabajo que no quieren soportar accesorios compartidos.

Si hay alguna excepción planteada durante una de las funciones compartidas del aparato, la prueba se notifica como un error. Debido a que no hay una instancia de prueba correspondiente, se crea un objeto _ErrorHolder (que tiene la misma interfaz que un TestCase) para representar el error. Si sólo estás usando el standard unittest test runner entonces este detalle no importa, pero si eres un autor de marcos de trabajo puede ser relevante.

setUpClass y tearDownClass

Estos deben ser implementados como métodos de clase:

import unittest

class Test(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls._connection = createExpensiveConnectionObject()

    @classmethod
    def tearDownClass(cls):
        cls._connection.destroy()

Si quieres que se invoque a SetUpClass y BreakdownClass en clases base, debes llamarlos tú mismo. Las implementaciones en TestCase están vacías.

Si se lanza una excepción durante una setUpClass, entonces los tests de la clase no se ejecutan y la tearDownClass no se ejecuta. Las clases que se salten no tendrán setUpClass o tearDownClass. Si la excepción es una SkipTest entonces la clase será reportada como salteada en lugar de como un error.

setUpModule y tearDownModule

Estos deben ser implementados como funciones:

def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()

Si se lanza una excepción en un setUpModule, entonces no se ejecutará ninguna de las pruebas del módulo y no se ejecutará el tearDownModule. Si la excepción es una SkipTest entonces el módulo será reportado como saltado en lugar de como un error.

Para agregar código de limpieza que se debe ejecutar incluso en el caso de una excepción, utilice addModuleCleanup:

unittest.addModuleCleanup(function, /, *args, **kwargs)

Añade una función que se llamará después de tearDownModule() para limpiar los recursos utilizados durante la clase de test. Las funciones se llamarán en orden inverso al orden en que se agregan (LIFO). Se llaman con cualquier argumento y palabra clave que se pase a addModuleCleanup() cuando se añadan.

Si setUpModule() falla, lo que significa que tearDownModule() no se invoca, entonces cualquier función de limpieza añadida seguirá siendo invocada.

Nuevo en la versión 3.8.

classmethod unittest.enterModuleContext(cm)

Introduce el context manager suministrado. Si es exitoso, añade también su método __exit__() como función de limpieza mediante addModuleCleanup() y retorna el resultado del método __enter__().

Nuevo en la versión 3.11.

unittest.doModuleCleanups()

Esta función se llama incondicionalmente después de tearDownModule(), o después de setUpModule() si setUpModule() lanza una excepción.

Es responsable de invocar a todas las funciones de limpieza añadidas por addCleanupModule(). Si necesitas que las funciones de limpieza se llamen previamente a tearDownModule() entonces puedes invocar a doModuleCleanups() tú mismo.

doModuleCleanups() saca los métodos de la pila de funciones de limpieza uno a uno, así que se puede llamar en cualquier momento.

Nuevo en la versión 3.8.

Manejo de señales

Nuevo en la versión 3.2.

La opción -c/--catch línea de comando para unittest, junto con el parámetro catchbreak de unittest.main(), proporcionan un manejo más amigable del control-C durante una prueba. Con el comportamiento catch break habilitado, control-C permitirá que se complete la prueba que se está ejecutando actualmente, y la ejecución de la prueba terminará y reportará todos los resultados hasta ahora. Un segundo control-C lanzará una KeyboardInterrupt de la manera habitual.

El manejador de señales de manejo de control-c intenta permanecer compatible con el código o las pruebas que instalan su propio manejador signal.SIGINT . Si se llama al manejador unittest pero no es el manejador signal.SIGINT instalado, es decir, ha sido reemplazado por el sistema bajo test y delegado, entonces llama al manejador por defecto. Este será normalmente el comportamiento esperado por el código que reemplaza un manejador instalado y delega en él. Para las pruebas individuales que necesiten el manejo de control-c de unittest deshabilitado se puede usar el decorador removeHandler().

Hay algunas funciones de utilidad para que los autores de marcos de trabajo habiliten la funcionalidad de control de control-c dentro de los marcos de prueba.

unittest.installHandler()

Instala el controlador de control-c. Cuando se recibe una signal.SIGINT (normalmente en respuesta a que el usuario presione control-c) todos los resultados registrados tienen stop() llamado.

unittest.registerResult(result)

Registrar un objeto TestResult para el manejo de control-c. El registro de un resultado almacena una referencia débil a él, por lo que no evita que el resultado sea recogido por el recolector de basura.

El registro de un objeto TestResult no tiene efectos secundarios si el manejo de control-c no está habilitado, por lo que los marcos de pruebas pueden registrar incondicionalmente todos los resultados que crean independientemente de si el manejo está habilitado o no.

unittest.removeResult(result)

Elimine un resultado registrado. Una vez que un resultado ha sido eliminado, stop() ya no se llamará en ese objeto de resultado en respuesta a un control-c.

unittest.removeHandler(function=None)

Cuando se llama sin argumentos, esta función quita el gestor control-c si se ha instalado. Esta función también se puede utilizar como decorador de tests para quitar temporalmente el controlador mientras se ejecuta el test:

@unittest.removeHandler
def test_signal_handling(self):
    ...