Tutorial

If you haven’t worked with this library yet, this document is for you.

Writing your first test

With pytest-httpserver, a test looks like this:

import requests


def test_json_client(httpserver: HTTPServer):
    httpserver.expect_request("/foobar").respond_with_json({"foo": "bar"})
    assert requests.get(httpserver.url_for("/foobar")).json() == {"foo": "bar"}

In the first line of the code, we are setting up an expectation. The expectation contains the http request which is expected to be made:

httpserver.expect_request("/foobar")

This code tells that the httpserver, which is started automatically and running on localhost, should accept the request “http://localhost/foobar”. Configuring how to handle this request is then done with the following method:

respond_with_json({"foo": "bar"})

This tells that when the request arrives to the http://localhost/foobar URL, it must respond with the provided json. The library accepts here any python object which is json serializable. Here, a dict is provided.

Note

It is important to specify what response to be sent back to the client otherwise pytest-httpserver will error with Matching request handler found but no response defined message on an incoming request.

In the next line, an http request is sent with the requests library:

assert requests.get(httpserver.url_for("/foobar")).json() == {"foo": "bar"}

There’s no customization (such as mocking) to be made. You don’t need to figure out the port number where the server is running, as there’s the url_for() method provided to format the URL.

As you can see there are two different part of the httpserver configuration:

setting up what kind of request we are expecting
telling how the request should be handled and which content should be responded.

Important note on server port number

The test should be run with an unprivileged user. As it is not possible to bind to the default http port (80), the library binds the server to an available port which is higher than 1024. In the examples on this page when we are referring to the url http://localhost/… it is assumed that the url contains the http port also.

It is advised to use the url_for() method to construct an URL as it will always contain the correct port number in the URL.

If you need the http port as an integer, you can get it by the port attribute of the httpserver object.

How to test your http client

Note

This section describes the various ways of http client testing. If you are sure that pytest-httpserver is the right library for you, you can skip this section.

You’ve written your first http client application and you want to write a test for it. You have the following options:

Test your application against the production http server
Mock your http calls, so they won’t reach any real server
Run a fake http server listening on localhost behaving like the real http server

pytest-httpserver provides API for the 3rd option: it runs a real http server on localhost so you can test your client connecting to it.

However, there’s no silver bullet and the possibilities above have their pros and cons.

Test your application against the production http server

Pros:

It needs almost no change in the source code and you can run the tests with no issues.
Writing tests is simple.

Cons:

The tests will use a real connection to the real server, it will generate some load on the server, which may be acceptable or not. If the real server is down or you have some connectivity issue, you can’t run tests.
If the server has some state, for example, a backend database with user data, authentication, etc, you have to solve the shared resource problem if you want to allow multiple test runnings on different hosts. For example, if there are more than one developers and/or testers.
Ensuring that there’s no crosstalk is very important: if there’s some change made by one instance, it should be invisible to the other. It should either revert the changes or do it in a separate namespace which will be cleaned up by some other means such as periodic jobs. Also, the test should not have inconsistent state behind.

Mock your http calls, so they won’t reach any real server

Pros:

It needs almost no change in the source code and you can run the tests with no issues.
There are excellent libraries supporting mocking such as responses and pytest-vcr.
No need to ensure crosstalk or manage shared resources.
Tests work offline.

Cons:

No actual http requests are sent. It needs great effort to mock the existing behavior of the original library (such as requests) and you need to keep the two libraries in sync.
Mocking must support the http client library of your choice. Eg. if you use requests you need to use responses. If you are using different libraries, the complexity raises.
At some point, it is not like black-box testing as you need to know the implementation details of the original code.
It is required to set up the expected requests and their responses. If the server doesn’t work like your setup, the code will break when it is run with the real server.

Run a fake http server listening on localhost

Pros:

Writing tests is simple.
No need to ensure crosstalk or manage shared resources.
Tests work offline.
Actual http requests are sent. There’s a real http server running speaking http protocol so you can test all the special cases you need. You can customize every http request expectations and their responses to the end.
Testing connectivity issues is possible.
There’s no mocking, no code injection or class replacement.
It is black-box testing as there’s no need to know anything about the original code.

Cons:

