{ "componentChunkName": "component---src-templates-post-page-js", "path": "/2018/testing-aiohttp-client", "result": {"data":{"site":{"siteMetadata":{"title":"Solid Abstractions","siteUrl":"https://solidabstractions.com","twitterId":291334023,"author":{"fullName":"Julien Hartmann","profileHtml":"I am an open-source de­vel­op­er, for­mer IT con­sul­tant with a pas­sion for new tech­nol­o­gies. I be­lieve the role of an en­gi­neer is to em­pow­er peo­ple, by as­sem­bling sim­ple, re­fined de­signs.\n","links":[{"url":"https://github.com/spectras/","name":"github","title":"GitHub"},{"url":"https://stackoverflow.com/users/3212865/spectras","name":"stackoverflow","title":"StackOverflow"},{"url":"https://www.linkedin.com/in/julienhartmann/","name":"linkedin","title":"LinkedIn"}],"profilePicNode":{"original":{"src":"/static/profile-pic-301a9cbe7b572c3e7910c9717d2b3bcd.jpg"}},"url":"https://etherdream.org/about"}}},"markdownRemark":{"id":"7b9125bb-dffa-5cdf-8139-abb5a2951dd7","excerpt":"Asynchronous code is the new paradigm in python those last years.\nTesting it, though, is significantly harder.\nLet's see how to test asynchronous HTTP client code written with aiohttp.","html":"

Asynchronous code is the new paradigm in python those last years.\nTesting it, though, is significantly harder.\nLet's see how to test asynchronous HTTP client code written with aiohttp.

\n

--- excerpt ---

\n

Asynchronous code is the new paradigm in python those last years. Leveraging coroutine\nsupport to write asynchronous code in a non-blocking fashion is very convenient.

\n

But it opens up a whole new uncharted territory. Testing, notably, is\nsignificantly harder: exceptions might go unnoticed, unit tests might end without\nwaiting for all asynchronous code to complete, and so on.

\n

It does, however, enable interesting new techniques for testing. In this article, we\nshall test asynchronous client-side code written using the amazing aiohttp.\nWe will do this in two parts:

\n
\n
    \n
  1. Testing tools (this post).
    2. \n
  2. Actual implementation.
    3. \n
\n
\n

Objectives

\n

Fetching bitcoin price

\n

So here are our requirements: we would like to fetch the latest bitcoin price from\nKraken exchange, using the following\ninterface:

\n
class QuotationProvider:\n    async def get_price(self, pair):\n        ''' Get latest trade price for given pair.\n        Args:\n            pair (str): name of a pair symbol on exchange.\n        Returns:\n            Decimal: latest price for the symbol.\n        Raises:\n            PayloadError: if server response could not be understood.\n            QuotationError: if quotation is not available.\n            ValueError: if `pair` is not a valid pair symbol.\n        '''\n\nclass QuotationError(Exception): pass\nclass PayloadError(QuotationError): pass
Interface definition
\n

Here is the expected use, assuming we built a Kraken class that implements\nthe above interface:

\n
>>> xchg = Kraken(session=aiohttp.ClientSession())\n>>> await xchg.get_price('btcusd')\nDecimal('3967.40000')
Example session using apython interpreter.
\n

Simple enough, right? Now, before we dive into code, how do we ensure it works fine?\nOr:
How do we test it properly?

\n

Testing goals

\n

Our final goal for this post is to unit-test this quotation client thoroughly and cleanly.\nWhat does that mean? It means we want our tests to be:

\n
Isolated

Testing must not depend on external resources. In particular, tests must not\nperform actual requests against Kraken's servers.

Faithful

Test cases should be as close as possible to real-world conditions. We want to\nstrive for behavioral testing, rather than checking implementation details.

This means we want to setup an actual HTTP server for the tests to interact with tested code,\nunder the control of the test case. The good news is with asyncio, we can actually run\none from within the test.

Comprehensive

In particular, we want to test error conditions and security features. Namely,\nwe want to test that we will not accept data from a server that has an invalid SSL\ncertificate. This implies our tests cannot circumvent the SSL layer.

Unintrusive

We want to test the actual code, not modify or patch it for testing, as this could\nhide bugs. In particular, if the client code uses URIs, we are not allowed to\nreach in and alter them.

\n

Lastly, we will aim at making tests as convenient to write as possible. Most developers\nhate writing tests, and lowering the barrier is a reasonable way to encourage a\nmore comprehensive test suite.

\n

Test support tools

\n

Checking out included batteries

\n

The aiohttp library provides a basic\ntesting toolset.\nIt allows setting up a test webapp, creating a server instance to serve it, and optionally\nrunning it asynchronously in the background. For instance:

\n
@pytest.mark.asyncio\ndef test_example():\n    app = aiohttp.web.Application()\n    async def handler(request):\n        return aiohttp.web.Response(text=SAMPLE_RESPONSE_FROM_KRAKEN)\n    app.router.add_route('get', '/0/public/Ticker', handler)\n\n    server = aiohttp.test_utils.TestServer(app)\n    async with server:\n        kraken = Kraken(server='localhost', port=server.port)\n        price = await kraken.get_price('btcusd')\n        assert price == Decimal('3602.20000')
\n

This starts a test server on localhost that sends back a JSON hello message when\nqueried for /hello. This is all nice and well, but it falls short in several ways:

\n\n

Let's build a better infrastructure for our tests.

\n

Handling requests in test cases

\n

The idea is simple: the test case is an asynchronous task. The test server is an\nasynchronous task as well. We should be able to use inter-task communication tools\nto have the server delegate request processing back to the test server.

\n
\"Client
Client request/response sequence under testcase control.
\n

Let's implement this workflow. We extend aiohttp's RawTestServer\nand provide our own request handler. This is the main idea: instead of\nhandling the request, the handler pushes it to a queue and waits\nfor the test case to provide the response.

\n
class CaseControlledTestServer(aiohttp.test_utils.RawTestServer):\n    def __init__(self, **kwargs):\n        super().__init__(self._handle_request, **kwargs)\n        self._requests = asyncio.Queue()\n        self._responses = {}                # {id(request): Future}\n\n    async def close(self):\n        ''' cancel all pending requests before closing '''\n        for future in self._responses.values():\n            future.cancel()\n        await super().close()\n\n    async def _handle_request(self, request):\n        ''' push request to test case and wait until it provides a response '''\n        self._responses[id(request)] = response = asyncio.Future()\n        self._requests.put_nowait(request)\n        try:\n            # wait until test case provides a response\n            return await response\n        finally:\n            del self._responses[id(request)]\n\n    async def receive_request(self):\n        ''' wait until test server receives a request '''\n        return await self._requests.get()\n\n    def send_response(self, request, *args, **kwargs):\n        ''' send web response from test case to client code '''\n        response = aiohttp.web.Response(*args, **kwargs)\n        self._responses[id(request)].set_result(response)
\n

Two things deserve an explanation:

\n\n

Using our CaseControlledTestServer, we can rewrite the previous example like this:

\n
@pytest.mark.asyncio\ndef test_example():\n    async with CaseControlledTestServer() as server:\n        kraken = Kraken(server='localhost', port=server.port)\n\n        task = asyncio.create_task(kraken.get_price('btcusd'))\n        request = await server.receive_request()\n        assert request.path_qs == '/0/public/Ticker?pair=XXBTZUSD'\n\n        server.send_response(request, text=SAMPLE_RESPONSE_FROM_KRAKEN)\n        price = await task\n        assert price == Decimal('3602.20000')
\n

Much better already. Notice how linear the test case has become? The test\ncase walks through the steps of the asynchronous workflow, and gets access\nto the request object, which allows checking it, eg: veryfing the query string,\nor ensuring some header is present.

\n

Let's now fix the uri redirection we have ignored so far.

\n

Rerouting network accesses

\n

Up to this point, we have been manually providing server address and port to\nour client code. This scheme is inherently wrong though, as it breaks encapsulation:\nas it is, every single part of our project that needs to build a Kraken instance\nmust know the official server address and port.

\n

Let's fix this.

\n

Global state in aiohttp is cleanly wrapped in a ClientSession\nobject. That objects holds connection pools, settings, a cookie database, etc.\nThen, all classes that use aiohttp accept a ClientSession object at\nconstruction (as a dependency injection). This makes it easy to share resources\namong components or isolate them depending on desired behavior.

\n

The interesting part is ClientSession does not know how to access the network.\nThis is all abstracted out in a connector, which is injected into the session at\ncreation: “here, anytime you need network access, use this connector”.

\n

We are thus interested in altering the TCP connector, an instance of class\naiohttp.TCPConnector. Digging deeper, we can see that in turn,\nthat connector delegates address resolution to a resolver object.

\n

This is our target: we will provide a custom resolver that resolves tested addresses\nto local test servers and purposefully fail all other addresses, ensuring no\nconnection can be made to other servers.

\n

Let's write the resolver first:

\n
class FakeResolver:\n    def __init__(self):\n        self._servers = {}\n\n    def add(self, host, port, target_port):\n        self._servers[host, port] = target_port\n\n    async def resolve(self, host, port=0, family=socket.AF_INET):\n        try:\n            fake_port = self._servers[host, port]\n        except KeyError:\n            raise OSError('No test server known for %s' % host)\n        return [{\n            'hostname': host,\n            'host': '127.0.0.1',\n            'port': fake_port,\n            'family': socket.AF_INET,\n            'proto': 0,\n            'flags': socket.AI_NUMERICHOST,\n        }]
\n

Straightforward: we record added test servers, and resolve raises an OSError if\nrequested address does not match a known test server.

\n

Now we want to inject our resolver into a connector and make it conveniently\navailable within a test-scoped ClientSession instance. A perfect use case for building\na fixture:

\n
_RedirectContext = namedtuple('RedirectContext', 'add_server session')\n\n@pytest.fixture\nasync def aiohttp_redirector():\n    resolver = FakeResolver()\n    connector = aiohttp.TCPConnector(resolver=resolver, use_dns_cache=False)\n    async with aiohttp.ClientSession(connector=connector) as session:\n        yield _RedirectContext(add_server=resolver.add, session=session)
\n

We can now use our fixture in our testcase example:

\n
@pytest.mark.asyncio\ndef test_example(aiohttp_redirector):\n    async with CaseControlledTestServer() as server:\n        aiohttp_redirector.add_server('api.kraken.com', 80, server.port)\n        kraken = Kraken(session=aiohttp_redirector.session)\n        #\n        # --- rest is unchanged ---\n        #
\n

Our Kraken class holds the knowledge of what it should connect to, and our\ntests uses a custom resolver to direct those connections to the test server.\nWe no longer break encapsulation.

\n

Recap

\n

In this first part, we have created our testing infrastructure.

\n\n

In the next post, we will use our testing infrastructure\nto test and develop our Kraken feed.

","fields":{"isPage":false,"slug":"/2018/testing-aiohttp-client"},"frontmatter":{"title":"Unit Testing aiohttp Clients","classname":null,"date":"2018-11-25T00:00:00.000Z","formattedDate":"November 25, 2018","isoDate":"2018-11-25T00:00:00+00:00"},"headings":[{"value":"Objectives","depth":1},{"value":"Fetching bitcoin price","depth":2},{"value":"Testing goals","depth":2},{"value":"Test support tools","depth":1},{"value":"Checking out included batteries","depth":2},{"value":"Handling requests in test cases","depth":2},{"value":"Rerouting network accesses","depth":2},{"value":"Recap","depth":1}],"image":null,"series":{"name":"python","fullName":null,"fields":{"slug":"/python"}},"tags":[{"name":"code","slug":"/tag/code"},{"name":"testing","slug":"/tag/testing"}]}},"pageContext":{"series":"python","slug":"/2018/testing-aiohttp-client","previous":{"fields":{"slug":"/2018/cryptomate/other-strategy-ports"},"frontmatter":{"title":"Other Strategy Ports","series":"cryptomate"},"tags":[{"name":"architecture","slug":"/tag/architecture"},{"name":"ports","slug":"/tag/ports"}]},"next":{"fields":{"slug":"/2018/testing-aiohttp-client-part-2"},"frontmatter":{"title":"Unit Testing aiohttp Clients - part 2","series":"python"},"tags":[{"name":"code","slug":"/tag/code"},{"name":"testing","slug":"/tag/testing"}]},"seriesPrevious":{"fields":{"slug":"/2018/starting-python-project"},"frontmatter":{"title":"Starting a Python Project","series":"python"},"tags":[{"name":"code","slug":"/tag/code"}]},"seriesNext":{"fields":{"slug":"/2018/testing-aiohttp-client-part-2"},"frontmatter":{"title":"Unit Testing aiohttp Clients - part 2","series":"python"},"tags":[{"name":"code","slug":"/tag/code"},{"name":"testing","slug":"/tag/testing"}]}}}, "staticQueryHashes": ["1733002695","4006707078"]}