`unittest.mock` — Biblioteca de objetos simulados¶

Nuevo en la versión 3.3.

unittest.mock es una biblioteca para pruebas de software en Python. Te permite reemplazar partes del sistema bajo prueba con objetos simulados y hacer aserciones sobre cómo se han utilizado.

El módulo unittest.mock proporciona una clase principal Mock eliminando la necesidad de crear una gran cantidad de stubs en todo el conjunto de pruebas. Después de realizar una determinada acción, puedes hacer aserciones sobre qué métodos/atributos se usaron y los argumentos con los que se llamaron. También puedes especificar valores de retorno y establecer los atributos necesarios de la forma habitual.

Además, mock proporciona un decorador patch() que puede manejar el parcheo de atributos a nivel de clase y de módulo dentro del ámbito de una prueba, junto con sentinel para crear objetos únicos. Consulta quick guide para ver algunos ejemplos de cómo utilizar Mock, MagicMock y patch().

Mock is designed for use with unittest and is based on the “action -> assertion” pattern instead of “record -> replay” used by many mocking frameworks.

Hay un backport del módulo unittest.mock para versiones anteriores de Python disponible en PyPI.

Guía rápida¶

Los objetos de las clases Mock y MagicMock van creando todos los atributos y métodos a medida que se accede a ellos y almacenan detalles de cómo se han utilizado. Puedes configurarlos para especificar valores de retorno o limitar qué atributos están disponibles y posteriormente hacer aserciones sobre cómo han sido utilizados:

>>> from unittest.mock import MagicMock
>>> thing = ProductionClass()
>>> thing.method = MagicMock(return_value=3)
>>> thing.method(3, 4, 5, key='value')
3
>>> thing.method.assert_called_with(3, 4, 5, key='value')

side_effect te permite implementar efectos colaterales, lo que incluye lanzar una excepción cuando se llama a un objeto simulado:

>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
 ...
KeyError: 'foo'

>>> values = {'a': 1, 'b': 2, 'c': 3}
>>> def side_effect(arg):
...     return values[arg]
...
>>> mock.side_effect = side_effect
>>> mock('a'), mock('b'), mock('c')
(1, 2, 3)
>>> mock.side_effect = [5, 4, 3, 2, 1]
>>> mock(), mock(), mock()
(5, 4, 3)

Existen muchas otras formas de configurar y controlar el comportamiento de Mock. Por ejemplo, el argumento spec configura el objeto simulado para que tome su especificación de otro objeto. Cualquier intento de acceder a atributos o métodos en el objeto simulado que no existan en la especificación fallará lanzando una excepción AttributeError.

El decorador / gestor de contexto patch() facilita la simulación de clases u objetos en un módulo bajo prueba. El objeto que especifiques será reemplazado por un objeto simulado (u otro objeto) durante la prueba y será restaurado cuando esta finalice:

>>> from unittest.mock import patch
>>> @patch('module.ClassName2')
... @patch('module.ClassName1')
... def test(MockClass1, MockClass2):
...     module.ClassName1()
...     module.ClassName2()
...     assert MockClass1 is module.ClassName1
...     assert MockClass2 is module.ClassName2
...     assert MockClass1.called
...     assert MockClass2.called
...
>>> test()

Nota

Cuando anidas decoradores patch, los objetos simulados se pasan a la función decorada en el mismo orden en el que fueron aplicados (el orden normal en el que se aplican los decoradores en Python). Esto significa de abajo hacia arriba, por lo que en el ejemplo anterior se pasa primero el objeto simulado para module.ClassName1.

Al usar patch() es importante que parchees los objetos en el espacio de nombres donde son buscados. Esto normalmente es sencillo, pero para una guía rápida, lee dónde parchear.

Además de decorador, la función patch() se puede usar como gestor de contexto en una declaración with:

>>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
...     thing = ProductionClass()
...     thing.method(1, 2, 3)
...
>>> mock_method.assert_called_once_with(1, 2, 3)

También existe la función patch.dict() que permite establecer valores en un diccionario dentro de un ámbito y restaurar el diccionario a su estado original cuando finaliza la prueba:

>>> foo = {'key': 'value'}
>>> original = foo.copy()
>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
...     assert foo == {'newkey': 'newvalue'}
...
>>> assert foo == original

Mock admite la simulación de los métodos mágicos de Python. La forma más sencilla de utilizar métodos mágicos es mediante la clase MagicMock. Te permite hacer cosas como:

>>> mock = MagicMock()
>>> mock.__str__.return_value = 'foobarbaz'
>>> str(mock)
'foobarbaz'
>>> mock.__str__.assert_called_with()

Mock también permite asignar funciones (u otras instancias de Mock) a métodos mágicos y se asegura de que serán llamadas de forma apropiada. La clase MagicMock es solo una variante de Mock con la diferencia de que tiene todos los métodos mágicos previamente creados para ti (bueno, todos los que son útiles).

El siguiente es un ejemplo de uso de métodos mágicos utilizando la clase Mock ordinaria:

>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'

Para asegurarte de que los objetos simulados en tus pruebas tienen exactamente la misma API que los objetos que están reemplazando, puedes usar autoespecificación. La autoespecificación se puede realizar a través del argumento autospec de patch, o mediante la función create_autospec(). La autoespecificación crea objetos simulados que tienen los mismos atributos y métodos que los objetos que están reemplazando, y todas las función y métodos (incluidos los constructores) tienen la misma firma de llamada que los objetos reales.

Esto asegura que tus simulaciones fallarán, si se utilizan incorrectamente, de la misma manera que lo haría tu código en producción:

>>> from unittest.mock import create_autospec
>>> def function(a, b, c):
...     pass
...
>>> mock_function = create_autospec(function, return_value='fishy')
>>> mock_function(1, 2, 3)
'fishy'
>>> mock_function.assert_called_once_with(1, 2, 3)
>>> mock_function('wrong arguments')
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes exactly 3 arguments (1 given)

create_autospec() también se puede usar en clases, donde copia la firma del método __init__, y en objetos invocables, donde copia la firma del método __call__.

La clase Mock¶

Mock es un objeto simulado flexible, destinado a reemplazar el uso de stubs y dobles de prueba en todo tu código. Los objetos Mock son invocables y crean atributos en el mismo momento que se accede a ellos como nuevos objetos Mock 1. Acceder al mismo atributo siempre retornará el mismo objeto Mock. Además, registran cómo los usas, lo que te permite hacer aserciones sobre cómo tu código ha interaccionado con ellos.

MagicMock es una subclase de Mock con todos los métodos mágicos creados previamente y listos para ser usados. También hay variantes no invocables, útiles cuando se están simulando objetos que no se pueden llamar: NonCallableMock y NonCallableMagicMock

Los decoradores patch() facilitan la sustitución temporal de clases en un módulo en particular con un objeto Mock. Por defecto, patch() creará un objeto MagicMock automáticamente. Se puede especificar una clase alternativa a Mock usando el argumento new_callable de patch().

class unittest.mock.Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)¶

Crea un nuevo objeto Mock. Mock toma varios argumentos opcionales que especifican el comportamiento del objeto Mock:

spec: Puede ser una lista de cadenas de caracteres o un objeto existente previamente (una clase o una instancia) que actúa como la especificación del objeto simulado. Si pasas un objeto, se forma una lista de cadenas llamando a la función dir en el objeto (excluyendo los métodos y atributos mágicos no admitidos). Acceder a cualquier atributo que no esté en esta lista generará una excepción AttributeError.

Si spec es un objeto (en lugar de una lista de cadenas de caracteres), __class__ retorna la clase del objeto especificado. Esto permite que los objetos simulados pasen las pruebas de isinstance().
spec_set: Una variante más estricta de spec. Si se utiliza, cualquier intento de establecer u obtener un atributo del objeto simulado que no esté en el objeto pasado como spec_set lanzará una excepción AttributeError.
side_effect: Una función que se llamará cada vez que el objeto simulado sea invocado. Consultar el atributo side_effect para más información. Es útil para lanzar excepciones o para cambiar dinámicamente valores de retorno. La función se llama con los mismos argumentos que el objeto simulado, y a menos que retorne DEFAULT, su valor de retorno se utiliza como valor de retorno del propio objeto simulado.

Alternativamente side_effect puede ser una clase o instancia de excepción. En este caso, se lanza la excepción cuando se llama al objeto simulado.

Si side_effect es un iterable, cada llamada al objeto simulado retornará el siguiente valor del iterable.

Un side_effect se puede desactivar estableciéndolo en None.
return_value: El valor retornado cuando se llama al objeto simulado. Por defecto, este es una nueva instancia de la clase Mock (creada en el primer acceso). Consultar el atributo return_value para más detalles.
unsafe: Por defecto, si cualquier atributo comienza con assert o assret y se intenta acceder a él, se lanza una excepción AttributeError. Pasar unsafe=True permitirá el acceso a estos atributos.

Nuevo en la versión 3.5.
wraps: objeto a envolver (simular) por la instancia de Mock. Si wraps no es None, al llamar al objeto Mock se pasa la llamada a través del objeto envuelto (retornando el resultado real). Acceder a un atributo del objeto simulado retornará otro objeto Mock que envuelve al atributo correspondiente del objeto real envuelto (de modo que intentar acceder a un atributo que no existe lanzará una excepción AttributeError).

Si el objeto simulado tiene un return_value explícito establecido, las llamadas no se pasan al objeto envuelto y return_value se retorna en su lugar.
name: Si el objeto simulado tiene un nombre, será utilizado en la representación imprimible del mismo. Esto puede ser útil para la depuración. El nombre se propaga a los objetos simulados hijos.

Los objetos simulados también pueden ser invocados con argumentos por palabra clave arbitrarios. Estos serán utilizados para establecer atributos en el objeto simulado una vez creado. Consultar el método configure_mock() para más detalles.

assert_called()¶

Aserta si el objeto simulado se ha invocado al menos una vez.

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called()

Nuevo en la versión 3.6.

assert_called_once()¶

Aserta si el objeto simulado se ha invocado exactamente una vez.

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_once()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_once()
Traceback (most recent call last):
...
AssertionError: Expected 'method' to have been called once. Called 2 times.

Nuevo en la versión 3.6.

assert_called_with(*args, **kwargs)¶

Este método es una manera apropiada de asertar si la última llamada se ha realizado de una manera particular:

>>> mock = Mock()
>>> mock.method(1, 2, 3, test='wow')
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_with(1, 2, 3, test='wow')

assert_called_once_with(*args, **kwargs)¶

Assert that the mock was called exactly once and that call was with the specified arguments.

>>> mock = Mock(return_value=None)
>>> mock('foo', bar='baz')
>>> mock.assert_called_once_with('foo', bar='baz')
>>> mock('other', bar='values')
>>> mock.assert_called_once_with('other', bar='values')
Traceback (most recent call last):
  ...
AssertionError: Expected 'mock' to be called once. Called 2 times.

assert_any_call(*args, **kwargs)¶

Aserta si el objeto simulado se ha invocado con los argumentos especificados.

La aserción pasa si el objeto simulado se ha invocado en algún momento, a diferencia de assert_called_with() y assert_called_once_with(), con los que sólo pasa la aserción si la llamada es la más reciente, y en el caso de assert_called_once_with() también debe ser la única llamada realizada.

