python/mock-1.0.0/docs/sentinel.txt
author Carsten "Tomcat" Book <cbook@mozilla.com>
Tue, 30 Jun 2015 10:30:51 +0200
changeset 274663 79800010be78122db7c36d4b5833814fdbf28495
parent 112588 5981ff9d3f45de802d956b2f8e064f49b74cb7a6
permissions -rw-r--r--
Backed out changeset f41a2121425f (bug 1171931) for bustage

==========
 Sentinel
==========


.. currentmodule:: mock

.. testsetup::

    class ProductionClass(object):
        def something(self):
            return self.method()

    class Test(unittest2.TestCase):
        def testSomething(self):
            pass
    self = Test('testSomething')


.. data:: sentinel

    The ``sentinel`` object provides a convenient way of providing unique
    objects for your tests.

    Attributes are created on demand when you access them by name. Accessing
    the same attribute will always return the same object. The objects
    returned have a sensible repr so that test failure messages are readable.


.. data:: DEFAULT

    The `DEFAULT` object is a pre-created sentinel (actually
    `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect`
    functions to indicate that the normal return value should be used.


Sentinel Example
================

Sometimes when testing you need to test that a specific object is passed as an
argument to another method, or returned. It can be common to create named
sentinel objects to test this. `sentinel` provides a convenient way of
creating and testing the identity of objects like this.

In this example we monkey patch `method` to return
`sentinel.some_object`:

.. doctest::

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