sanic/docs/testing.md

Testing

Sanic endpoints can be tested locally using the sanic.utils module, which depends on the additional aiohttp library. The sanic_endpoint_test function runs a local server, issues a configurable request to an endpoint, and returns the result. It takes the following arguments:

• app An instance of a Sanic app.
• method (default 'get') A string representing the HTTP method to use.
• uri (default '/') A string representing the endpoint to test.
• gather_request (default True) A boolean which determines whether the original request will be returned by the function. If set to True, the return value is a tuple of (request, response), if False only the response is returned.
• loop (default None) The event loop to use.
• debug (default False) A boolean which determines whether to run the server in debug mode.

The function further takes the *request_args and **request_kwargs, which are passed directly to the aiohttp ClientSession request. For example, to supply data with a GET request, method would be get and the keyword argument params={'value', 'key'} would be supplied. More information about the available arguments to aiohttp can be found in the documentation for ClientSession.

Below is a complete example of an endpoint test, using pytest. The test checks that the /challenge endpoint responds to a GET request with a supplied challenge string.

import pytest
import aiohttp
from sanic.utils import sanic_endpoint_test

# Import the Sanic app, usually created with Sanic(__name__)
from external_server import app

def test_endpoint_challenge():
    # Create the challenge data
    request_data = {'challenge': 'dummy_challenge'}

    # Send the request to the endpoint, using the default `get` method
    request, response = sanic_endpoint_test(app,
                                            uri='/challenge',
                                            params=request_data)

    # Assert that the server responds with the challenge string
    assert response.text == request_data['challenge']

Previous: Custom protocols

Next: Sanic extensions