Writing tests for RESTful APIs in Python using requests – part 4: mocking responses

In this short series of blog posts, I want to explore the Python requests library and how it can be used for writing tests for RESTful APIs. This is the fourth blog post in the series, in which we will cover working mocking responses for unit testing purposes. Previous blog posts in this series talked about getting started with requests and pytest, about creating data driven tests and about working with XML-based APIs.

One thing that has been keeping me busy in the last couple of months is improving my software development skills. I’m currently working on a Python development project, and one of the tasks of a developer is writing good unit tests. When I was writing these tests, I ran into a challenge when I wanted to test a method that involves communicating with a REST API using the requests library.

Obviously, I don’t want to have to invoke the API itself in my unit tests, so I was looking for a way to mock out that dependency instead. One thing I considered was writing mocks for the API myself, until I stumbled upon the responses library (PyPI, GitHub). According to their homepage, this is ‘A utility library for mocking out the requests Python library’. Exactly what I was looking for.

So, what can you do with the responses library, and how can you use to your advantage when you’re writing unit tests? Let’s look at a couple of examples that involve creating mock responses for the Zippopotam.us API.

Creating a mock response
Let’s say that in our unit test, we want to test that our code handles an HTTP 404 returned by a REST API dependency as expected. This implies we need a way to ‘override’ the actual API response with a response that contains an HTTP 404 status code, and (maybe) a response body with an error message.

To use the responses library to create such a mock response, you’ll first have to add the @responses.activate decorator to your test method. In the test method body, you can then add a new mock response as follows:

@responses.activate
def test_simulate_data_cannot_be_found():
    responses.add(
        responses.GET,
        'http://api.zippopotam.us/us/90210',
        json={"error": "No data exists for US zip code 90210"},
        status=404
    )

When you use the requests library to perform an HTTP GET to http://api.zippopotam.us/us/90210, instead of the response from the live API (which will return an HTTP 200), you’ll receive the mock response, instead, which we can confirm like this:

response = requests.get('http://api.zippopotam.us/us/90210')
assert response.status_code == 404
response_body = response.json()
assert response_body['error'] == 'No data exists for US zip code 90210'

You can add any number of mock responses in this way.

Unmapped responses
If, during testing, you accidentally hit an endpoint that does not have an associated mock response, you’ll get a ConnectionError:

@responses.activate
def test_unmatched_endpoint_raises_connectionerror():
    with pytest.raises(ConnectionError):
        requests.get('http://api.zippopotam.us/us/12345')

Simulating an exception being thrown
If you want to test how your code handles an exception being thrown when you perform an API call using requests, you can do that using responses, too:

@responses.activate
def test_responses_can_raise_error_on_demand():
    responses.add(
        responses.GET,
        'http://api.zippopotam.us/us/99999',
        body=RuntimeError('A runtime error occurred')
    )

You can confirm that this works as expected by asserting on the behaviour in a test:

with pytest.raises(RuntimeError) as re:
    requests.get('http://api.zippopotam.us/us/99999')
assert str(re.value) == 'A runtime error occurred'

Creating dynamic responses
If you want to generate more complex and/or dynamic responses, you can do that by creating a callback and using that in your mock. This callback should return a tuple containing the response status code (an integer), the headers (a dictionary) and the response (in a string format).

In this example, I want to parse the request URL, extract the path parameters from it and then use those values in a message I return in the response body:

@responses.activate
def test_using_a_callback_for_dynamic_responses():

    def request_callback(request):
        request_url = request.url
        resp_body = {'value': generate_response_from(request_url)}
        return 200, {}, json.dumps(resp_body)

    responses.add_callback(
        responses.GET, 'http://api.zippopotam.us/us/55555',
        callback=request_callback,
        content_type='application/json',
    )

def generate_response_from(url):
    parsed_url = urlparse(url).path
    split_url = parsed_url.split('/')
    return f'You requested data for {split_url[1].upper()} zip code {split_url[2]}'

Again, writing a test confirms that this works as expected:

response = requests.get('http://api.zippopotam.us/us/55555')
assert response.json() == {'value': 'You requested data for US zip code 55555'}

Plus, responses retains all calls made to the callback and the responses it returned, which is very useful when you want to verify that your code made the correct (number of) calls:

assert len(responses.calls) == 1
assert responses.calls[0].request.url == 'http://api.zippopotam.us/us/55555'
assert responses.calls[0].response.text == '{"value": "You requested data for US zip code 55555"}'

Using the examples for yourself
The code examples I have used in this blog post can be found on my GitHub page. If you download the project and (given you have installed Python properly) run

pip install -r requirements.txt

from the root of the python-requests project to install the required libraries, you should be able to run the tests for yourself. See you next time!

Why I think unit testing is the basis of any solid automation strategy

In a recent blog post I talked about why and how I still use the test automation pyramid as a model to talk about different levels of test automation and how to combine them into an automation strategy that fits your needs. In this blog post I’d like to talk about the basis of the pyramid a little more: unit tests and unit testing. There’s a reason -or better, there are a number of reasons- why unit testing forms the basis of any solid automation strategy, and why it’s depicted as the broadest layer in the pyramid.

Unit tests are fast
Even though end-to-end testing using tools like Selenium is the first thing a lot of people think about when they hear the term ‘test automation’, Selenium tests are actually the hardest and most time-intensive to write, run and maintain. Unit tests, on the other hand, can be written fast, both in absolute time it takes to write unit test code as well as relative to the progress of the software development process. A very good example of the latter is the practice of Test Driven Development (TDD), where tests are written before the actual production code is created.

