Using the Mocker¶

The mocker is a loading mechanism to ensure the adapter is correctly in place to intercept calls from requests. Its goal is to provide an interface that is as close to the real requests library interface as possible.

Activation¶

Loading of the Adapter is handled by the requests_mock.Mocker class, which provides two ways to load an adapter:

Context Manager¶

The Mocker object can work as a context manager.

>>> import requests
>>> import requests_mock

>>> with requests_mock.Mocker() as m:
...     m.get('http://test.com', text='resp')
...     requests.get('http://test.com').text
...
'resp'

Decorator¶

Mocker can also be used as a decorator. The created object will then be passed as the last positional argument.

>>> @requests_mock.Mocker()
... def test_function(m):
...     m.get('http://test.com', text='resp')
...     return requests.get('http://test.com').text
...
>>> test_function()
'resp'

If the position of the mock is likely to conflict with other arguments you can pass the kw argument to the Mocker to have the mocker object passed as that keyword argument instead.

>>> @requests_mock.Mocker(kw='mock')
... def test_kw_function(**kwargs):
...     kwargs['mock'].get('http://test.com', text='resp')
...     return requests.get('http://test.com').text
...
>>> test_kw_function()
'resp'

Contrib¶

The contrib module also provides ways of loading the mocker based on other frameworks. These will require additional dependencies but may provide a better experience depending on your tests setup.

See Additional Loading for these additions.

Class Decorator¶

Mocker can also be used to decorate a whole class. It works exactly like in case of decorating a normal function. When used in this way they wrap every test method on the class. The mocker recognise methods that start with test as being test methods. This is the same way that the unittest.TestLoader finds test methods by default. It is possible that you want to use a different prefix for your tests. You can inform the mocker of the different prefix by setting requests_mock.Mocker.TEST_PREFIX:

>>> requests_mock.Mocker.TEST_PREFIX = 'foo'
>>>
>>> @requests_mock.Mocker()
... class Thing(object):
...     def foo_one(self, m):
...        m.register_uri('GET', 'http://test.com', text='resp')
...        return requests.get('http://test.com').text
...     def foo_two(self, m):
...         m.register_uri('GET', 'http://test.com', text='resp')
...         return requests.get('http://test.com').text
...
>>>
>>> Thing().foo_one()
'resp'
>>> Thing().foo_two()
'resp'

This behavior mimics how patchers from mock library works.

Methods¶

The mocker object can be used with a similar interface to requests itself.

>>> with requests_mock.Mocker() as mock:
...     mock.get('http://test.com', text='resp')
...     requests.get('http://test.com').text
...
'resp'

The functions exist for the common HTTP method:

delete()

get()

head()

options()

patch()

post()

put()

As well as the basic:

request()

register_uri()

These methods correspond to the HTTP method of your request, so to mock POST requests you would use the post() function. Further information about what can be matched from a request can be found at Request Matching

Real HTTP Requests¶

The Mocker object takes the following parameters:

real_http (bool):
	If True then any requests that are not handled by the mocking adapter will be forwarded to the real server. Defaults to False.

>>> with requests_mock.Mocker(real_http=True) as m:
...     m.register_uri('GET', 'http://test.com', text='resp')
...     print(requests.get('http://test.com').text)
...     print(requests.get('http://www.google.com').status_code)  
...
'resp'
200

New in 1.1

Similarly when using a mocker you can register an individual URI to bypass the mocking infrastructure and make a real request. Note this only works when using the mocker and not when directly mounting an adapter.

>>> with requests_mock.Mocker() as m:
...     m.register_uri('GET', 'http://test.com', text='resp')
...     m.register_uri('GET', 'http://www.google.com', real_http=True)
...     print(requests.get('http://test.com').text)
...     print(requests.get('http://www.google.com').status_code)  
...
'resp'
200