Some code changes required in the original source code. The code should accept the server endpoint (host and port) as a parameter or by some means of configuration. This endpoint will be set to localhost during the test running. If it is not possible, you need to tweak name resolution.
It is required to set up the expected requests and their responses. If the server doesn’t work like your setup, the code will break when it is run with the real server.
Setting up TLS/SSL requires additional knowledge (cert generation, for example)

Specifying the expectations and constraints

In the above code, the most simple case was shown. The library provides many ways to customize the expectations.

In the example above, the code expected a request to /foobar with any method (such as GET, PUT, POST, DELETE). If you want to limit the method to the GET method only, you can specify:

httpserver.expect_request("/foobar", method="GET")

Similarly, specifying the query parameters is possible:

httpserver.expect_request("/foobar", query_string="user=user1", method="GET")

This will match the GET request made to the http://localhost/foobar?user=user1 URL. If more constraint is specified to the expect_request() method, the expectation will be narrower, eg. it is similar when using logical AND.

If you want, you can specify the query string as a dictionary so the order of the key-value pairs does not matter:

httpserver.expect_request(
    "/foobar", query_string={"user": "user1", "group": "group1"}, method="GET"
)

Similar to query parameters, it is possible to specify constraints for http headers also.

For many parameters, you can specify either string or some expression (such as the dict in the example above).

For example, specifying a regexp pattern for the URI Is also possible by specifying a compiled regexp object:

httpserver.expect_request(
    re.compile("^/foo"), query_string={"user": "user1", "group": "group1"}, method="GET"
)

The above will match every URI starting with “/foo”.

All of these are documented in the API documentation.

Specifying responses

Once you have set up the expected request, it is required to set up the response which will be returned to the client.

In the example we used respond_with_json() but it is also possible to respond with an arbitrary content.

respond_with_data("Hello world!", content_type="text/plain")

In the example above, we are responding a text/plain content. You can specify the status also:

respond_with_data("Not found", status=404, content_type="text/plain")

With this method, it is possible to set the response headers, mime type.

In some cases you need to create your own Response instance (which is the Response object from the underlying werkzeug library), so you can respond with it. This allows more customization, however, in most cases the respond_with_data is sufficient:

respond_with_response(Response("Hello world!"))
# same as
respond_with_data("Hello world!")

If you need to produce dynamic content, use the respond_with_handler method, which accepts a callable (eg. a python function):

def my_handler(request):
    # here, examine the request object
    return Response("Hello world!")


respond_with_handler(my_handler)

Ordered and oneshot expectations

In the above examples, we used expect_request() method, which registered the request to be handled. During the test running you can issue requests to this endpoint as many times as you want, and you will get the same response (unless you used the respond_with_handler() method, detailed above).

There are two other additional limitations which can be used:

ordered handling, which specifies the order of the requests
oneshot handling, which specifies the lifetime of the handlers for only one request

Ordered handling

The ordered handling specifies the order of the requests. It must be the same as the order of the registration:

def test_ordered(httpserver: HTTPServer):
    httpserver.expect_ordered_request("/foobar").respond_with_data("OK foobar")
    httpserver.expect_ordered_request("/foobaz").respond_with_data("OK foobaz")

    requests.get(httpserver.url_for("/foobar"))
    requests.get(httpserver.url_for("/foobaz"))

The above code passes the test running. The first request matches the first handler, and the second request matches the second one.

When making the requests in a reverse order, it will fail:

def test_ordered(httpserver: HTTPServer):
    httpserver.expect_ordered_request("/foobar").respond_with_data("OK foobar")
    httpserver.expect_ordered_request("/foobaz").respond_with_data("OK foobaz")

    requests.get(httpserver.url_for("/foobaz"))
    requests.get(httpserver.url_for("/foobar"))  # <- fail?

If you run the above code you will notice that no test failed. This is because the http server is running in its own thread, separately from the client code. It has no way to raise an assertion error in the client thread.

However, this test checks nothing but runs two subsequent queries and that’s it. Checking the http status code would make it fail:

def test_ordered(httpserver: HTTPServer):
    httpserver.expect_ordered_request("/foobar").respond_with_data("OK foobar")
    httpserver.expect_ordered_request("/foobaz").respond_with_data("OK foobaz")

    assert requests.get(httpserver.url_for("/foobaz")).status_code == 200
    assert requests.get(httpserver.url_for("/foobar")).status_code == 200  # <- fail!

For further details about error handling, please read the Handling test errors chapter.