>>> mock = Mock(return_value=None)
>>> mock(1, 2, arg='thing')
>>> mock('some', 'thing', 'else')
>>> mock.assert_any_call(1, 2, arg='thing')

assert_has_calls(calls, any_order=False)¶

Aserta si el objeto simulado se ha invocado con las llamadas especificadas. La lista mock_calls se compara con la lista de llamadas.

Si any_order es falso entonces las llamadas deben ser secuenciales. No puede haber llamadas adicionales antes o después de las llamadas especificadas.

Si any_order es verdadero, las llamadas pueden estar en cualquier orden, pero deben aparecer todas en mock_calls.

>>> mock = Mock(return_value=None)
>>> mock(1)
>>> mock(2)
>>> mock(3)
>>> mock(4)
>>> calls = [call(2), call(3)]
>>> mock.assert_has_calls(calls)
>>> calls = [call(4), call(2), call(3)]
>>> mock.assert_has_calls(calls, any_order=True)

assert_not_called()¶

Aserta si el objeto simulado nunca fue invocado.

>>> m = Mock()
>>> m.hello.assert_not_called()
>>> obj = m.hello()
>>> m.hello.assert_not_called()
Traceback (most recent call last):
  ...
AssertionError: Expected 'hello' to not have been called. Called 1 times.

Nuevo en la versión 3.5.

reset_mock(*, return_value=False, side_effect=False)¶

El método reset_mock restablece todos los atributos de llamada en un objeto simulado:

>>> mock = Mock(return_value=None)
>>> mock('hello')
>>> mock.called
True
>>> mock.reset_mock()
>>> mock.called
False

Distinto en la versión 3.6: Se añadieron dos argumentos por palabra clave a la función reset_mock.

Esto puede ser útil cuando se quiere hacer una serie de aserciones que reutilizan el mismo objeto. Ten en cuenta que por defecto reset_mock() no borra el valor de retorno, side_effect, ni cualquier atributo hijo que hayas establecido mediante asignación normal. En caso de que quieras restablecer return_value o side_effect, debes pasar el parámetro correspondiente como True. Los objetos simulados hijos y el objeto simulado que conforma el valor de retorno (si los hay) se restablecen también.

Nota

return_value y side_effect son argumentos por palabra clave exclusivamente.

mock_add_spec(spec, spec_set=False)¶

Agrega una especificación a un objeto simulado. spec puede ser un objeto o una lista de cadenas de caracteres. Sólo los atributos presentes en spec pueden ser obtenidos desde el objeto simulado.

Si spec_set es verdadero, solo los atributos de la especificación pueden ser establecidos.

attach_mock(mock, attribute)¶: Adjunta otro objeto simulado como un atributo de la instancia actual, substituyendo su nombre y su padre. Las llamadas al objeto simulado adjuntado se registrarán en los atributos method_calls y mock_calls del padre.

configure_mock(**kwargs)¶

Establece los atributos del objeto simulado por medio de argumentos por palabra clave.

Los atributos, los valores de retorno y los efectos de colaterales se pueden configurar en los objetos simulados hijos usando la notación de punto estándar y desempaquetando un diccionario en la llamada al método:

>>> mock = Mock()
>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> mock.configure_mock(**attrs)
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError

Lo mismo se puede lograr en la llamada al constructor de los objetos simulados:

>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError

configure_mock() existe con el fin de facilitar la configuración después de que el objeto simulado haya sido creado.

__dir__()¶

Los objetos Mock limitan los resultados de dir(some_mock) a resultados útiles. Para los objetos simulados con una especificación (spec), esto incluye todos los atributos permitidos para el mismo.

Consultar FILTER_DIR para conocer que hace este filtrado y la forma de desactivarlo.

_get_child_mock(**kw)¶

Crea los objetos simulados hijos para los atributos y el valor de retorno. Por defecto los objetos simulados hijos serán del mismo tipo que el padre. Las subclases de Mock pueden redefinir este método para personalizar la forma en la que se construye el objeto simulado hijo.

Para objetos simulados no invocables la variante invocable será utilizada (en lugar de cualquier subclase personalizada).

called¶

Un booleano que representa si el objeto simulado ha sido invocado o no:

>>> mock = Mock(return_value=None)
>>> mock.called
False
>>> mock()
>>> mock.called
True

call_count¶

Un entero que le indica cuántas veces el objeto simulado ha sido invocado:

>>> mock = Mock(return_value=None)
>>> mock.call_count
0
>>> mock()
>>> mock()
>>> mock.call_count
2

return_value¶

Establece este atributo para configurar el valor a retornar cuando se llama al objeto simulado:

>>> mock = Mock()
>>> mock.return_value = 'fish'
>>> mock()
'fish'

El valor de retorno por defecto es otro objeto simulado y se puede configurar de forma habitual:

>>> mock = Mock()
>>> mock.return_value.attribute = sentinel.Attribute
>>> mock.return_value()
<Mock name='mock()()' id='...'>
>>> mock.return_value.assert_called_with()

return_value también se puede establecer directamente en el constructor:

>>> mock = Mock(return_value=3)
>>> mock.return_value
3
>>> mock()
3

side_effect¶

Este atributo puede ser una función a ser llamada cuando se llame al objeto simulado, un iterable o una excepción (clase o instancia) para ser lanzada.

Si pasas una función, será llamada con los mismos argumentos que el objeto simulado y, a menos que la función retorne el singleton DEFAULT, la llamada al objeto simulado retornará lo mismo que retorna la función. En cambio, si la función retorna DEFAULT, entonces el objeto simulado retornará su valor normal (el del atributo return_value).

Si pasas un iterable, se utiliza para obtener un iterador a partir del mismo que debe producir un valor en cada llamada. Este valor puede ser una instancia de la excepción a ser lanzada o un valor a retornar al llamar al objeto simulado (el manejo de DEFAULT es igual que en el caso en el que se pasa una función).

Un ejemplo de un objeto simulado que genera una excepción (para probar el manejo de excepciones de una API):

>>> mock = Mock()
>>> mock.side_effect = Exception('Boom!')
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!

Usando side_effect para retornar una secuencia de valores:

>>> mock = Mock()
>>> mock.side_effect = [3, 2, 1]
>>> mock(), mock(), mock()
(3, 2, 1)

Usando un objeto invocable:

>>> mock = Mock(return_value=3)
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> mock.side_effect = side_effect
>>> mock()
3

side_effect se puede establecer en el constructor. Aquí hay un ejemplo que suma uno al valor del objeto simulado invocado y lo retorna:

>>> side_effect = lambda value: value + 1
>>> mock = Mock(side_effect=side_effect)
>>> mock(3)
4
>>> mock(-8)
-7

Establecer side_effect en None lo desactiva:

>>> m = Mock(side_effect=KeyError, return_value=3)
>>> m()
Traceback (most recent call last):
 ...
KeyError
>>> m.side_effect = None
>>> m()
3

call_args¶

Este atributo es None (si el objeto simulado no ha sido invocado) o los argumentos con los que se llamó por última vez. En este último caso, será una tupla con dos elementos: el primer miembro, que también es accesible a través de la propiedad args, son los argumentos posicionales con los que el objeto simulado se llamó (o una tupla vacía si no se pasó ninguno) y el segundo miembro, que también es accesible mediante la propiedad kwargs, son los argumento por palabra clave pasados (o un diccionario vacío si no se pasó ninguno).

>>> mock = Mock(return_value=None)
>>> print(mock.call_args)
None
>>> mock()
>>> mock.call_args
call()
>>> mock.call_args == ()
True
>>> mock(3, 4)
>>> mock.call_args
call(3, 4)
>>> mock.call_args == ((3, 4),)
True
>>> mock.call_args.args
(3, 4)
>>> mock.call_args.kwargs
{}
>>> mock(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args
call(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args.args
(3, 4, 5)
>>> mock.call_args.kwargs
{'key': 'fish', 'next': 'w00t!'}

El atributo call_args, junto con los miembros de las listas call_args_list, method_calls y mock_calls son objetos call. Estos objetos son tuplas, con la finalidad de que puedan ser desempaquetadas para acceder a los argumentos individuales y hacer aserciones más complejas. Consultar objetos call como tuplas para más información.

Distinto en la versión 3.8: Added args and kwargs properties.

call_args_list¶

Este argumento es una lista de todas las llamadas consecutivas realizadas al objeto simulado (por lo que la longitud de la lista es el número de veces que se ha invocado). Previamente a que se hayan realizado llamadas es una lista vacía. El objeto call se puede utilizar para construir convenientemente las listas de llamadas a comparar con call_args_list.

>>> mock = Mock(return_value=None)
>>> mock()
>>> mock(3, 4)
>>> mock(key='fish', next='w00t!')
>>> mock.call_args_list
[call(), call(3, 4), call(key='fish', next='w00t!')]
>>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)]
>>> mock.call_args_list == expected
True

Los miembros de call_args_list son objetos call. Estos pueden ser desempaquetados como tuplas para acceder a los argumentos individuales. Consultar objetos call como tuplas para más información.

method_calls¶

Igual que realizan un seguimiento de las llamadas hechas a sí mismos, los objetos simulados también realizan un seguimiento a sus métodos y atributos, así como de las llamadas hechas a los mismos:

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.property.method.attribute()
<Mock name='mock.property.method.attribute()' id='...'>
>>> mock.method_calls
[call.method(), call.property.method.attribute()]

Los miembros de method_calls son objetos call. Estos pueden ser desempaquetados como tuplas para acceder a los atributos individuales. Consultar objetos call como tuplas para más información.

mock_calls¶

mock_calls registra todas las llamadas al objeto simulado, sus métodos, métodos mágicos y objetos simulados del valor de retorno.

>>> mock = MagicMock()
>>> result = mock(1, 2, 3)
>>> mock.first(a=3)
<MagicMock name='mock.first()' id='...'>
>>> mock.second()
<MagicMock name='mock.second()' id='...'>
>>> int(mock)
1
>>> result(1)
<MagicMock name='mock()()' id='...'>
>>> expected = [call(1, 2, 3), call.first(a=3), call.second(),
... call.__int__(), call()(1)]
>>> mock.mock_calls == expected
True

Los miembros de mock_calls son objetos call. Estos pueden ser desempaquetados como tuplas para acceder a los argumentos individuales. Consultar objetos call como tuplas para más información.

Nota

La forma como se registra el atributo mock_calls implica que cuando se realizan llamadas anidadas, los parámetros de las llamadas previas no se registran, por lo que siempre resultan iguales al comparar:

>>> mock = MagicMock()
>>> mock.top(a=3).bottom()
<MagicMock name='mock.top().bottom()' id='...'>
>>> mock.mock_calls
[call.top(a=3), call.top().bottom()]
>>> mock.mock_calls[-1] == call.top(a=-1).bottom()
True

__class__¶

Normalmente, el atributo de un objeto __class__ retornará su tipo. Para un objeto simulado con un spec, __class__ retorna la clase especificada en su lugar. Esto permite a los objetos simulados pasar los test de isinstance() para el objeto que están reemplazando / enmascarando:

>>> mock = Mock(spec=3)
>>> isinstance(mock, int)
True

El atributo __class__ es asignable, esto permite al objeto simulado pasar una verificación de isinstance() sin verse forzado a utilizar una especificación:

>>> mock = Mock()
>>> mock.__class__ = dict
>>> isinstance(mock, dict)
True

