deb-python-httpretty/docs/docs.md

Reference

testing query strings

import requests
from sure import expect
import httpretty

def test_one():
    httpretty.enable()  # enable HTTPretty so that it will monkey patch the socket module
    httpretty.register_uri(httpretty.GET, "http://yipit.com/login",
                           body="Find the best daily deals")

    requests.get('http://yipit.com/login?email=user@github.com&password=foobar123')
    expect(httpretty.last_request()).to.have.property("querystring").being.equal({
        "email": "user@github.com",
        "password": "foobar123",
    })

    httpretty.disable()  # disable afterwards, so that you will have no problems in code that uses that socket module

Using the decorator

YES we've got a decorator

import requests
import httpretty

@httpretty.activate
def test_one():
    httpretty.register_uri(httpretty.GET, "http://yipit.com/",
                           body="Find the best daily deals")

    response = requests.get('http://yipit.com')
    assert response.text == "Find the best daily deals"

the @httpretty.activate is a short-hand decorator that wraps the decorated function with httpretty.enable() and then calls httpretty.disable() right after.

Providing status code

import requests
from sure import expect
import httpretty

@httpretty.activate
def test_github_access():
    httpretty.register_uri(httpretty.GET, "http://github.com/",
                           body="here is the mocked body",
                           status=201)

    response = requests.get('http://github.com')
    expect(response.status_code).to.equal(201)

Providing custom headers

and all you need is to add keyword args in which the keys are always lower-cased and with underscores _ instead of dashes -

For example, let's say you want to mock that server returns content-type. To do so, use the argument content_type, all the keyword args are taken by HTTPretty and transformed in the RFC2616 equivalent name.

@httpretty.activate
def test_some_api():
    httpretty.register_uri(httpretty.GET, "http://foo-api.com/gabrielfalcao",
                           body='{"success": false}',
                           status=500,
                           content_type='text/json')

    response = requests.get('http://foo-api.com/gabrielfalcao')

    expect(response.json()).to.equal({'success': False})
    expect(response.status_code).to.equal(500)

Adding extra headers and forcing headers

You can pass the adding_headers argument as a dictionary and your headers will be united to the existing headers.

@httpretty.activate
def test_some_api():
    httpretty.register_uri(httpretty.GET, "http://foo-api.com/gabrielfalcao",
                           body='{"success": false}',
                           status=500,
                           content_type='text/json',
                           adding_headers={
                               'X-foo': 'bar'
                           })

    response = requests.get('http://foo-api.com/gabrielfalcao')

    expect(response.json()).to.equal({'success': False})
    expect(response.status_code).to.equal(500)

Although there are some situation where some headers line content-length will be calculated by HTTPretty based on the specified fake response body.

So you might want to "force" those headers:

@httpretty.activate
def test_some_api():
    httpretty.register_uri(httpretty.GET, "http://foo-api.com/gabrielfalcao",
                           body='{"success": false}',
                           status=500,
                           content_type='text/json',
                           forcing_headers={
                               'content-length': '100'
                           })

    response = requests.get('http://foo-api.com/gabrielfalcao')

    expect(response.json()).to.equal({'success': False})
    expect(response.status_code).to.equal(500)

You should, though, be careful with it. The HTTP client is likely to rely on the content length to know how many bytes of response payload should be loaded. Forcing a content-length that is bigger than the action response body might cause the HTTP client to hang because it is waiting for data. Read more in the "caveats" session on the bottom.

rotating responses

Same URL, same request method, the first request return the first httpretty.Response, all the subsequent ones return the last (status 202).

Notice that the responses argument is a list and you can pass as many responses as you want.

import requests
from sure import expect


@httpretty.activate
def test_rotating_responses():
    httpretty.register_uri(httpretty.GET, "http://github.com/gabrielfalcao/httpretty",
                           responses=[
                               httpretty.Response(body="first response", status=201),
                               httpretty.Response(body='second and last response', status=202),
                            ])

    response1 = requests.get('http://github.com/gabrielfalcao/httpretty')
    expect(response1.status_code).to.equal(201)
    expect(response1.text).to.equal('first response')

    response2 = requests.get('http://github.com/gabrielfalcao/httpretty')
    expect(response2.status_code).to.equal(202)
    expect(response2.text).to.equal('second and last response')

    response3 = requests.get('http://github.com/gabrielfalcao/httpretty')

    expect(response3.status_code).to.equal(202)
    expect(response3.text).to.equal('second and last response')

streaming responses

Mock a streaming response by registering a generator response body.

import requests
from sure import expect
import httpretty

