How to start a Uvicorn + FastAPI in background when testing with PyTest

If you want to bring the server up you will have to do it in a different process/thread, since uvicorn.run() is a blocking call.

Then instead of using the TestClient you will have to use something like requests to hit the actual URL your server is listening to.

from multiprocessing import Process

import pytest
import requests
import uvicorn
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def read_main():
    return {"msg": "Hello World"}


def run_server():
    uvicorn.run(app)


@pytest.fixture
def server():
    proc = Process(target=run_server, args=(), daemon=True)
    proc.start() 
    yield
    proc.kill() # Cleanup after test


def test_read_main(server):
    response = requests.get("http://localhost:8000/")
    assert response.status_code == 200
    assert response.json() == {"msg": "Hello World"}

Here I have another solution which runs uvicorn in the same process (tested with Python 3.7.9):

from typing import List, Optional
import asyncio

import pytest

import uvicorn

PORT = 8000


class UvicornTestServer(uvicorn.Server):
    """Uvicorn test server

    Usage:
        @pytest.fixture
        server = UvicornTestServer()
        await server.up()
        yield
        await server.down()
    """

    def __init__(self, app, host='127.0.0.1', port=PORT):
        """Create a Uvicorn test server

        Args:
            app (FastAPI, optional): the FastAPI app. Defaults to main.app.
            host (str, optional): the host ip. Defaults to '127.0.0.1'.
            port (int, optional): the port. Defaults to PORT.
        """
        self._startup_done = asyncio.Event()
        super().__init__(config=uvicorn.Config(app, host=host, port=port))

    async def startup(self, sockets: Optional[List] = None) -> None:
        """Override uvicorn startup"""
        await super().startup(sockets=sockets)
        self.config.setup_event_loop()
        self._startup_done.set()

    async def up(self) -> None:
        """Start up server asynchronously"""
        self._serve_task = asyncio.create_task(self.serve())
        await self._startup_done.wait()

    async def down(self) -> None:
        """Shut down server asynchronously"""
        self.should_exit = True
        await self._serve_task


@pytest.fixture
async def startup_and_shutdown_server():
    """Start server as test fixture and tear down after test"""
    server = UvicornTestServer()
    await server.up()
    yield
    await server.down()


@pytest.mark.asyncio
async def test_chat_simple(startup_and_shutdown_server):
    """A simple websocket test"""
    # any test code here

There is a test client in FastAPI
https://fastapi.tiangolo.com/tutorial/testing/
This is a sort of implementation on a requests library, so you can use it like this:

import unittest
from fastapi.testclient import TestClient
from engine.routes.base import app


class PostTest(unittest.TestCase):
    def setUp(self) -> None:
        self.client = TestClient(app)

    def test_home_page(self):
        response = self.client.get("/")
        assert response.status_code == 200

Digging deeper into the documentation, I stumbled upon
https://fastapi.tiangolo.com/advanced/testing-events
which proposes using with TestClient(app) as client to make the asynchronous events for @app.on_event("startup") and @app.on_event("shutdown") fire:

def test_read_main():
    with TestClient(app) as client:
        response = client.get("/")
        assert response.status_code == 200
        assert response.json() == {"msg": "Hello World"}

This allowed me to properly replicate the app’s behavior of gunicorn also in pytest, without starting any additional background process.

Additional information

I just encountered this problem while I was trying to adapt the testing practice proposed in https://fastapi.tiangolo.com/tutorial/testing, i.e. without starting a background server like gunicorn, as others have proposed.

However, this does not execute the asynchronous events for @app.on_event("startup") and @app.on_event("shutdown"), which are properly executed on gunicorn.

For example, the following will not print Block reached

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.on_event("startup")
async def startup_event():
    # This will not be reached in pytest, but in gunicorn it will
    print("Block reached")

@app.get("/")
async def read_main():
    return {"msg": "Hello World"}

def test_read_main():
    client = TestClient(app)
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"msg": "Hello World"}