class unittest.mock.NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs)¶: Una versión no invocable de Mock. Los parámetros del constructor tienen el mismo significado que en Mock, con la excepción de return_value y side_effect que no tienen sentido en un objeto simulado no invocable.

Los objetos simulados que usan una clase o una instancia como spec o spec_set son capaces de pasar los test de isinstance():

>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
True
>>> mock = Mock(spec_set=SomeClass())
>>> isinstance(mock, SomeClass)
True

Las clases Mock tienen soporte para simular los métodos mágicos. Consultar la sección dedicada a los métodos mágicos para ver los detalles.

Las clases simuladas y los decoradores patch() aceptan todas argumentos por palabra clave arbitrarios para la configuración. En los decoradores patch() los argumentos por palabra clave se pasan al constructor del objeto simulado creado. Estos argumentos se usan para configurar los atributos del propio objeto simulado:

>>> m = MagicMock(attribute=3, other='fish')
>>> m.attribute
3
>>> m.other
'fish'

Tanto el valor de retorno como el efecto colateral del objeto simulado pueden ser establecidos de la misma manera, mediante notación de punto. En cambio, si se quieren establecer mediante el constructor, dado que no se puede utilizar notación de punto directamente en una llamada, se tiene que crear un diccionario y desempaquetarlo usando **:

>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError

Un objeto simulado invocable que fue creado con un spec (o un spec_set) introspeccionará la firma del objeto de la especificación en el momento de emparejar las llamadas al objeto simulado. Esto le permite hacer coincidir sus argumentos con los argumentos de la llamada real, independientemente de si se pasaron por posición o por nombre:

>>> def f(a, b, c): pass
...
>>> mock = Mock(spec=f)
>>> mock(1, 2, c=3)
<Mock name='mock()' id='140161580456576'>
>>> mock.assert_called_with(1, 2, 3)
>>> mock.assert_called_with(a=1, b=2, c=3)

Esto se aplica a assert_called_with(), assert_called_once_with(), assert_has_calls() y assert_any_call(). Cuando se hace uso de Autoespecificación, también se aplicará a las llamadas a los métodos del objeto simulado.

Distinto en la versión 3.4: Se añadió introspección de firma en objetos simulados especificados y autoespecificados.

class unittest.mock.PropertyMock(*args, **kwargs)¶

Un objeto simulado destinado a ser utilizado en una clase como una propiedad, u otro descriptor. La clase PropertyMock proporciona los métodos __get__() y __set__(), por lo que puedes especificar un valor de retorno para cuando su valor es requerido.

La obtención de una instancia PropertyMock desde un objeto ocasiona una llamada al objeto simulado, sin argumentos. Establecer su valor también llama al objeto simulado, con el valor a establecer como argumento.

>>> class Foo:
...     @property
...     def foo(self):
...         return 'something'
...     @foo.setter
...     def foo(self, value):
...         pass
...
>>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo:
...     mock_foo.return_value = 'mockity-mock'
...     this_foo = Foo()
...     print(this_foo.foo)
...     this_foo.foo = 6
...
mockity-mock
>>> mock_foo.mock_calls
[call(), call(6)]

Debido a la forma en que se almacenan los atributos simulados, no es posible conectar directamente un PropertyMock a un objeto simulado. En su lugar se puede conectar al tipo (type) del objeto simulado:

>>> m = MagicMock()
>>> p = PropertyMock(return_value=3)
>>> type(m).foo = p
>>> m.foo
3
>>> p.assert_called_once_with()

class unittest.mock.AsyncMock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)¶

An asynchronous version of MagicMock. The AsyncMock object will behave so the object is recognized as an async function, and the result of a call is an awaitable.

>>> mock = AsyncMock()
>>> asyncio.iscoroutinefunction(mock)
True
>>> inspect.isawaitable(mock())  
True

El resultado de mock() es una función asíncrona que proporcionará el resultado de side_effect o de return_value después de haber sido aguardada:

si side_effect es una función, la función asíncrona retornará el resultado de esa función,
si side_effect es una excepción, la función asíncrona lanzará la excepción,
si side_effect es un iterable, la función asíncrona retornará el siguiente valor del iterable, sin embargo, si se agota la secuencia de resultados, se lanza una excepción StopAsyncIteration inmediatamente,
si side_effect no está definido, la función asíncrona retornará el valor definido por return_value, por lo tanto, la función asíncrona retorna un nuevo objeto AsyncMock por defecto.

Establecer el argumento spec de un objeto Mock o MagicMock en una función asíncrona resultará en que un objeto corrutina será retornado después de la llamada al objeto.

>>> async def async_func(): pass
...
>>> mock = MagicMock(async_func)
>>> mock
<MagicMock spec='function' id='...'>
>>> mock()  
<coroutine object AsyncMockMixin._mock_call at ...>

Establecer el argumento spec de un objeto Mock, MagicMock o AsyncMock en una clase que tiene simultáneamente funciones asíncronas y síncronas hará que se detecten automáticamente las funciones sincrónicas y las establecerá como MagicMock (si el objeto simulado padre es AsyncMock o MagicMock) o Mock (si el objeto simulado padre es Mock) . Todas las funciones asíncronas serán AsyncMock.

>>> class ExampleClass:
...     def sync_foo():
...         pass
...     async def async_foo():
...         pass
...
>>> a_mock = AsyncMock(ExampleClass)
>>> a_mock.sync_foo
<MagicMock name='mock.sync_foo' id='...'>
>>> a_mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>
>>> mock = Mock(ExampleClass)
>>> mock.sync_foo
<Mock name='mock.sync_foo' id='...'>
>>> mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>

Nuevo en la versión 3.8.

assert_awaited()¶

Aserta si el objeto simulado fue aguardado al menos una vez. Ten en cuenta que, independientemente del objeto que ha sido invocado, la palabra clave await debe ser utilizada:

>>> mock = AsyncMock()
>>> async def main(coroutine_mock):
...     await coroutine_mock
...
>>> coroutine_mock = mock()
>>> mock.called
True
>>> mock.assert_awaited()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited.
>>> asyncio.run(main(coroutine_mock))
>>> mock.assert_awaited()

assert_awaited_once()¶

Aserta si el objeto simulado fue aguardado exactamente una vez.

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.assert_awaited_once()
>>> asyncio.run(main())
>>> mock.method.assert_awaited_once()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited once. Awaited 2 times.

assert_awaited_with(*args, **kwargs)¶

Aserta si el último aguardo (await) fue con los argumentos especificados.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_with('foo', bar='bar')
>>> mock.assert_awaited_with('other')
Traceback (most recent call last):
...
AssertionError: expected call not found.
Expected: mock('other')
Actual: mock('foo', bar='bar')

assert_awaited_once_with(*args, **kwargs)¶

Aserta si que el objeto simulado se ha aguardado exactamente una vez y con los argumentos especificados.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_once_with('foo', bar='bar')
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_once_with('foo', bar='bar')
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited once. Awaited 2 times.

assert_any_await(*args, **kwargs)¶

Aserta si el objeto simulado nunca se ha aguardado con los argumentos especificados.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> asyncio.run(main('hello'))
>>> mock.assert_any_await('foo', bar='bar')
>>> mock.assert_any_await('other')
Traceback (most recent call last):
...
AssertionError: mock('other') await not found

assert_has_awaits(calls, any_order=False)¶

Aserta si el objeto simulado ha sido aguardado con las llamadas especificadas. Para comprobar los aguardos (awaits) se utiliza la lista await_args_list.

Si any_order es falso, los aguardos (awaits) deben ser secuenciales. No puede haber llamadas adicionales antes o después de los aguardos especificados.

Si any_order es verdadero, entonces los aguardos (awaits) pueden estar en cualquier orden, pero deben aparecer todos en await_args_list.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> calls = [call("foo"), call("bar")]
>>> mock.assert_has_awaits(calls)
Traceback (most recent call last):
...
AssertionError: Awaits not found.
Expected: [call('foo'), call('bar')]
Actual: []
>>> asyncio.run(main('foo'))
>>> asyncio.run(main('bar'))
>>> mock.assert_has_awaits(calls)

assert_not_awaited()¶

Aserta si el objeto simulado nunca ha sido aguardado.

>>> mock = AsyncMock()
>>> mock.assert_not_awaited()

reset_mock(*args, **kwargs)¶: Consultar Mock.reset_mock(). Además, también establece await_count a 0, await_args a None y borra await_args_list.

await_count¶

Un registro entero de cuántas veces se ha aguardado el objeto simulado.

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.await_count
1
>>> asyncio.run(main())
>>> mock.await_count
2

await_args¶

Este atributo es None (si el objeto simulado no se ha aguardado) o los argumentos con los que fue aguardado la última vez. Su funcionamiento es idéntico al de Mock.call_args.

>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*args)
...
>>> mock.await_args
>>> asyncio.run(main('foo'))
>>> mock.await_args
call('foo')
>>> asyncio.run(main('bar'))
>>> mock.await_args
call('bar')

await_args_list¶

Es una lista de todas los aguardos (awaits) realizados en el objeto simulado de forma secuencial (por lo que la longitud de la lista es el número de veces que se ha aguardado el objeto). Si no se han realizado aguardos previos, es una lista vacía.

>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*args)
...
>>> mock.await_args_list
[]
>>> asyncio.run(main('foo'))
>>> mock.await_args_list
[call('foo')]
>>> asyncio.run(main('bar'))
>>> mock.await_args_list
[call('foo'), call('bar')]

Llamar a los objetos simulados¶

Los objetos Mock son invocables. La llamada a uno retornará el valor establecido en el atributo return_value. El valor de retorno por defecto es un nuevo objeto Mock, el cual se crea la primera vez que se accede al valor de retorno (ya sea explícitamente o llamando al objeto Mock). Una vez creado, se almacena y el mismo objeto es retornado cada vez que se solicita.

Las llamadas realizadas al objeto serán registradas en los atributos call_args y call_args_list.

Si side_effect se establece, será invocado después de que la llamada haya sido registrada, por lo que la llamada se registra aunque side_effect lance una excepción.

La forma más sencilla de hacer que un objeto simulado lance de una excepción cuando sea invocado es establecer su atributo side_effect como una clase o instancia de excepción:

>>> m = MagicMock(side_effect=IndexError)
>>> m(1, 2, 3)
Traceback (most recent call last):
  ...
IndexError
>>> m.mock_calls
[call(1, 2, 3)]
>>> m.side_effect = KeyError('Bang!')
>>> m('two', 'three', 'four')
Traceback (most recent call last):
  ...
KeyError: 'Bang!'
>>> m.mock_calls
[call(1, 2, 3), call('two', 'three', 'four')]

Si side_effect es una función, la llamada al objeto simulado retornará lo que sea que esta función retorne. La función establecida en side_effect se llama con los mismos argumentos con los que el objeto simulado ha sido invocado. Esto te permite variar el valor de retorno de la llamada dinámicamente, en función de la entrada:

>>> def side_effect(value):
...     return value + 1
...
>>> m = MagicMock(side_effect=side_effect)
>>> m(1)
2
>>> m(2)
3
>>> m.mock_calls
[call(1), call(2)]

Si se desea que el objeto simulado aún retorne el valor por defecto (un nuevo objeto simulado), o cualquier valor de retorno establecido, entonces existen dos maneras de proceder. Se puede retornar tanto el atributo mock.return_value como DEFAULT desde side_effect:

