requests-mock/doc/source/mocker.rst

Using the Mocker

The mocker is a loading mechanism to ensure the adapter is correctly in place to intercept calls from requests. It's 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 :pyrequests_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'

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:

• :py~requests_mock.MockerCore.delete
• :py~requests_mock.MockerCore.get
• :py~requests_mock.MockerCore.head
• :py~requests_mock.MockerCore.options
• :py~requests_mock.MockerCore.patch
• :py~requests_mock.MockerCore.post
• :py~requests_mock.MockerCore.put

As well as the basic:

• :py~requests_mock.MockerCore.request
• :py~requests_mock.MockerCore.register_uri

These methods correspond to the HTTP method of your request, so to mock POST requests you would use the :py~requests_mock.MockerCore.post function. Further information about what can be matched from a request can be found at 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) # doctest: +SKIP ... '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) # doctest: +SKIP ... 'resp' 200