Oneshot handling

Oneshot handling is useful when you want to ensure that the client makes only one request to the specified URI. Once the request is handled and the response is sent, the handler is no longer registered and a further call to the same URL will be erroneous.

def test_oneshot(httpserver: HTTPServer):
    httpserver.expect_oneshot_request("/foobar").respond_with_data("OK")

    requests.get(httpserver.url_for("/foobar"))
    requests.get(httpserver.url_for("/foobar"))  # this will get http status 500

If you run the above code you will notice that no test failed. This is because the http server is running in its own thread, separately from the client code. It has no way to raise an assertion error in the client thread.

However, this test checks nothing but runs two subsequent queries and that’s it. Checking the http status code would make it fail:

def test_oneshot(httpserver: HTTPServer):
    httpserver.expect_oneshot_request("/foobar").respond_with_data("OK")

    assert requests.get(httpserver.url_for("/foobar")).status_code == 200
    assert requests.get(httpserver.url_for("/foobar")).status_code == 200  # fail!

For further details about error handling, please read the Handling test errors chapter.

Handling test errors

If you look at carefully at the test running, you realize that the second request (and all further requests) will get an http status 500 code, explaining the issue in the response body. When a properly written http client gets http status 500, it should raise an exception, which will be unhandled and in the end the test will be failed.

In some cases, however, you want to make sure that everything is ok so far, and raise AssertionError when something is not good. Call the check_assertions() method of the httpserver object, and this will look at the server’s internal state (which is running in the other thread) and if there’s something not right (such as the order of the requests not matching, or there was a non-matching request), it will raise an AssertionError and your test will properly fail:

def test_ordered_ok(httpserver: HTTPServer):
    httpserver.expect_ordered_request("/foobar").respond_with_data("OK foobar")
    httpserver.expect_ordered_request("/foobaz").respond_with_data("OK foobaz")

    requests.get(httpserver.url_for("/foobaz"))
    requests.get(httpserver.url_for("/foobar"))  # gets 500

    httpserver.check_assertions()  # this will raise AssertionError and make the test failing

The server writes a log about the requests and responses which were processed. This can be accessed in the log attribute of the http server. This log is a python list with 2-element tuples (request, response).

Server lifetime

Http server is started when the first test uses the httpserver fixture, and it will be running for the rest of the session. The server is not stopped and started between the tests as it is an expensive operation, it takes up to 1 second to properly stop the server.

To avoid crosstalk (eg one test leaving its state behind), the server’s state is cleaned up between test runnings.

Debugging

If you having multiple requests for the server, adding the call to check_assertions() may to debug as it will make the test failed as soon as possible.

import requests


def test_json_client(httpserver: HTTPServer):
    httpserver.expect_request("/foobar").respond_with_json({"foo": "bar"})
    requests.get(httpserver.url_for("/foo"))
    requests.get(httpserver.url_for("/bar"))
    requests.get(httpserver.url_for("/foobar"))

    httpserver.check_assertions()

In the above code, the first request (to /foo) is not successful (it gets http status 500), but as the response status is not checked (or any of the response), and there’s no call to check_assertions(), the test continues the running. It gets through the /bar request, which is also not successful (and gets http status 500 also like the first one), then goes the last request which is successful (as there’s a handler defined for it)

In the end, when checking the check_assertions() raise the error for the first request, but it is a bit late: figuring out the request which caused the problem could be troublesome. Also, it will report the problem for the first request only.

Adding more call of check_assertions() will help.

import requests


def test_json_client(httpserver: HTTPServer):
    httpserver.expect_request("/foobar").respond_with_json({"foo": "bar"})
    requests.get(httpserver.url_for("/foo"))
    httpserver.check_assertions()

    requests.get(httpserver.url_for("/bar"))
    httpserver.check_assertions()

    requests.get(httpserver.url_for("/foobar"))
    httpserver.check_assertions()

In the above code, the test will fail after the first request.

In case you do not want to fail the test, you can use any of these options:

assertions attribute of the httpserver object is a list of the known errors. If it is non-empty, then there was an issue.
format_matchers() method of the httpserver object returns which handlers have been registered to the server. In some cases, registering non-matching handlers causes the problem so printing this string can help to diagnose the problem.

Advanced topics

This is the end of the tutorial, however, not everything is covered here and this library offers a lot more.