>>> m = MagicMock()
>>> def side_effect(*args, **kwargs):
...     return m.return_value
...
>>> m.side_effect = side_effect
>>> m.return_value = 3
>>> m()
3
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> m.side_effect = side_effect
>>> m()
3

Para eliminar un side_effect, volviendo al comportamiento predeterminado, establece el atributo side_effect en None:

>>> m = MagicMock(return_value=6)
>>> def side_effect(*args, **kwargs):
...     return 3
...
>>> m.side_effect = side_effect
>>> m()
3
>>> m.side_effect = None
>>> m()
6

El atributo side_effect también puede ser cualquier objeto iterable. En este caso, las llamadas repetidas al objeto simulado irán retornando valores del iterable (hasta que el iterable se agote, momento en el que se lanza una excepción StopIteration):

>>> m = MagicMock(side_effect=[1, 2, 3])
>>> m()
1
>>> m()
2
>>> m()
3
>>> m()
Traceback (most recent call last):
  ...
StopIteration

Si cualquier miembro del iterable es una excepción, se lanzará en lugar de retornarse:

>>> iterable = (33, ValueError, 66)
>>> m = MagicMock(side_effect=iterable)
>>> m()
33
>>> m()
Traceback (most recent call last):
 ...
ValueError
>>> m()
66

Eliminar atributos¶

Los objetos simulados crean atributos en demanda. Esto les permite hacerse pasar por objetos de cualquier tipo.

Es posible que desees que un objeto simulado retorne False al llamar a hasattr(), o que lance una excepción AttributeError cuando se intenta obtener un atributo. Puedes hacer todo esto proporcionando un objeto adecuado al atributo spec del objeto simulado, pero no siempre es conveniente.

Puedes «bloquear» atributos eliminándolos. Una vez eliminado, el acceso a un atributo lanzará una excepción AttributeError.

>>> mock = MagicMock()
>>> hasattr(mock, 'm')
True
>>> del mock.m
>>> hasattr(mock, 'm')
False
>>> del mock.f
>>> mock.f
Traceback (most recent call last):
    ...
AttributeError: f

Los nombres de los objetos simulados y el atributo name¶

Dado que «name» es un argumento para el constructor de la clase Mock, si quieres que tu objeto simulado tenga un atributo «name», no puedes simplemente pasarlo al constructor en tiempo de creación. Hay dos alternativas. Una opción es usar el método configure_mock():

>>> mock = MagicMock()
>>> mock.configure_mock(name='my_name')
>>> mock.name
'my_name'

Una opción más sencilla es simplemente establecer el atributo «name» después de la creación del objeto simulado:

>>> mock = MagicMock()
>>> mock.name = "foo"

Adjuntar objetos simulados como atributos¶

Cuando se adjunta un objeto simulado como un atributo de otro objeto simulado (o como su valor de retorno) se convierte en un «hijo» del mismo. Las llamadas a los hijos se registran en los atributos method_calls y mock_calls del padre. Esto es útil para configurar objetos simulados hijos para después adjuntarlos al padre, o para adjuntar objetos simulados a un padre que se encargará de registrar todas las llamadas a los hijos, permitiéndote hacer aserciones sobre el orden de las llamadas entre objetos simulados:

>>> parent = MagicMock()
>>> child1 = MagicMock(return_value=None)
>>> child2 = MagicMock(return_value=None)
>>> parent.child1 = child1
>>> parent.child2 = child2
>>> child1(1)
>>> child2(2)
>>> parent.mock_calls
[call.child1(1), call.child2(2)]

La excepción a lo anterior es si el objeto simulado tiene un nombre. Esto te permite evitar el comportamiento de «parentesco» explicado previamente, si por alguna razón no deseas que suceda.

>>> mock = MagicMock()
>>> not_a_child = MagicMock(name='not-a-child')
>>> mock.attribute = not_a_child
>>> mock.attribute()
<MagicMock name='not-a-child()' id='...'>
>>> mock.mock_calls
[]

Los objetos simulados creados automáticamente por la función patch() también reciben nombres automáticamente. Para adjuntar un objeto simulado con nombre a un padre debes utilizar el método attach_mock():

>>> thing1 = object()
>>> thing2 = object()
>>> parent = MagicMock()
>>> with patch('__main__.thing1', return_value=None) as child1:
...     with patch('__main__.thing2', return_value=None) as child2:
...         parent.attach_mock(child1, 'child1')
...         parent.attach_mock(child2, 'child2')
...         child1('one')
...         child2('two')
...
>>> parent.mock_calls
[call.child1('one'), call.child2('two')]

1: Las únicas excepciones son los métodos y atributos mágicos (aquellos que tienen doble subrayado al principio y al final). Mock no los crea automáticamente, sino que lanza una excepción AttributeError. Esto se debe a que el intérprete a menudo solicitará implícitamente estos métodos y terminaría muy confundido si obtiene un nuevo objeto Mock cuando espera un método mágico. Si necesitas soporte para métodos mágicos, consulta métodos mágicos.

Parcheadores¶

Los decoradores patch se utilizan para parchear los objetos sólo dentro del ámbito de la función que decoran. Se encargan automáticamente de desparchear una vez terminada la prueba, incluso si se lanzan excepciones. Todas estas funciones también se pueden utilizar con declaraciones o como decoradores de clase.

patch¶

Nota

The key is to do the patching in the right namespace. See the section where to patch.

unittest.mock.patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)¶

patch() actúa como decorador de función, decorador de clase o como gestor de contexto. Ya sea en el interior del cuerpo de una función o dentro de una declaración with, target es parcheado con un objeto new. Cuando la función / declaración with termina su ejecución el parche se deshace automáticamente.

Si se omite new, entonces el objetivo se reemplaza por un objeto AsyncMock si el objeto parcheado es una función asíncrona, o con un objeto MagicMock en caso contrario. Si se utiliza patch() como decorador y se omite new, el objeto simulado creado se pasa como un argumento adicional a la función decorada. Si se utiliza patch() como un gestor de contexto, el objeto simulado creado es retornado por el gestor de contexto.

target debe ser una cadena de la forma 'paquete.modulo.NombreDeLaClase'. target es importado y el objeto especificado reemplazado por el objeto new, por lo que target debe ser importable desde el entorno desde el cual estás llamando a patch(). Hay que tener presente que target es importado cuando se ejecuta la función decorada, no en tiempo de decoración.

Los argumentos spec y spec_set se pasan a MagicMock si patch está creando automáticamente uno para ti.

Además, puedes pasar spec=True o spec_set=True, lo que causa que patch pase el objeto que está siendo simulado como el objeto spec/spec_set.

new_callable te permite especificar una clase diferente, o un objeto invocable, que será invocada para crear el objeto new. Por defecto se utiliza AsyncMock para las funciones asíncronas y MagicMock para el resto.

Una variante más poderosa de spec es autospec. Si estableces autospec=True el objeto simulado se creará con una especificación del objeto que está siendo reemplazado. Todos los atributos del objeto simulado también tendrán la especificación del atributo correspondiente del objeto que está siendo reemplazado. Los argumentos de los métodos y funciones simulados son comprobados y se lanzará una excepción TypeError si se les llama con la firma incorrecta. Para los objetos simulados que sustituyen a una clase, su valor de retorno (la “instancia”) tendrá la misma especificación que la clase. Consultar la función create_autospec() y Autoespecificación para más detalles.

En lugar de autospec=True, puedes pasar autospec=some_object para utilizar un objeto arbitrario como especificación en lugar del objeto reemplazado.

Por defecto, patch() fallará al intentar reemplazar atributos que no existen. Si pasas create=True y no existe el atributo, patch crea el atributo cuando la función se llama y lo elimina de nuevo en cuanto termina de ejecutarse . Esto es útil para implementar pruebas para atributos que tu código de producción crea en tiempo de ejecución. Está desactivado por defecto, ya que puede ser peligroso. ¡Al activarlo se pueden implementar pruebas que validen APIs que en realidad no existen!

Nota

Distinto en la versión 3.5: Si estás parcheando objetos incorporados (builtins) en un módulo, no es necesario pasar create=True, ya que en este caso se agrega de forma predeterminada.

Patch puede ser usado como un decorador de la clase TestCase. Funciona decorando cada uno de los métodos de prueba presentes en la clase. Esto reduce el código repetitivo cuando tus métodos de prueba comparten un conjunto de parcheo común. patch() encuentra las pruebas mediante la búsqueda de métodos cuyos nombres comienzan con patch.TEST_PREFIX. Por defecto es 'test', que coincide con la forma en que unittest busca las pruebas. Se puede especificar un prefijo alternativo estableciendo un nuevo valor para el atributo patch.TEST_PREFIX.

Patch puede ser usado como un gestor de contexto, con la declaración with. En este caso el parcheo se aplica al bloque sangrado inmediatamente después de la declaración with. Si utilizas «as», el objeto parcheado será enlazado al nombre especificado después de «as»; muy útil si patch() está creando un objeto simulado automáticamente.

patch() takes arbitrary keyword arguments. These will be passed to AsyncMock if the patched object is asynchronous, to MagicMock otherwise or to new_callable if specified.

patch.dict(...), patch.multiple(...) y patch.object(...) están disponibles para casos de uso alternativos.

patch() como decorador de función, crea el objeto simulado por ti y lo pasa a la función decorada:

>>> @patch('__main__.SomeClass')
... def function(normal_argument, mock_class):
...     print(mock_class is SomeClass)
...
>>> function(None)
True

Parchear una clase sustituye a la clase por una instancia de MagicMock. Si la clase se instancia en el código bajo prueba, el atributo return_value del objeto simulado será el utilizado.

Si la clase se instancia en múltiples ocasiones, puedes utilizar el atributo side_effect para retornar un nuevo objeto simulado cada vez. O también puedes establecer return_value para que sea lo que tu quieras.

Para configurar valores de retorno de métodos en instancias de la clase parcheada debes hacer uso del atributo return_value. Por ejemplo:

>>> class Class:
...     def method(self):
...         pass
...
>>> with patch('__main__.Class') as MockClass:
...     instance = MockClass.return_value
...     instance.method.return_value = 'foo'
...     assert Class() is instance
...     assert Class().method() == 'foo'
...

Si utilizas spec o spec_set y patch() está reemplazando una clase, el valor de retorno del objeto simulado creado tendrá las mismas especificaciones:

>>> Original = Class
>>> patcher = patch('__main__.Class', spec=True)
>>> MockClass = patcher.start()
>>> instance = MockClass()
>>> assert isinstance(instance, Original)
>>> patcher.stop()

El argumento new_callable es útil cuando deseas utilizar una clase por defecto alternativa a MagicMock para el objeto simulado creado. Por ejemplo, si quieres que se use una clase NonCallableMock por defecto:

>>> thing = object()
>>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
...     assert thing is mock_thing
...     thing()
...
Traceback (most recent call last):
  ...
TypeError: 'NonCallableMock' object is not callable

Otro caso de uso podría ser la sustitución de un objeto por una instancia de io.StringIO:

>>> from io import StringIO
>>> def foo():
...     print('Something')
...
>>> @patch('sys.stdout', new_callable=StringIO)
... def test(mock_stdout):
...     foo()
...     assert mock_stdout.getvalue() == 'Something\n'
...
>>> test()

