michael@0: ==========
michael@0:  Sentinel
michael@0: ==========
michael@0: 
michael@0: 
michael@0: .. currentmodule:: mock
michael@0: 
michael@0: .. testsetup::
michael@0: 
michael@0:     class ProductionClass(object):
michael@0:         def something(self):
michael@0:             return self.method()
michael@0: 
michael@0:     class Test(unittest2.TestCase):
michael@0:         def testSomething(self):
michael@0:             pass
michael@0:     self = Test('testSomething')
michael@0: 
michael@0: 
michael@0: .. data:: sentinel
michael@0: 
michael@0:     The ``sentinel`` object provides a convenient way of providing unique
michael@0:     objects for your tests.
michael@0: 
michael@0:     Attributes are created on demand when you access them by name. Accessing
michael@0:     the same attribute will always return the same object. The objects
michael@0:     returned have a sensible repr so that test failure messages are readable.
michael@0: 
michael@0: 
michael@0: .. data:: DEFAULT
michael@0: 
michael@0:     The `DEFAULT` object is a pre-created sentinel (actually
michael@0:     `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect`
michael@0:     functions to indicate that the normal return value should be used.
michael@0: 
michael@0: 
michael@0: Sentinel Example
michael@0: ================
michael@0: 
michael@0: Sometimes when testing you need to test that a specific object is passed as an
michael@0: argument to another method, or returned. It can be common to create named
michael@0: sentinel objects to test this. `sentinel` provides a convenient way of
michael@0: creating and testing the identity of objects like this.
michael@0: 
michael@0: In this example we monkey patch `method` to return
michael@0: `sentinel.some_object`:
michael@0: 
michael@0: .. doctest::
michael@0: 
michael@0:     >>> real = ProductionClass()
michael@0:     >>> real.method = Mock(name="method")
michael@0:     >>> real.method.return_value = sentinel.some_object
michael@0:     >>> result = real.method()
michael@0:     >>> assert result is sentinel.some_object
michael@0:     >>> sentinel.some_object
michael@0:     sentinel.some_object
michael@0: 
michael@0: