Testing#

Testing is a first class citizen in Starlite, which offers several powerful testing utilities out of the box.

Creating a test app#

Starlite also offers a helper function called create_test_client which first creates an instance of Starlite and then a test client using it. There are multiple use cases for this helper - when you need to check generic logic that is decoupled from a specific Starlite app, or when you want to test endpoints in isolation.

You can pass to this helper all the kwargs accepted by the starlite constructor, with the route_handlers kwarg being required. Yet unlike the Starlite app, which expects route_handlers to be a list, here you can also pass individual values.

For example, you can do this:

my_app/tests/test_health_check.py#

from starlite.status_codes import HTTP_200_OK
from starlite.testing import create_test_client

from my_app.main import health_check


def test_health_check():
    with create_test_client(route_handlers=[health_check]) as client:
        response = client.get("/health-check")
        assert response.status_code == HTTP_200_OK
        assert response.text == "healthy"

But also this:

my_app/tests/test_health_check.py#

from starlite.status_codes import HTTP_200_OK
from starlite.testing import create_test_client

from my_app.main import health_check


def test_health_check():
    with create_test_client(route_handlers=health_check) as client:
        response = client.get("/health-check")
        assert response.status_code == HTTP_200_OK
        assert response.text == "healthy"

RequestFactory#

Another helper is the RequestFactory class, which creates instances of starlite.connection.request.Request. The use case for this helper is when you need to test logic that expects to receive a request object.

For example, lets say we wanted to unit test a guard function in isolation, to which end we’ll reuse the examples from the route guards documentation:

my_app/guards.py#

from starlite import Request, RouteHandler, NotAuthorizedException


def secret_token_guard(request: Request, route_handler: RouteHandler) -> None:
    if (
        route_handler.opt.get("secret")
        and not request.headers.get("Secret-Header", "") == route_handler.opt["secret"]
    ):
        raise NotAuthorizedException()

We already have our route handler in place:

my_app/secret.py#

from os import environ

from starlite import get

from my_app.guards import secret_token_guard


@get(path="/secret", guards=[secret_token_guard], opt={"secret": environ.get("SECRET")})
def secret_endpoint() -> None:
    ...

We could thus test the guard function like so:

tests/guards/test_secret_token_guard.py#

import pytest

from starlite import NotAuthorizedException
from starlite.testing import RequestFactory

from my_app.guards import secret_token_guard
from my_app.secret import secret_endpoint

request = RequestFactory().get("/")


def test_secret_token_guard_failure_scenario():
    copied_endpoint_handler = secret_endpoint.copy()
    copied_endpoint_handler.opt["secret"] = None
    with pytest.raises(NotAuthorizedException):
        secret_token_guard(request=request, route_handler=copied_endpoint_handler)


def test_secret_token_guard_success_scenario():
    copied_endpoint_handler = secret_endpoint.copy()
    copied_endpoint_handler.opt["secret"] = "super-secret"
    secret_token_guard(request=request, route_handler=copied_endpoint_handler)

Using pydantic-factories#

Pydantic-factories offers an easy and powerful way to generate mock data from pydantic models and dataclasses.

Let’s say we have an API that talks to an external service and retrieves some data:

main.py#

from typing import Protocol, runtime_checkable

from pydantic import BaseModel
from starlite import get


class Item(BaseModel):
    name: str


@runtime_checkable
class Service(Protocol):
    def get(self) -> Item:
        ...


@get(path="/item")
def get_item(service: Service) -> Item:
    return service.get()

We could test the /item route like so:

tests/conftest.py#

import pytest

from starlite.status_codes import HTTP_200_OK
from starlite import Provide, create_test_client

from my_app.main import Service, Item, get_item


@pytest.fixture()
def item():
    return Item(name="Chair")


def test_get_item(item: Item):
    class MyService(Service):
        def get_one(self) -> Item:
            return item

    with create_test_client(
        route_handlers=get_item, dependencies={"service": Provide(lambda: MyService())}
    ) as client:
        response = client.get("/item")
        assert response.status_code == HTTP_200_OK
        assert response.json() == item.dict()

While we can define the test data manually, as is done in the above, this can be quite cumbersome. That’s where pydantic-factories library comes in. It generates mock data for pydantic models and dataclasses based on type annotations. With it, we could rewrite the above example like so:

main.py#

from typing import Protocol, runtime_checkable

import pytest
from pydantic import BaseModel
from pydantic_factories import ModelFactory
from starlite.status_codes import HTTP_200_OK
from starlite import Provide, get
from starlite.testing import create_test_client


class Item(BaseModel):
    name: str


@runtime_checkable
class Service(Protocol):
    def get_one(self) -> Item:
        ...


@get(path="/item")
def get_item(service: Service) -> Item:
    return service.get_one()


class ItemFactory(ModelFactory[Item]):
    model = Item


@pytest.fixture()
def item():
    return ItemFactory.build()


def test_get_item(item: Item):
    class MyService(Service):
        def get_one(self) -> Item:
            return item


with create_test_client(
    route_handlers=get_item, dependencies={"service": Provide(lambda: MyService())}
) as client:
    response = client.get("/item")
    assert response.status_code == HTTP_200_OK
    assert response.json() == item.dict()

Testing#

Test Client#

Using sessions#

Using a blocking portal#

Creating a test app#

RequestFactory#

Using pydantic-factories#