Cuando patch() crea un objeto simulado para ti, a menudo lo primero que tienes que hacer es configurar el objeto simulado recién creado. Parte de la configuración se puede hacer en la propia llamada a patch. Cualquier palabra clave arbitraria que pases a la llamada será utilizada para establecer los atributos del objeto simulado creado:

>>> patcher = patch('__main__.thing', first='one', second='two')
>>> mock_thing = patcher.start()
>>> mock_thing.first
'one'
>>> mock_thing.second
'two'

Los atributos de los objetos simulados hijos, como return_value y side_effect, también puede ser configurados en la llamada, dado que los objetos simulados hijos son atributos en si mismos del objeto simulado padre creado. Eso si, estos no son sintácticamente válidos para ser pasados directamente como argumentos por palabras clave a la función patch, pero un diccionario con ellos como claves si que puede ser expandido en una llama a patch() usando **:

>>> config = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> patcher = patch('__main__.thing', **config)
>>> mock_thing = patcher.start()
>>> mock_thing.method()
3
>>> mock_thing.other()
Traceback (most recent call last):
  ...
KeyError

Por defecto, el intento de parchear una función en un módulo (o un método o atributo en una clase) que no existe fallará lanzando una excepción AttributeError:

>>> @patch('sys.non_existing_attribute', 42)
... def test():
...     assert sys.non_existing_attribute == 42
...
>>> test()
Traceback (most recent call last):
  ...
AttributeError: <module 'sys' (built-in)> does not have the attribute 'non_existing_attribute'

pero añadir create=True en la llamada a patch() hará que el ejemplo previo funcione como se esperaba:

>>> @patch('sys.non_existing_attribute', 42, create=True)
... def test(mock_stdout):
...     assert sys.non_existing_attribute == 42
...
>>> test()

Distinto en la versión 3.8: patch() ahora retorna una instancia de AsyncMock si el objetivo es una función asíncrona.

patch.object¶

patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)¶

parchea el miembro attribute invocado de un objeto target con un objeto simulado.

patch.object() se puede utilizar como un decorador, decorador de clase o un gestor de contexto. Los argumentos new, spec, create, spec_set, autospec y new_callable tienen el mismo significado que en la función patch(). Al igual que patch(), patch.object() toma argumentos por palabras clave arbitrarios para la configuración del objeto simulado que crea.

Cuando se utiliza como un decorador de clase patch.object() se rige por patch.TEST_PREFIX a la hora de elegir los métodos a envolver.

Puedes llamar a patch.object() con tres argumentos o con dos argumentos. La forma de tres argumento toma el objeto a parchear, el nombre del atributo y el objeto con el que reemplazar el atributo.

Al llamar usando la variante de dos argumento se omite el objeto de sustitución, por lo tanto se crea un objeto simulado automáticamente y se pasa como argumento adicional a la función decorada:

>>> @patch.object(SomeClass, 'class_method')
... def test(mock_method):
...     SomeClass.class_method(3)
...     mock_method.assert_called_with(3)
...
>>> test()

spec, create y el resto de argumentos de patch.object() tienen el mismo significado que en la función patch().

patch.dict¶

patch.dict(in_dict, values=(), clear=False, **kwargs)¶

Parchea un diccionario o un objeto similar a un diccionario y posteriormente lo restaura a su estado original una vez terminada la prueba.

in_dict puede ser un diccionario o un contenedor similar a uno. Si se trata de un objeto similar a un diccionario, debe soportar como mínimo el establecimiento, la obtención y la eliminación de elementos, además de permitir la iteración sobre las claves.

in_dict también puede ser una cadena que especifique el nombre del diccionario a parchear, el nombre es usado para obtener el diccionario mediante importación.

values puede ser otro diccionario con valores para ser añadidos al diccionario. values también puede ser un iterable de parejas (clave, valor).

Si clear es verdadero, el contenido del diccionario se borrará antes de establecer los nuevos valores.

La función patch.dict() también puede ser invocada con argumentos por palabra clave arbitrarios para establecer los valores en el diccionario.

Distinto en la versión 3.8: La función patch.dict() ahora retorna el diccionario parcheado cuando se utiliza como gestor de contexto.

patch.dict() se puede utilizar como gestor de contexto, decorador o decorador de clase:

>>> foo = {}
>>> @patch.dict(foo, {'newkey': 'newvalue'})
... def test():
...     assert foo == {'newkey': 'newvalue'}
>>> test()
>>> assert foo == {}

Cuando se utiliza patch.dict() como decorador de clase, se rige por patch.TEST_PREFIX (por defecto 'test') a la hora de elegir qué métodos envolver:

>>> import os
>>> import unittest
>>> from unittest.mock import patch
>>> @patch.dict('os.environ', {'newkey': 'newvalue'})
... class TestSample(unittest.TestCase):
...     def test_sample(self):
...         self.assertEqual(os.environ['newkey'], 'newvalue')

Si deseas utilizar un prefijo diferente para tu prueba, puede informar a los parcheadores del nuevo prefijo a usar estableciendo patch.TEST_PREFIX. Para más detalles sobre cómo cambiar el valor del atributo consultar TEST_PREFIX.

patch.dict() puede utilizarse para agregar miembros a un diccionario, o simplemente para dejar que una prueba modifique un diccionario y asegurarte de que el diccionario será restablecido cuando finalice la misma.

>>> foo = {}
>>> with patch.dict(foo, {'newkey': 'newvalue'}) as patched_foo:
...     assert foo == {'newkey': 'newvalue'}
...     assert patched_foo == {'newkey': 'newvalue'}
...     # You can add, update or delete keys of foo (or patched_foo, it's the same dict)
...     patched_foo['spam'] = 'eggs'
...
>>> assert foo == {}
>>> assert patched_foo == {}

>>> import os
>>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
...     print(os.environ['newkey'])
...
newvalue
>>> assert 'newkey' not in os.environ

Se pueden utilizar argumentos por palabra clave en la llamada a patch.dict() para establecer valores en el diccionario:

>>> mymodule = MagicMock()
>>> mymodule.function.return_value = 'fish'
>>> with patch.dict('sys.modules', mymodule=mymodule):
...     import mymodule
...     mymodule.function('some', 'args')
...
'fish'

patch.dict() se puede utilizar con objetos similares a un diccionario, que no son realmente diccionarios. Estos objetos como mínimo deben permitir obtener, establecer y borrar elementos, además de soportar la iteración o la prueba de pertenencia. Dichas funcionalidades se corresponden a los métodos mágicos __getitem__(), __setitem__(), __delitem__() e __iter__() o __contains__().

>>> class Container:
...     def __init__(self):
...         self.values = {}
...     def __getitem__(self, name):
...         return self.values[name]
...     def __setitem__(self, name, value):
...         self.values[name] = value
...     def __delitem__(self, name):
...         del self.values[name]
...     def __iter__(self):
...         return iter(self.values)
...
>>> thing = Container()
>>> thing['one'] = 1
>>> with patch.dict(thing, one=2, two=3):
...     assert thing['one'] == 2
...     assert thing['two'] == 3
...
>>> assert thing['one'] == 1
>>> assert list(thing) == ['one']

patch.multiple¶

patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)¶

Realiza múltiples parches en una sola llamada. Se toma el objeto a ser parcheado (ya sea como un objeto o una cadena de caracteres con el nombre del mismo para obtener el objeto mediante importación) y los argumentos por palabras clave para los parches:

with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
    ...

Usa DEFAULT como valor si deseas que la función patch.multiple() cree objetos simulados automáticamente por ti. En este caso, los objetos simulados creados son pasados a la función decorada mediante palabra clave y se retorna un diccionario cuando patch.multiple() se utiliza como gestor de contexto.

La función patch.multiple() se puede utilizar como un decorador, decorador de clase o como gestor de contexto. La argumentos spec, spec_set, create, autospec y new_callable tienen el mismo significado que en la función patch(). Estos argumentos se aplicarán a todos los parches realizados por patch.multiple().

Cuando se utiliza como decorador de clase, patch.multiple() se rige por patch.TEST_PREFIX a la hora de elegir qué métodos envolver.

Si deseas que patch.multiple() cree objetos simulados automáticamente por ti, puedes utilizar DEFAULT como valor. Si utilizas patch.multiple() como decorador, entonces los objetos simulados creados se pasan a la función decorada por palabra clave:

>>> thing = object()
>>> other = object()

>>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(thing, other):
...     assert isinstance(thing, MagicMock)
...     assert isinstance(other, MagicMock)
...
>>> test_function()

patch.multiple() se puede anidar junto a otros decoradores patch, pero los argumentos pasados por palabra clave se deben agregar después de cualquier argumento estándar creado por patch():

>>> @patch('sys.exit')
... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(mock_exit, other, thing):
...     assert 'other' in repr(other)
...     assert 'thing' in repr(thing)
...     assert 'exit' in repr(mock_exit)
...
>>> test_function()

Si patch.multiple() se utiliza como un gestor de contexto, el valor retornado por el mismo es un diccionario en el que los objetos simulados creados son almacenados, usando sus nombres como claves:

>>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
...     assert 'other' in repr(values['other'])
...     assert 'thing' in repr(values['thing'])
...     assert values['thing'] is thing
...     assert values['other'] is other
...

Métodos start y stop de patch¶

Todos los parcheadores tienen los métodos start() y stop(). Esto facilita parchear en los métodos setUp o cuando deseas hacer múltiples parches sin usar decoradores anidados o declaraciones with.

Para utilizar estos métodos, llama a patch(), patch.object() o patch.dict() como haces normalmente y mantén una referencia al objeto patcher retornado. A continuación, puedes llamar al método start() para aplicar el parche y a stop() para deshacerlo.

Si estás utilizando patch() para crear un objeto simulado automáticamente, este será retornado por la llamada a patcher.start:

>>> patcher = patch('package.module.ClassName')
>>> from package import module
>>> original = module.ClassName
>>> new_mock = patcher.start()
>>> assert module.ClassName is not original
>>> assert module.ClassName is new_mock
>>> patcher.stop()
>>> assert module.ClassName is original
>>> assert module.ClassName is not new_mock

Un uso típico de esto podría ser realizar múltiples parches en el método setUp de un TestCase:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher1 = patch('package.module.Class1')
...         self.patcher2 = patch('package.module.Class2')
...         self.MockClass1 = self.patcher1.start()
...         self.MockClass2 = self.patcher2.start()
...
...     def tearDown(self):
...         self.patcher1.stop()
...         self.patcher2.stop()
...
...     def test_something(self):
...         assert package.module.Class1 is self.MockClass1
...         assert package.module.Class2 is self.MockClass2
...
>>> MyTest('test_something').run()

Prudencia

Si se utiliza esta técnica debes asegurarte de que el parcheo está «sin aplicar» llamando a stop. Esto puede ser más complicado de lo que parece, ya que si se produce una excepción en el setUp no se llama a tearDown a continuación. unittest.TestCase.addCleanup() hace que esto sea más fácil:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         patcher = patch('package.module.Class')
...         self.MockClass = patcher.start()
...         self.addCleanup(patcher.stop)
...
...     def test_something(self):
...         assert package.module.Class is self.MockClass
...

Como beneficio adicional, ya no es necesario mantener una referencia al objeto patcher.

También es posible detener todos los parches que han sido iniciados usando patch.stopall().