Unit tests are also fast to run. Their run time is typically in the milliseconds range, where integration and end-to-end tests take seconds or even minutes, depending on your test and their scope. This means that a solid set of unit tests will give you feedback on specific aspects of your application quality much faster than those other types of tests. I stressed ‘specific aspects’, because while unit tests can cover ground in relatively little time, there’s only so much they can do. As goes for automation as a whole.

Unit tests require (and enforce) code testability
Any developer can tell you that the better structured code is, the easier it is to isolate specific classes and methods and write unit tests for them, mocking away all dependencies that method or class requires. This is referred to as highly testable code. I’ve worked in projects where people were stuck with badly testable code and have seen the consequences. I’ve facilitated two day test automation hackathon where the end goal was to write a single unit test and integrate it into the Continuous Integration pipeline. Writing the test took ten minutes. Untangling the existing code so that the unit test could be written? Two days MINUS ten minutes.

This is where practices like TDD can help. When you’ve got your tests in place before the production code that lets the tests pass is written, the risk of that production code becoming untestable spaghetti code is far lower. And having testable code is a massive help with the next reason why unit testing should be the basis of your automation efforts.

Unit tests prevent outside in test automation (hopefully)
If you’re code is testable, it means that it’s far easier to write unit tests for it. Which in turn means that the likelihood that unit tests are actually written increases as well. And where unit tests are written consistently and visibly, the risk that everything and its mother it tested through the user interface (a phenomenon I’ve seen referred to as ‘outside-in test automation’) is far less high. Just writing lots of unit tests is not enough, though, their scope, intent and coverage should be clear to the team as well (so, testers, get involved!).

Unit tests are a safety net for code refactoring
Let’s face it: your production code isn’t going to live unchanged forever (although I’ve heard about lines of COBOL that are busy defying this). Changes to the application, renewed libraries or insights, all of these will in time be reason to refactor your existing code to improve effectivity, readability, maintainability or just to keep things running. This is where a decent set of unit tests helps a lot, since they can be used as a safety net that can give you feedback about the consequences of your refactoring efforts on overall application functionality. And even more importantly, they do this quickly. Developers are humans, and will move on to different tasks if they need to wait hours for feedback. With unit tests, that feedback arrives in seconds, keeping them and you both focused and on the right track.

In the end, unit tests can, will and need not replace integration and end-to-end tests, of course. There’s a reason all of them are featured in the test automation pyramid. But when you’re trying to create or improve your test automation strategy, I’d advise you to start with the basis and get your unit testing in place.

By the way, for those of you reading this on the publication date, I’d like to mention that I’ll be co-hosting a webinar with the folks at Testim, where I’ll be talking about the importance of unit testing, as well as much more with regards to test automation strategy. I hope to see you there! If you’re reading this at a later date, I’ll add a link to the recording as soon as it’s available.

On crossing the bridge into unit testing land

Maybe it’s just the people and organizations I meet and work with, but no matter how active they’re trying to implement automation and involve testers therein, there’s one bridge that’s often too far for those that are tasked with test automation, and that’s the bridge to unit testing land. When asking them for the reasons that testers aren’t involved in unit testing, I typically get one (or more, or all) of the following answers:

  • ‘That’s the responsibility of our developers’
  • ‘I don’t know how to write unit tests’
  • ‘I’m already busy with other types of automation and I don’t have time for that’

While these answers might sound perfectly reasonable to some, I think there’s something inherently wrong with all of them. Let’s take a look:

  • With more and more teams becoming multidisciplinary, we can’t simply shift responsibility for any task to a specific subgroup. If ‘we’ (i.e., the testers) keep saying that unit testing is a developer’s responsibility, we’ll never get rid of the silos we’re trying to break down.
  • While you might not know how to actually write unit tests yourself, there’s a lot you CAN do to contribute to their value and effectiveness. Try reviewing them, for example: has the developer of the unit test missed some obvious cases?
  • Not having time to concern yourself with unit testing reminds me of the picture below. Really, if something can be covered with a decent set of unit tests, there really is no need to write integration or even (shudder) end-to-end tests for it.

Are you too busy to pay attention to unit testing?

I’m not a devotee of the test automation pyramid per se, but there IS a lot of truth to the concept that a decent set of unit tests should be the foundation of every solid test automation effort. Unit tests are relatively easy to write (even though it might not look that way to some), they run fast (no need for waiting until web pages are loaded and complete their client-side processing, for example..) and therefore they’re the best way to provide that fast feedback that development teams are looking for those in this age of Continuous Integration / Delivery / Deployment / Testing / Everything / … .

To put it in even bolder terms, as a tester, I think you have the responsibility of familiarizing yourself with the unit testing activities that your development team is undertaking. Offer to review them. Try to understand what they do, what they check and where coverage could be improved. Yes, this might require you to actually talk to your developers! But it’ll be worth it, not just to you, but to the whole team and, in the end, also to your product and your customers. Over time, you might even write some unit tests yourself, though, again, that’s not a necessity for you to provide value in the land of unit testing. Plus, you’ll likely learn some new tricks and skills by doing so, and that’s always a good thing, right?

For those of you looking for another take on this subject, John Ruberto wrote an article called ‘100 percent unit test coverage is not enough‘, which was published on StickyMinds. A highly recommended read.

P.S.: Remember Tesults, the SaaS solution for storing and displaying test results I wrote about a couple of months ago? The people behind Tesults recently let me know they now offer a free forever plan as well. So if you were interested in using their services but could not afford or justify the investment, it might be a good idea to check their new plan out here. And again, I am in no way, shape or form associated with, nor do I have a commercial interest in Tesults as an organization or a product. I still think it’s a great platform, though.