# mock a streaming response body with a generator
def mock_streaming_tweets(tweets):
    from time import sleep
    for t in tweets:
        sleep(.5)
        yield t

@httpretty.activate
def test_twitter_api_integration(now):
    twitter_response_lines = [
        '{"text":"If @BarackObama requests to follow me one more time I\'m calling the police."}\r\n',
        '\r\n',
        '{"text":"Thanks for all your #FollowMe1D requests Directioners! We\u2019ll be following 10 people throughout the day starting NOW. G ..."}\r\n'
    ]

    TWITTER_STREAMING_URL = "https://stream.twitter.com/1/statuses/filter.json"

    # set the body to a generator and set `streaming=True` to mock a streaming response body
    httpretty.register_uri(httpretty.POST, TWITTER_STREAMING_URL,
                           body=mock_streaming_tweets(twitter_response_lines),
                           streaming=True)

    # taken from the requests docs
    # http://docs.python-requests.org/en/latest/user/advanced/#streaming-requests
    response = requests.post(TWITTER_STREAMING_URL, data={'track':'requests'},
                            auth=('username','password'), prefetch=False)

    #test iterating by line
    line_iter = response.iter_lines()
    for i in xrange(len(twitter_response_lines)):
        expect(line_iter.next().strip()).to.equal(twitter_response_lines[i].strip())

dynamic responses through callbacks

Set a callback to allow for dynamic responses based on the request.

import requests
from sure import expect
import httpretty

@httpretty.activate
def test_response_callbacks():

    def request_callback(request, uri, headers):
        return (200, headers, "The {} response from {}".format(request.method, uri))

    httpretty.register_uri(
        httpretty.GET, "https://api.yahoo.com/test",
        body=request_callback)

    response = requests.get('https://api.yahoo.com/test')

    expect(response.text).to.equal('The GET response from https://api.yahoo.com/test')

matching regular expressions

You can register a compiled regex and it will be matched against the requested urls.

@httpretty.activate
def test_httpretty_should_allow_registering_regexes():
    u"HTTPretty should allow registering regexes"

    httpretty.register_uri(
        httpretty.GET,
        re.compile("api.yipit.com/v2/deal;brand=(\w+)"),
        body="Found brand",
    )

    response = requests.get('https://api.yipit.com/v2/deal;brand=GAP')
    expect(response.text).to.equal('Found brand')
    expect(httpretty.last_request().method).to.equal('GET')
    expect(httpretty.last_request().path).to.equal('/v1/deal;brand=GAP')

By default, the regexp you register will match the requests without looking at the querystring. If you want the querystring to be considered, you can set match_querystring=True when calling register_uri.

expect for a response, and check the request got by the "server" to make sure it was fine.

import requests
from sure import expect
import httpretty


@httpretty.activate
def test_yipit_api_integration():
    httpretty.register_uri(httpretty.POST, "http://api.yipit.com/foo/",
                           body='{"repositories": ["HTTPretty", "lettuce"]}')

    response = requests.post('http://api.yipit.com/foo',
                            '{"username": "gabrielfalcao"}',
                            headers={
                                'content-type': 'text/json',
                            })

    expect(response.text).to.equal('{"repositories": ["HTTPretty", "lettuce"]}')
    expect(httpretty.last_request().method).to.equal("POST")
    expect(httpretty.last_request().headers['content-type']).to.equal('text/json')

checking whether a request was made or not

import httpretty
import requests

def order_pizza(user, home_delivery=True):
    check_number = make_pizza()
    if home_delivery:
        requests.post('http://api.pizzas.com/deliveries/', {'address': user.address, 'check_number': check_number})
    else:
        # for pick up.
        pass
    return check_number
    
@httpretty.activate
def test_pizza_delivery():
    httpretty.register_uri(httpretty.POST, 'http://api.pizzas.com/deliveries/', body='OK')

    order_pizza(some_user)
    expect(httpretty.has_request()).to.be.true

    httpretty.reset()
    order_pizza(some_user, home_delivery=False)
    expect(httpretty.has_request()).to.be.false

checking if is enabled

httpretty.enable()
httpretty.is_enabled().should.be.true

httpretty.disable()
httpretty.is_enabled().should.be.false

raising an error if an unregistered endpoint is requested

import urllib2
import httpretty

httpretty.enable()
httpretty.HTTPretty.allow_net_connect = False

httpretty.register_uri(httpretty.GET, 'http://www.google.com', body='OK')

urllib2.urlopen('http://www.google.com')
urllib2.urlopen('http://www.reddit.com') # raises httpretty.errors.UnmockedError