patch.stopall()¶: Detiene todos los parches activos. Sólo se detienen parches iniciados con start.

Parchear objetos incorporados (builtins)¶

Puedes parchear cualquier objeto incorporado dentro de un módulo. El siguiente ejemplo parchea la función incorporada ord():

>>> @patch('__main__.ord')
... def test(mock_ord):
...     mock_ord.return_value = 101
...     print(ord('c'))
...
>>> test()
101

TEST_PREFIX¶

Todos los parcheadores se puede utilizar como decoradores de clase. Cuando se usan de esta forma, todos los métodos a probar en la clase son envueltos. Los parcheadores reconocen los métodos que comienzan con 'test' como métodos a probar. Esta es la misma forma que la clase unittest.TestLoader usa para encontrar métodos de prueba por defecto.

Cabe la posibilidad de que desees utilizar un prefijo diferente para las pruebas. Puedes informar a los parcheadores del cambio de prefijo estableciendo el atributo patch.TEST_PREFIX:

>>> patch.TEST_PREFIX = 'foo'
>>> value = 3
>>>
>>> @patch('__main__.value', 'not three')
... class Thing:
...     def foo_one(self):
...         print(value)
...     def foo_two(self):
...         print(value)
...
>>>
>>> Thing().foo_one()
not three
>>> Thing().foo_two()
not three
>>> value
3

Anidando decoradores patch¶

Si deseas aplicar múltiples parches, solo tienes que apilar los decoradores.

Puede apilar múltiples decoradores patch usando el siguiente patrón:

>>> @patch.object(SomeClass, 'class_method')
... @patch.object(SomeClass, 'static_method')
... def test(mock1, mock2):
...     assert SomeClass.static_method is mock1
...     assert SomeClass.class_method is mock2
...     SomeClass.static_method('foo')
...     SomeClass.class_method('bar')
...     return mock1, mock2
...
>>> mock1, mock2 = test()
>>> mock1.assert_called_once_with('foo')
>>> mock2.assert_called_once_with('bar')

Ten en cuenta que los decoradores se aplican desde abajo hacia arriba. Esta es la manera estándar de Python para aplicar decoradores. El orden en el que los objetos simulados generados se pasan a la función de prueba coincide con este orden.

Dónde parchear¶

patch() funciona cambiando (temporalmente) el objeto al que apunta name con otro. Puede haber muchos nombres apuntando a cualquier objeto individual, por lo que para que el parcheo funcione, debes asegurarte de parchear el nombre utilizado para el objeto por el sistema concreto bajo prueba.

El principio básico es parchear donde un objeto es buscado, que no es necesariamente el mismo lugar donde está definido. Un par de ejemplos ayudarán a aclarar esto.

Imaginemos que tenemos un proyecto, que queremos probar, con la siguiente estructura:

a.py
    -> Defines SomeClass

b.py
    -> from a import SomeClass
    -> some_function instantiates SomeClass

Ahora queremos probar some_function, pero queremos simular SomeClass utilizando patch(). El problema es que cuando importamos el módulo b, lo cual tenemos que hacer obligatoriamente, se importa SomeClass del módulo a. Si utilizamos patch() para simular a.SomeClass, no tendrá ningún efecto en nuestra prueba; el módulo b ya tiene una referencia a la SomeClass real, por lo que parece que nuestro parcheo no tuvo ningún efecto.

La clave es parchear SomeClass donde se utiliza (o donde es buscado). En este caso some_function realmente va a buscar SomeClass en el módulo b, donde lo hemos importado. La aplicación de parches debe ser similar a:

@patch('b.SomeClass')

Sin embargo, ten en cuenta el escenario alternativo donde en el módulo b en lugar de from a import SomeClass se hace import a y some_function usa a.SomeClass. Ambas formas de importación son comunes. En este caso, la clase que queremos parchear está siendo buscada en el módulo, por lo que tenemos que parchear a.SomeClass:

@patch('a.SomeClass')

Parcheando descriptores y objetos proxy¶

Tanto patch como patch.object parchean descriptores correctamente y los restauran posteriormente: métodos de clase, métodos estáticos y propiedades. Los descriptores deben ser parcheados en la clase y no en una instancia. También funcionan con algunos objetos que actúan como proxy en el acceso a atributos, como el objeto de configuraciones de django (django settings object).

MagicMock y el soporte de métodos mágicos¶

Simular métodos mágicos¶

Mock soporta la simulación de los métodos de protocolo de Python, también conocidos como «métodos mágicos». Esto permite a los objetos simulados reemplazar contenedores u otros objetos que implementan protocolos de Python.

Dado que los métodos mágicos se buscan de manera diferente a los métodos normales 2, este soporte ha sido especialmente implementado. Esto significa que sólo es compatible con métodos mágicos específicos. La lista de métodos soportados incluye casi todos los existentes. Si hay alguno que falta y que consideras necesario, por favor háznoslo saber.

Puedes simular métodos mágicos estableciendo el método que te interesa en una función o en una instancia simulada. Si utilizas una función, debe aceptar self como primer argumento 3.

>>> def __str__(self):
...     return 'fooble'
...
>>> mock = Mock()
>>> mock.__str__ = __str__
>>> str(mock)
'fooble'

>>> mock = Mock()
>>> mock.__str__ = Mock()
>>> mock.__str__.return_value = 'fooble'
>>> str(mock)
'fooble'

>>> mock = Mock()
>>> mock.__iter__ = Mock(return_value=iter([]))
>>> list(mock)
[]

Un caso de uso para esto es simular objetos usados como gestores de contexto en una declaración with:

>>> mock = Mock()
>>> mock.__enter__ = Mock(return_value='foo')
>>> mock.__exit__ = Mock(return_value=False)
>>> with mock as m:
...     assert m == 'foo'
...
>>> mock.__enter__.assert_called_with()
>>> mock.__exit__.assert_called_with(None, None, None)

Las llamadas a métodos mágicos no aparecen registradas en method_calls, aunque si se registran en mock_calls.

Nota

Si se utiliza el argumento por palabra clave spec para crear un objeto simulado, intentar después establecer un método mágico que no está en la especificación lanzará una excepción AttributeError.

La lista completa de los métodos mágicos soportados es la siguiente:

__hash__, __sizeof__, __repr__ y __str__
__dir__, __format__ y __subclasses__
__round__, __floor__, __trunc__ y __ceil__
Comparaciones: __lt__, __gt__, __le__, __ge__, __eq__ y __ne__
Métodos de contenedores: __getitem__, __setitem__, __delitem__, __contains__, __len__, __iter__, __reversed__ y __missing__
Administrador de contexto: __enter__, __exit__, __aenter__ y __aexit__
Métodos numéricos unarios: __neg__, __pos__ y __invert__
Los métodos numéricos (incluyendo los métodos estándar y las variantes in-place): __add__, __sub__, __mul__, __matmul__, __div__, __truediv__, __floordiv__, __mod__, __divmod__, __lshift__, __rshift__, __and__, __xor__, __or__, y __pow__
Métodos de conversión numérica: __complex__, __int__, __float__ y __index__
Métodos de descriptores: __get__, __set__ y __delete__
Pickling: __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__ y __setstate__
Representación de rutas del sistema de archivos: __fspath__
Métodos de iteración asíncronos: __aiter__ y __anext__

Distinto en la versión 3.8: Se añadió soporte para os.PathLike.__fspath__().

Distinto en la versión 3.8: Se añadió soporte para __aenter__, __aexit__, __aiter__ y __anext__.

Los siguientes métodos existen pero no están soportados, ya sea porque son usados por el propio objeto simulado, porque no se pueden establecer dinámicamente o porque pueden causar problemas:

__getattr__, __setattr__, __init__ y __new__
__prepare__, __instancecheck__, __subclasscheck__ y __del__

Magic Mock¶

Hay dos variantes de MagicMock: MagicMock y NonCallableMagicMock.

class unittest.mock.MagicMock(*args, **kw)¶

MagicMock es una subclase de Mock con implementaciones por defecto de la mayoría de los métodos mágicos. Puedes utilizar MagicMock para crear objetos simulados sin tener que establecer los métodos mágicos por ti mismo.

Los parámetros del constructor tienen el mismo significado que en Mock.

Si utilizas los argumentos spec o spec_set entonces solo los métodos mágicos que existan en la especificación serán creados.

class unittest.mock.NonCallableMagicMock(*args, **kw)¶

Una versión no invocable de MagicMock.

Los parámetros del constructor tienen el mismo significado que en MagicMock, con la excepción de return_value y side_effect que no tienen significado en un objeto simulado no invocable.

Los métodos mágicos están implementados mediante objetos MagicMock, por lo que puedes configurarlos y utilizarlos de la forma habitual:

>>> mock = MagicMock()
>>> mock[3] = 'fish'
>>> mock.__setitem__.assert_called_with(3, 'fish')
>>> mock.__getitem__.return_value = 'result'
>>> mock[2]
'result'

Por defecto, muchos de los métodos de protocolo están obligados a retornar objetos de un tipo específico. Estos métodos están preconfigurados con un valor de retorno por defecto, de manera que puedan ser utilizados sin tener que hacer nada más, siempre que no estés interesado en el valor de retorno. En todo caso, puedes establecer el valor de retorno de forma manual si deseas cambiar el valor predeterminado.

Métodos y sus valores por defecto:

__lt__: NotImplemented
__gt__: NotImplemented
__le__: NotImplemented
__ge__: NotImplemented
__int__: 1
__contains__: False
__len__: 0
__iter__: iter([])
__exit__: False
__aexit__: False
__complex__: 1j
__float__: 1.0
__bool__: True
__index__: 1
__hash__: hash predeterminado del objeto simulado
__str__: str predeterminado del objeto simulado
__sizeof__: sizeof predeterminado del objeto simulado

Por ejemplo:

>>> mock = MagicMock()
>>> int(mock)
1
>>> len(mock)
0
>>> list(mock)
[]
>>> object() in mock
False

Los dos métodos de igualdad, __eq__() y __ne__(), son especiales. Realizan la comparación de igualdad predeterminada basada en la identidad, utilizando el atributo side_effect, a menos que cambies su valor de retorno para que retorne alguna otra cosa:

>>> MagicMock() == 3
False
>>> MagicMock() != 3
True
>>> mock = MagicMock()
>>> mock.__eq__.return_value = True
>>> mock == 3
True

El valor de retorno de MagicMock.__iter__() puede ser cualquier objeto iterable, no se requiere que sea un iterador:

>>> mock = MagicMock()
>>> mock.__iter__.return_value = ['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']

Si el valor de retorno es un iterador, iterar sobre él una vez que se consume, y cualquier iteración posterior, resultará en una lista vacía:

>>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
[]

MagicMock tiene todos los métodos mágicos soportados configurados a excepción de algunos de los más oscuros y obsoletos. De todas formas, puedes configurar estos también si lo deseas.

Los métodos mágicos que son compatibles, pero que no están configurados por defecto en MagicMock son:

__subclasses__
__dir__
__format__
__get__, __set__ y __delete__
__reversed__ y __missing__
__reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__ y __setstate__
__getformat__ y __setformat__

2: Los métodos mágicos deben ser buscados en la clase en lugar de en la instancia. Diferentes versiones de Python son inconsistentes sobre la aplicación de esta regla. Los métodos de protocolo soportados deben trabajar con todas las versiones de Python.
3: La función está básicamente conectada a la clase, pero cada instancia Mock se mantiene aislada de las demás.

Ayudantes¶

sentinel¶

unittest.mock.sentinel¶

El objeto sentinel proporciona una manera conveniente de proporcionar objetos únicos para tus pruebas.

Los atributos se crean a demanda, en el instante en el que se accede a ellos por su nombre por primera vez. El acceso al mismo atributo siempre retornará el mismo objeto. Los objetos retornados tienen una reproducción (repr) apropiada para que los mensajes de error de la prueba sean legibles.

Distinto en la versión 3.7: Los atributos sentinel ahora preservan su identidad cuando son copiados o serializados con pickle.

A veces, cuando implementas pruebas, necesitas probar que un determinado objeto se pasa como argumento a otro método, o se retorna. Crear objetos centinela con un nombre para probar esto puede ser una práctica común. sentinel proporciona una manera conveniente de crear y probar la identidad de este tipo de objetos.

En el siguiente ejemplo, parcheamos method para retornar sentinel.some_object:

>>> real = ProductionClass()
>>> real.method = Mock(name="method")
>>> real.method.return_value = sentinel.some_object
>>> result = real.method()
>>> assert result is sentinel.some_object
>>> result
sentinel.some_object

DEFAULT¶

unittest.mock.DEFAULT¶: El objeto DEFAULT es un centinela pre-creado (actualmente sentinel.DEFAULT). Puede ser usado por las funciones side_effect para indicar que el valor de retorno normal debe ser utilizado.

call¶

unittest.mock.call(*args, **kwargs)¶

call() es un objeto ayudante que puede usarse para hacer aserciones simples, para comparar con call_args, call_args_list, mock_calls y method_calls. call() y también se puede utilizar con assert_has_calls().

>>> m = MagicMock(return_value=None)
>>> m(1, 2, a='foo', b='bar')
>>> m()
>>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
True

call.call_list()¶: Para un objeto call que representa múltiples llamadas, el método call_list() retorna una lista con todas las llamadas intermedias, así como la llamada final.

call_list es particularmente útil para hacer aserciones sobre «llamadas encadenadas». Una llamada encadenada es varias llamadas en una sola línea de código. Esto resulta en múltiples entradas en el atributo mock_calls de un objeto simulado. Construir manualmente la secuencia de llamadas puede ser tedioso.

call_list() puede construir la secuencia de llamadas desde la misma llamada encadenada:

>>> m = MagicMock()
>>> m(1).method(arg='foo').other('bar')(2.0)
<MagicMock name='mock().method().other()()' id='...'>
>>> kall = call(1).method(arg='foo').other('bar')(2.0)
>>> kall.call_list()
[call(1),
 call().method(arg='foo'),
 call().method().other('bar'),
 call().method().other()(2.0)]
>>> m.mock_calls == kall.call_list()
True

Un objeto call, dependiendo de cómo fuera construido, puede ser una tupla de la forma (argumentos posicionales, argumentos por palabras clave) o bien de la forma (nombre, argumentos posicionales, argumentos por palabras clave). Esto no es particularmente interesante cuando los construyes por ti mismo, pero la introspección de los objetos call que conforman los atributos Mock.call_args, Mock.call_args_list y Mock.mock_calls si pueden ser de utilidad para para acceder a los argumentos individuales que contienen.

Los objetos call en Mock.call_args y Mock.call_args_list están conformados por dos tuplas (argumentos posicionales, argumentos por palabra clave) mientras que los objetos call en Mock.mock_calls, junto con los que construyas por ti mismo, constan de tres tuplas (nombre, argumentos posicionales, argumentos por palabra clave).

Puedes utilizar esta presentación en forma de tuplas para obtener los argumentos individuales, con la finalidad de llevar a cabo introspección y aserciones más complejas. Los argumentos posicionales son una tupla (vacía si no hay ninguno) y los argumentos por palabra clave son un diccionario:

>>> m = MagicMock(return_value=None)
>>> m(1, 2, 3, arg='one', arg2='two')
>>> kall = m.call_args
>>> kall.args
(1, 2, 3)
>>> kall.kwargs
{'arg': 'one', 'arg2': 'two'}
>>> kall.args is kall[0]
True
>>> kall.kwargs is kall[1]
True

>>> m = MagicMock()
>>> m.foo(4, 5, 6, arg='two', arg2='three')
<MagicMock name='mock.foo()' id='...'>
>>> kall = m.mock_calls[0]
>>> name, args, kwargs = kall
>>> name
'foo'
>>> args
(4, 5, 6)
>>> kwargs
{'arg': 'two', 'arg2': 'three'}
>>> name is m.mock_calls[0][0]
True

create_autospec¶

unittest.mock.create_autospec(spec, spec_set=False, instance=False, **kwargs)¶

Crea un nuevo objeto simulado utilizando otro objeto (spec) como especificación. Los atributos del objeto simulado utilizarán el atributo correspondiente del objeto spec como su especificación.

Los argumentos de las funciones o métodos simulados se validarán para asegurarse de que son invocados con la firma correcta.

Si spec_set es True, tratar de establecer atributos que no existen en el objeto especificado lanzará una excepción AttributeError.

Si se utiliza una clase como especificación, el valor de retorno del objeto simulado (la instancia de la clase) tendrá la misma especificación. Se puede utilizar una clase como especificación de una instancia pasando instance=True. El objeto simulado retornado sólo será invocable si las instancias del objeto simulado son también invocables.

create_autospec() también acepta argumentos por palabra clave arbitrarios, que son pasados al constructor del objeto simulado creado.

Consultar Autoespecificación para ver ejemplos de cómo utilizar la autoespecificación mediante create_autospec() y el argumento autospec de patch().

Distinto en la versión 3.8: create_autospec() ahora retorna un objeto AsyncMock si el objetivo a simular es una función asíncrona.

ANY¶

unittest.mock.ANY¶

A veces puede que necesites hacer aserciones sobre algunos de los argumentos de una llamada al objeto simulado, pero sin preocuparte por el resto, o puede que quieras hacer uso de ellos de forma individual fuera de call_args y hacer aserciones más complejas con ellos.

Para ignorar ciertos argumentos puedes pasar objetos que se comparan como iguales con cualquier cosa. En este caso, las llamadas a assert_called_with() y assert_called_once_with() tendrán éxito sin importar lo que se haya pasado realmente.

>>> mock = Mock(return_value=None)
>>> mock('foo', bar=object())
>>> mock.assert_called_once_with('foo', bar=ANY)

ANY también se puede utilizar en las comparaciones con las listas de llamadas, como mock_calls:

>>> m = MagicMock(return_value=None)
>>> m(1)
>>> m(1, 2)
>>> m(object())
>>> m.mock_calls == [call(1), call(1, 2), ANY]
True

FILTER_DIR¶

unittest.mock.FILTER_DIR¶

FILTER_DIR es una variable definida a nivel de módulo que controla la forma en la que los objetos simulados responden a dir() (sólo para Python 2.6 y en adelante). El valor predeterminado es True, que utiliza el filtrado descrito a continuación, con la finalidad de mostrar solo los miembros considerados como útiles. Si no te gusta este filtrado, o necesitas desactivarlo con fines de diagnóstico, simplemente establece mock.FILTER_DIR = False.

Con el filtrado activado, dir(some_mock) mostrará solo atributos útiles y además incluirá cualquier atributo creado dinámicamente, que normalmente no se mostraría. Si el objeto simulado fue creado con un spec (o autospec) se muestran todos los atributos del objeto original, incluso si no se ha accedido a ellos todavía:

>>> dir(Mock())
['assert_any_call',
 'assert_called',
 'assert_called_once',
 'assert_called_once_with',
 'assert_called_with',
 'assert_has_calls',
 'assert_not_called',
 'attach_mock',
 ...
>>> from urllib import request
>>> dir(Mock(spec=request))
['AbstractBasicAuthHandler',
 'AbstractDigestAuthHandler',
 'AbstractHTTPHandler',
 'BaseHandler',
 ...

Muchos de los atributos con subrayado y doble subrayado no muy útiles (atributos privados de Mock y no del objeto real que se está simulando) se han filtrado del resultado de llamar a dir() en un objeto Mock. Si no te gusta este comportamiento, puedes desactivarlo estableciendo el modificador a nivel de módulo FILTER_DIR:

>>> from unittest import mock
>>> mock.FILTER_DIR = False
>>> dir(mock.Mock())
['_NonCallableMock__get_return_value',
 '_NonCallableMock__get_side_effect',
 '_NonCallableMock__return_value_doc',
 '_NonCallableMock__set_return_value',
 '_NonCallableMock__set_side_effect',
 '__call__',
 '__class__',
 ...

Como alternativa, puedes usar vars(my_mock) (miembros de instancia) y dir(type(my_mock)) (miembros de tipo) para omitir el filtrado con independencia del valor de mock.FILTER_DIR.

mock_open¶

unittest.mock.mock_open(mock=None, read_data=None)¶

Una función auxiliar que permite crear un objeto simulado con la finalidad de reemplazar el uso de open(). Funciona para simular llamadas directas a open() y para aquellos casos en los que es utilizada como gestor de contexto.

El argumento mock es el objeto simulado a configurar. Si es None (por defecto) un objeto MagicMock se creará para ti, con la API limitada a métodos o atributos disponibles en los gestores de fichero estándares.

read_data es una cadena de caracteres para los métodos read(), readline() y readlines() del gestor de fichero a retornar. Las llamadas a los métodos tomarán datos de read_data hasta que se agote. El objeto simulado de estos métodos es bastante simple: cada vez que el mock se llama, read_data se rebobina hasta el principio. Si necesitas más control sobre los datos que estás proporcionando al código de prueba tendrás que personalizar el objeto simulado. Cuando eso no sea suficiente, alguno de los paquetes que implementan sistemas de archivos en memoria disponible en PyPI puede ofrecer un sistema de archivos realista para usar en las pruebas.

Distinto en la versión 3.4: Se añadió soporte para readline() y readlines(). El objeto simulado de read() ahora consume datos de read_data, en lugar de retornarlo en cada llamada.

Distinto en la versión 3.5: read_data ahora es restablecido en cada llamada al mock.

Distinto en la versión 3.8: Se añadió el método __iter__() a la implementación, de manera que la iteración (como ocurre en los bucles) consume apropiadamente read_data.

Usar open() como gestor de contexto es una buena manera de asegurarse de que los gestores de archivos se cierren correctamente al terminar y se está convirtiendo en una práctica común:

with open('/some/path', 'w') as f:
    f.write('something')

El problema es que, incluso si simulas la llamada a open(), es el objeto retornado el que se utiliza como gestor de contexto (lo que conlleva que sus métodos __enter__() y __exit__() son invocados).

Simular gestores de contexto con un MagicMock es lo suficientemente común y complicado como para que una función auxiliar sea útil:

>>> m = mock_open()
>>> with patch('__main__.open', m):
...     with open('foo', 'w') as h:
...         h.write('some stuff')
...
>>> m.mock_calls
[call('foo', 'w'),
 call().__enter__(),
 call().write('some stuff'),
 call().__exit__(None, None, None)]
>>> m.assert_called_once_with('foo', 'w')
>>> handle = m()
>>> handle.write.assert_called_once_with('some stuff')

Y para la lectura de archivos:

>>> with patch('__main__.open', mock_open(read_data='bibble')) as m:
...     with open('foo') as h:
...         result = h.read()
...
>>> m.assert_called_once_with('foo')
>>> assert result == 'bibble'

Autoespecificación¶

La autoespecificación se basa en la característica spec ya existente en el objeto simulado. Limita la API de los objetos simulados a la API del objeto original (la especificación), pero es recursiva (implementada de forma perezosa), de modo que los atributos del objeto simulado sólo tienen la misma API que los atributos de la especificación. Además, las funciones / métodos simuladas tienen la misma firma de llamada que la original y lanzan una excepción TypeError si se les llama incorrectamente.

Antes de explicar cómo funciona la autoespecificación, he aquí por qué se necesita.

Mock es un objeto muy potente y flexible, pero adolece de dos defectos cuando se utiliza para simular objetos de un sistema bajo prueba. Uno de estos defectos es específico de la API de Mock y el otro es un problema más genérico referente al uso de objetos simulados.

En primer lugar, el problema específico a Mock. Mock tiene dos métodos de aserción que son extremadamente útiles: assert_called_with() y assert_called_once_with().

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
Traceback (most recent call last):
 ...
AssertionError: Expected 'mock' to be called once. Called 2 times.

Debido a que los objetos simulados crean automáticamente atributos según demanda y además permiten que se les llame con argumentos arbitrarios, si escribes mal uno de estos métodos de aserción, la utilidad de esa aserción desaparece:

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assret_called_once_with(4, 5, 6)  # Intentional typo!

Tus pruebas pueden pasar silenciosamente y de forma incorrecta debido al error tipográfico.

El segundo problema es algo más general en las simulaciones. Si refactorizas parte de tu código, cambias el nombre de los miembros, etc., las pruebas para el código que siguen utilizando la antigua API, pero utilizan objetos simulados en lugar de los objetos reales, todavía pasarán las pruebas. Esto significa que tus pruebas pueden validarlo todo sin problemas, a pesar de que el código esté roto.

Ten en cuenta que esta es otra razón por la que necesitas pruebas de integración además de pruebas unitarias. Probar todo de forma aislada está muy bien, pero si no pruebas cómo están «conectadas entre sí» tus unidades, todavía hay mucho espacio para errores que las pruebas deberían haber detectado.

mock ya proporciona una característica para ayudar con esto, llamada especificación. Si se utiliza una clase o instancia como atributo spec de un objeto simulado, entonces solo puedes acceder a los atributos del mismo que existe en la clase real:

>>> from urllib import request
>>> mock = Mock(spec=request.Request)
>>> mock.assret_called_with  # Intentional typo!
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'

La especificación sólo se aplica al propio objeto simulado, por lo que aún tenemos el mismo problema con cualquiera de los métodos del mismo:

>>> mock.has_data()
<mock.Mock object at 0x...>
>>> mock.has_data.assret_called_with()  # Intentional typo!

La autoespecificación resuelve este problema. Puedes pasar autospec=True a patch() / patch.object() o utilizar la función create_autospec() para crear un objeto simulado con una especificación. Si utilizas el argumento autospec=True de patch(), el objeto que se va a reemplazar se utiliza como objeto de especificación. Debido a que la especificación se hace «perezosamente» (la especificación se crea en el instante en el que se accede a los atributos del objeto simulado, no antes), se puede utilizar con objetos muy complejos o anidadas (como módulos que importan módulos que, a su vez, importan otros módulos) sin un gran impacto en el rendimiento.

He aquí un ejemplo de ello en acción:

>>> from urllib import request
>>> patcher = patch('__main__.request', autospec=True)
>>> mock_request = patcher.start()
>>> request is mock_request
True
>>> mock_request.Request
<MagicMock name='request.Request' spec='Request' id='...'>

Se puede ver que request.Request tiene una especificación. request.Request toma dos argumentos en el constructor (uno de los cuales es self). Esto es lo que sucede si tratamos de llamarlo de forma incorrecta:

>>> req = request.Request()
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes at least 2 arguments (1 given)

La especificación también se aplica a las clases instanciadas (es decir, el valor de retorno de los objetos simulados especificados):

>>> req = request.Request('foo')
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>

Los objetos de la clase Request no son invocables, por lo que el valor de retorno de una instancia de nuestro objeto simulado de request.Request no es invocable. Con la especificación, en cambio, cualquier error tipográfico en nuestras aserciones generará el error correcto:

>>> req.add_header('spam', 'eggs')
<MagicMock name='request.Request().add_header()' id='...'>
>>> req.add_header.assret_called_with  # Intentional typo!
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'
>>> req.add_header.assert_called_with('spam', 'eggs')

En muchos casos, podrás simplemente añadir autospec=True a tus llamadas patch() existentes y así estar protegido contra errores tipográficos y cambios de la API.

Además de poder usar autospec a través de patch(), existe la función create_autospec() para crear directamente objetos simulados autoespecificados:

>>> from urllib import request
>>> mock_request = create_autospec(request)
>>> mock_request.Request('foo', 'bar')
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>

Sin embargo, este no es el comportamiento predeterminado, ya que no está exento de advertencias y restricciones. Con el fin de conocer qué atributos están disponibles en el objeto especificado, autospec tiene que hacer uso de introspección sobre la especificación (acceder a los atributos). A medida que recorres los atributos en el objeto simulado, se produce paralelamente y de forma soterrada un recorrido del objeto original. Si alguno de tus objetos especificados tienen propiedades o descriptores que puedan desencadenar la ejecución de código, quizás no deberías utilizar la autoespecificación. De todas formas, es siempre mucho mejor diseñar tus objetos de modo que la introspección sea segura 4.

Un problema más serio es que es común que los atributos de instancia sean creados en el método __init__() y que no existan a nivel de clase. autospec no puede tener conocimiento de ningún atributo creado dinámicamente, por lo que restringe la API a atributos visibles:

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a
...
Traceback (most recent call last):
  ...
AttributeError: Mock object has no attribute 'a'

Hay diferentes formas de resolver este problema. La forma más sencilla, pero no necesariamente la menos molesta, es simplemente establecer los atributos necesarios en el objeto simulado después de la creación del mismo. El hecho de que autospec no te permita buscar atributos que no existen en la especificación no impide que los establezcas manualmente después:

>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a = 33
...

Existe una versión más agresiva de spec y autospec que impide establecer atributos inexistentes. Esto es útil si deseas asegurarte de que tu código solo establece atributos válidos, pero obviamente evitando este escenario en particular:

>>> with patch('__main__.Something', autospec=True, spec_set=True):
...   thing = Something()
...   thing.a = 33
...
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'a'

Probablemente la mejor manera de resolver el problema es añadir atributos de clase como valores por defecto para los miembros de instancia inicializados en el método __init__(). Ten en cuenta que, si sólo estás estableciendo atributos predeterminados en __init__(), proporcionarlos a través de atributos de clase (que , por supuesto, son compartidos entre instancias) también es más rápido.

class Something:
    a = 33

Esto nos plantea otro problema. Es relativamente común proporcionar un valor predeterminado de None para los miembros que posteriormente se convertirán en objetos de un tipo diferente. None es inútil como especificación dado que no permite acceder a ningún atributo o método. Como None nunca será útil como especificación, y probablemente indica un miembro que normalmente será de algún otro tipo en el futuro, la autoespecificación no usa una especificación para aquellos miembros configurados con None como valor. Estos serán simplemente objetos simulados ordinarios (MagicMocks en realidad):

>>> class Something:
...     member = None
...
>>> mock = create_autospec(Something)
>>> mock.member.foo.bar.baz()
<MagicMock name='mock.member.foo.bar.baz()' id='...'>

Si modificar tus clases en producción para agregar valores predeterminados no es de tu agrado, dispones de otras opciones. Una de ellas es simplemente usar una instancia como especificación en lugar de la clase. La otra es crear una subclase de la clase en producción y agregar los valores predeterminados a la subclase, sin afectar a la clase en producción. Ambas alternativas requieren que uses un objeto alternativo como especificación. Afortunadamente patch() admite esto, simplemente tienes que pasar el objeto alternativo mediante el argumento autospec:

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> class SomethingForTest(Something):
...   a = 33
...
>>> p = patch('__main__.Something', autospec=SomethingForTest)
>>> mock = p.start()
>>> mock.a
<NonCallableMagicMock name='Something.a' spec='int' id='...'>

4: Esto sólo se aplica a las clases u objetos ya instanciados. Llamar a una clase simulada para crear una instancia simulada no crea una instancia real. Solo se llevan a cabo las búsqueda de atributos (mediante llamadas a dir()).

Sellar objetos simulados¶

unittest.mock.seal(mock)¶

Seal desactivará la creación automática de objetos simulados al acceder a un atributo del objeto simulado que está siendo sellado, o a cualquiera de sus atributos que ya sean objetos simulados de forma recursiva.

Si una instancia simulada con un nombre o una especificación es asignada a un atributo no será considerada en la cadena de sellado. Esto permite evitar que seal fije partes del objeto simulado.

>>> mock = Mock()
>>> mock.submock.attribute1 = 2
>>> mock.not_submock = mock.Mock(name="sample_name")
>>> seal(mock)
>>> mock.new_attribute  # This will raise AttributeError.
>>> mock.submock.attribute2  # This will raise AttributeError.
>>> mock.not_submock.attribute2  # This won't raise.

Nuevo en la versión 3.7.

`unittest.mock` — Biblioteca de objetos simulados¶

Guía rápida¶

La clase Mock¶

Llamar a los objetos simulados¶

Eliminar atributos¶

Los nombres de los objetos simulados y el atributo name¶

Adjuntar objetos simulados como atributos¶

Parcheadores¶

patch¶

patch.object¶

patch.dict¶

patch.multiple¶

Métodos start y stop de patch¶

Parchear objetos incorporados (builtins)¶

TEST_PREFIX¶

Anidando decoradores patch¶

Dónde parchear¶

Parcheando descriptores y objetos proxy¶

MagicMock y el soporte de métodos mágicos¶

Simular métodos mágicos¶

Magic Mock¶

Ayudantes¶

sentinel¶

DEFAULT¶

call¶

create_autospec¶

ANY¶

FILTER_DIR¶

mock_open¶

Autoespecificación¶

Sellar objetos simulados¶

Tabla de contenido

Tema anterior

Próximo tema

Esta página

unittest.mock — Biblioteca de objetos simulados¶

Guía rápida¶

La clase Mock¶

Llamar a los objetos simulados¶

Eliminar atributos¶

Los nombres de los objetos simulados y el atributo name¶

Adjuntar objetos simulados como atributos¶

Parcheadores¶

patch¶

patch.object¶

patch.dict¶

patch.multiple¶

Métodos start y stop de patch¶

Parchear objetos incorporados (builtins)¶

TEST_PREFIX¶

Anidando decoradores patch¶

Dónde parchear¶

Parcheando descriptores y objetos proxy¶

MagicMock y el soporte de métodos mágicos¶

Simular métodos mágicos¶

Magic Mock¶

Ayudantes¶

sentinel¶

DEFAULT¶

call¶

create_autospec¶

ANY¶

FILTER_DIR¶

mock_open¶

Autoespecificación¶

Sellar objetos simulados¶

`unittest.mock` — Biblioteca de objetos simulados¶