In the ever-evolving landscape of software development, responsiveness and efficiency are paramount. Modern applications, especially those dealing with network requests, user interfaces, or concurrent operations, often demand the ability to handle multiple tasks seemingly at the same time. For a long time, traditional threading and multiprocessing were the go-to solutions in Python for achieving concurrency. However, Python’s Global Interpreter Lock (GIL) and the overhead associated with thread management can sometimes limit the effectiveness of these approaches, especially for I/O-bound tasks.

Enter asynchronous programming. Async Python offers a powerful paradigm for writing concurrent code that is both efficient and, arguably, more intuitive for certain types of applications. If you’ve encountered the keywords async and await in Python and found yourself intrigued but also slightly mystified, you’re not alone. While the surface-level syntax of async Python might seem straightforward, understanding what’s happening beneath the hood is crucial for truly leveraging its power and avoiding common pitfalls.

This post is your comprehensive guide to demystifying async Python. We’ll go far beyond the basic syntax, diving deep into the core concepts that underpin asynchronous programming in Python. We’ll explore the event loop, coroutines, tasks, futures, context switching, and even touch upon how async compares to traditional threading and parallelism. By the end of this journey, you’ll not only be able to write async Python code, but you’ll also possess a solid understanding of the mechanisms that make it all tick.

The async and await Duo: The Face of Async Python

Let’s start with the syntax that you’ll encounter most frequently when working with async Python: the async and await keywords. These two are the fundamental building blocks for writing asynchronous code in Python.

Defining Asynchronous Functions with async def

In Python, you declare a function as asynchronous by using the async def syntax instead of the regular def. This seemingly small change has profound implications. An async def function, also known as a coroutine function, doesn’t execute like a regular synchronous function. Instead, it returns a coroutine object.

Think of a coroutine object as a promise of work to be done later. It’s not the work itself, but rather a representation of that work, ready to be executed when the time is right.

 1import asyncio
 2
 3async def hello_async():
 4    print("Hello from async function!")
 5    await asyncio.sleep(1) # Simulate some async operation (like network I/O)
 6    print("Async function finished.")
 7
 8# Calling the async function returns a coroutine object
 9coro = hello_async()
10print(f"Coroutine object: {coro}")
11
12# To actually run the coroutine, we need to use an event loop
13asyncio.run(coro)

In this example, hello_async is an asynchronous function. When we call hello_async(), it doesn’t immediately print “Hello from async function!”. Instead, it creates and returns a coroutine object. To actually execute the code within the coroutine, we need to use asyncio.run(), which sets up and runs an event loop (more on event loops shortly) to manage the execution of our coroutine.

Pausing Execution with await

The await keyword is the other half of the async duo. It can only be used inside async def functions. await is the point where an asynchronous function can pause its execution and yield control back to the event loop. This is the crucial mechanism that enables concurrency in async Python without relying on threads.

When you await something, you are essentially saying: “I need to wait for this asynchronous operation to complete. While I’m waiting, I’m going to yield control back to the event loop so it can work on other tasks. Once this operation is done, please resume my execution from right here.”

In our hello_async example, await asyncio.sleep(1) is a simulated asynchronous operation that represents waiting for 1 second. During this second, the hello_async coroutine pauses, and the event loop is free to execute other coroutines or handle other events. Once the sleep duration is over, the event loop resumes the hello_async coroutine from the line after the await statement, and it prints “Async function finished.”

Important Note: You can only await objects that are awaitable. In practice, this usually means you’re awaiting other coroutines, Future objects (which we’ll discuss later), or objects that have implemented the __await__ special method. Standard synchronous functions are not awaitable.

The Event Loop: The Orchestrator of Asynchronicity

At the heart of async Python lies the event loop. Think of the event loop as the central conductor of an orchestra. It’s responsible for managing and scheduling the execution of all your asynchronous tasks. It’s a single-threaded loop that constantly monitors for events and dispatches tasks to be executed when those events occur.

How the Event Loop Works (Simplified)

1. Task Queue: The event loop maintains a queue of tasks (usually coroutines wrapped in Task objects) that are ready to be executed or resumed.
2. Event Monitoring: The event loop also monitors for various events, such as network sockets becoming ready for reading or writing, timers expiring, or file operations completing. It typically uses efficient system calls like select, poll, or epoll (depending on the operating system) to monitor these events without blocking.
3. Task Execution and Resumption: When an event occurs that makes a task ready to proceed (e.g., data is available on a socket that a task is waiting to read from), the event loop picks up that task from the queue and executes it until it encounters an await statement.
4. Yielding Control with await: When a coroutine reaches an await statement, it effectively tells the event loop, “I need to wait for this operation. Please pause me and let someone else run.” The event loop then takes control and looks for other tasks in the queue that are ready to run.
5. Resuming Execution: Once the awaited operation completes (e.g., the network request returns, the timer expires), the event loop is notified. It then puts the paused coroutine back into the task queue, ready to be resumed at the point where it left off.
6. Looping Continuously: The event loop continues this process of monitoring events, executing tasks, and pausing/resuming coroutines in a loop until there are no more tasks to run or the program is explicitly stopped.

Different Event Loop Implementations: asyncio, uvloop, and More

Python’s standard library provides the asyncio module, which includes a built-in event loop implementation. This default event loop is written in Python and is generally sufficient for many use cases.

However, for performance-critical applications, especially those dealing with high-performance networking, you might consider using alternative event loop implementations. One popular option is uvloop.

uvloop: uvloop is a blazing-fast, drop-in replacement for asyncio’s event loop. It’s written in Cython and built on top of libuv, the same high-performance library that powers Node.js. uvloop is significantly faster than the default asyncio event loop, especially for network I/O.

To use uvloop, you typically need to install it separately (pip install uvloop) and then set it as the event loop policy for asyncio when your application starts:

 1import asyncio
 2import uvloop
 3
 4async def main():
 5    print("Running with uvloop!")
 6    await asyncio.sleep(1)
 7    print("Done.")
 8
 9if __name__ == "__main__":
10    uvloop.install() # Set uvloop as the event loop policy
11    asyncio.run(main())

Other event loop implementations exist, but asyncio and uvloop are the most commonly used in Python async programming. Choosing between them often depends on the performance requirements of your application. For most general async tasks, asyncio’s default loop is perfectly adequate. For high-load network applications, uvloop can provide a noticeable performance boost.

Layers of Async Python: Coroutines, Tasks, and Futures

To truly understand async Python, it’s helpful to think about it in layers. We’ve already touched upon coroutines and the event loop. Let’s now delve into the roles of Tasks and Futures.

Coroutines: The Asynchronous Functions

As we discussed earlier, coroutines are the asynchronous functions you define using async def. They represent units of asynchronous work. Coroutines themselves are not directly executed by the event loop. Instead, they need to be wrapped in something that the event loop can manage and schedule. This “something” is a Task.

Tasks: Scheduling Coroutines in the Event Loop

A Task in asyncio is essentially a wrapper around a coroutine that allows the event loop to schedule and manage its execution. When you want to run a coroutine concurrently within the event loop, you typically create a Task from it.

You can create a Task using asyncio.create_task():

 1import asyncio
 2
 3async def my_coroutine():
 4    print("Coroutine started")
 5    await asyncio.sleep(2)
 6    print("Coroutine finished")
 7    return "Coroutine result"
 8
 9async def main():
10    task1 = asyncio.create_task(my_coroutine()) # Create a Task from the coroutine
11    task2 = asyncio.create_task(my_coroutine()) # Create another Task
12
13    print("Tasks created, waiting for completion...")
14
15    result1 = await task1 # Await the completion of task1
16    result2 = await task2 # Await the completion of task2
17
18    print(f"Task 1 result: {result1}")
19    print(f"Task 2 result: {result2}")
20
21asyncio.run(main())

In this example, we create two Tasks, task1 and task2, from the same my_coroutine. asyncio.create_task() schedules these coroutines to be run by the event loop concurrently. When we await task1 and await task2, we are waiting for these Tasks to complete and retrieve their results.

Tasks are essential for managing the lifecycle of coroutines within the event loop. They provide methods to:

• Cancel a Task: task.cancel()
• Check if a Task is done: task.done()
• Get the result of a Task: task.result() (if done)
• Get exceptions raised during Task execution: task.exception() (if any)

Futures: Representing the Result of Asynchronous Operations

A Future is an object that represents the eventual result of an asynchronous operation. It’s a placeholder for a value that might not be available yet. Tasks in asyncio are actually a subclass of Futures.

Futures are used extensively in async Python to represent the outcome of operations that are performed asynchronously, such as:

• Network I/O: Reading data from a socket, sending a request to a server.
• File I/O: Reading or writing to a file (in an async context).
• Concurrent computations: Tasks running in parallel (within the same event loop or in different threads/processes).

A Future object has a state that can be:

• Pending: The asynchronous operation is still in progress.
• Running: The operation is currently being executed.
• Done: The operation has completed successfully or with an exception.
• Cancelled: The operation has been cancelled.

You can interact with a Future to:

• Check if it’s done: future.done()
• Get the result: future.result() (blocks until done if pending, raises exception if an exception occurred)
• Get exceptions: future.exception() (returns exception if one occurred, otherwise None)
• Add callbacks: future.add_done_callback(callback_function) (run a function when the future is done)
• Cancel the future: future.cancel()

When you await a Task (or any awaitable Future-like object), you are essentially waiting for that Future to become “done” and then retrieving its result or handling any exceptions.

Coroutine Execution and Context Switching: The Asynchronous Dance

Now, let’s delve deeper into how coroutines are actually executed and how context switching works in async Python.

Cooperative Multitasking and Context Switching

Async Python uses cooperative multitasking. This is in contrast to preemptive multitasking used by operating systems for threads and processes.

• Preemptive Multitasking (Threads/Processes): In preemptive multitasking, the operating system’s scheduler decides when to switch between threads or processes. It can interrupt a running thread/process at any time and switch to another, even if the running thread/process doesn’t explicitly yield control. This is typically based on time slices and priority levels.
• Cooperative Multitasking (Async Python): In cooperative multitasking, coroutines voluntarily yield control back to the event loop when they encounter an await statement. The event loop then decides which coroutine to run next. Context switching only happens at these explicit await points. A coroutine will continue to run until it reaches an await or completes.

This cooperative nature has important implications:

• No True Parallelism (within a single event loop): Within a single event loop running in a single thread, true parallelism is not achieved. Coroutines take turns running. If a coroutine doesn’t await frequently and performs long-running CPU-bound operations, it can block the event loop and prevent other coroutines from making progress.
• Responsiveness: Cooperative multitasking is excellent for I/O-bound tasks. While one coroutine is waiting for I/O, another can run, keeping the application responsive.
• Less Overhead: Context switching in cooperative multitasking is generally lighter than preemptive context switching between threads or processes. There’s less operating system overhead involved.
• Deterministic Behavior (mostly): Because context switching happens only at explicit await points, the execution flow of async code is often more predictable and easier to reason about compared to multithreaded code, which can have race conditions and unpredictable scheduling.

How Coroutines are Paused and Resumed

When a coroutine reaches an await statement, several things happen:

1. await Expression: The expression after await (e.g., asyncio.sleep(1), another coroutine, a Future) must be awaitable.
2. Yielding Control: The coroutine effectively “pauses” its execution at the await point. It returns control back to the event loop.
3. Event Loop Takes Over: The event loop becomes active again. It looks at its task queue for other tasks that are ready to run.
4. Registering for Resumption: The coroutine, along with information about where it paused (the line after the await), is registered with the event loop as being “waiting” for the completion of the awaited operation.
5. Awaited Operation Proceeds: The awaited operation (e.g., network request, timer) proceeds asynchronously in the background (often managed by non-blocking system calls).
6. Event Notification: When the awaited operation is complete, the event loop receives a notification (e.g., socket becomes readable, timer expires).
7. Resuming the Coroutine: The event loop puts the paused coroutine back into the task queue, marked as ready to be resumed.
8. Coroutine Resumes: When the event loop gets around to executing this coroutine again, it resumes from the exact point where it was paused (right after the await statement). It now has access to the result of the awaited operation (if any).

This pause-and-resume mechanism is what allows asynchronous code to be written in a seemingly sequential style, even though it’s actually being executed in an interleaved and non-blocking manner.

Async vs. Threads vs. Processes: Choosing the Right Tool

It’s crucial to understand when async Python is the right choice and when traditional threading or multiprocessing might be more appropriate.

Async Python: Ideal for I/O-Bound Tasks

Async Python excels in scenarios where your application is I/O-bound. This means that the primary bottleneck is waiting for external operations to complete, such as:

• Network requests: Fetching data from APIs, making HTTP requests, communicating with databases over a network.
• File I/O: Reading and writing to files (especially over a network file system).
• Waiting for user input: In GUI applications or interactive systems.

In these cases, the CPU is often idle while waiting for I/O operations. Async Python allows you to utilize this idle time by letting other coroutines run while one is waiting for I/O. It’s highly efficient for handling many concurrent I/O operations with minimal overhead.

Example: Web Server

A web server that handles many concurrent requests is a classic example where async Python shines. While one request is being processed (which often involves waiting for database queries, external API calls, etc.), the server can be handling other requests concurrently.

 1import asyncio
 2import aiohttp
 3from aiohttp import web
 4
 5async def fetch_data_from_api(api_url):
 6    async with aiohttp.ClientSession() as session:
 7        async with session.get(api_url) as response:
 8            return await response.json()
 9
10async def handler(request):
11    data = await fetch_data_from_api("https://api.example.com/data")
12    return web.json_response(data)
13
14async def main():
15    app = web.Application()
16    app.add_routes([web.get('/', handler)])
17    runner = web.AppRunner(app)
18    await runner.setup()
19    site = web.TCPSite(runner, 'localhost', 8080)
20    await site.start()
21    print("Server started at http://localhost:8080")
22    await asyncio.Event().wait() # Keep the server running indefinitely
23
24if __name__ == "__main__":
25    asyncio.run(main())

This example uses aiohttp, an async HTTP client and server library. The fetch_data_from_api coroutine performs an asynchronous HTTP request. The handler coroutine uses await fetch_data_from_api to fetch data without blocking the server. The server can handle many requests concurrently, making it highly scalable for I/O-bound web applications.

Threads: For CPU-Bound Tasks and True Parallelism (within limits)

Threads, especially when used with Python’s threading module, are suitable for tasks that are more CPU-bound and can benefit from concurrency (even if not true parallelism due to the GIL).

• CPU-Bound Tasks: Tasks that spend most of their time performing computations on the CPU, rather than waiting for I/O. Examples include:

  • Image processing
  • Numerical computations
  • Data analysis
  • Cryptographic operations

• Concurrency (with GIL limitations): Python’s GIL (Global Interpreter Lock) prevents true parallelism for CPU-bound tasks in standard CPython threads. Only one thread can hold the Python interpreter lock at any given time. However, threads can still provide concurrency by releasing the GIL during I/O operations or certain blocking system calls. This can improve responsiveness even for CPU-bound tasks if they involve some I/O or blocking.

Example: CPU-Bound Computation (with threading for concurrency)

 1import threading
 2import time
 3
 4def cpu_bound_task(task_id):
 5    print(f"Task {task_id} started")
 6    start_time = time.time()
 7    result = 0
 8    for _ in range(10**7): # Simulate CPU-intensive computation
 9        result += 1
10    end_time = time.time()
11    duration = end_time - start_time
12    print(f"Task {task_id} finished in {duration:.4f} seconds, result: {result}")
13
14def main_threads():
15    threads = []
16    for i in range(4):
17        thread = threading.Thread(target=cpu_bound_task, args=(i,))
18        threads.append(thread)
19        thread.start()
20
21    for thread in threads:
22        thread.join() # Wait for all threads to complete
23
24if __name__ == "__main__":
25    main_threads()

In this example, cpu_bound_task simulates a CPU-intensive operation. We create multiple threads to run this task concurrently. While the GIL limits true parallelism for CPU-bound Python code, threads can still provide some concurrency and potential performance improvement, especially if the tasks involve some I/O or blocking operations. For purely CPU-bound tasks, however, the benefits might be limited by the GIL.

Processes: True Parallelism and CPU-Bound Tasks (but heavier)

For truly CPU-bound and computationally intensive tasks that need true parallelism and to bypass the GIL limitations, multiprocessing using Python’s multiprocessing module is the way to go.

• True Parallelism: Multiprocessing creates separate processes, each with its own Python interpreter and memory space. Processes run in parallel on multiple CPU cores, achieving true parallelism for CPU-bound tasks.
• Bypassing the GIL: Each process has its own GIL, so the GIL limitation of threads is overcome.
• Higher Overhead: Process creation and inter-process communication have more overhead compared to threads or async tasks. Processes consume more system resources (memory, process management overhead).

Example: CPU-Bound Computation (with multiprocessing for parallelism)

 1import multiprocessing
 2import time
 3
 4def cpu_bound_task_process(task_id): # Same CPU-bound task as before
 5    print(f"Process {task_id} started")
 6    start_time = time.time()
 7    result = 0
 8    for _ in range(10**7):
 9        result += 1
10    end_time = time.time()
11    duration = end_time - start_time
12    print(f"Process {task_id} finished in {duration:.4f} seconds, result: {result}")
13
14def main_processes():
15    processes = []
16    for i in range(4):
17        process = multiprocessing.Process(target=cpu_bound_task_process, args=(i,))
18        processes.append(process)
19        process.start()
20
21    for process in processes:
22        process.join() # Wait for all processes to complete
23
24if __name__ == "__main__":
25    main_processes()

In this multiprocessing example, we create separate processes to run the same CPU-bound task. Because each process has its own interpreter and bypasses the GIL, we can achieve true parallelism and significantly speed up CPU-intensive computations on multi-core systems.

Choosing the Right Concurrency Approach

General Guidelines:

• I/O-Bound, High Concurrency: Async Python (asyncio) is often the best choice.
• CPU-Bound with some I/O, Responsiveness: Threads (threading) can be considered, but be mindful of GIL limitations for pure CPU-bound tasks.
• CPU-Bound, True Parallelism, Max Performance: Processes (multiprocessing) are essential, especially for computationally intensive tasks on multi-core machines.
• Hybrid Applications: You can combine async and multiprocessing. For example, use async for handling network I/O and multiprocessing for CPU-bound background tasks.

Conclusion: Embracing the Asynchronous World

Async Python offers a powerful and elegant way to write concurrent code, particularly for I/O-bound applications. Understanding the underlying mechanisms – the event loop, coroutines, tasks, futures, and cooperative multitasking – is key to effectively leveraging its benefits.

While async Python is not a silver bullet for all concurrency problems, and it’s not a direct replacement for threading or multiprocessing in all cases, it provides a compelling and often more efficient alternative for many modern application scenarios. By mastering async Python, you gain a valuable tool in your development arsenal, enabling you to build responsive, scalable, and performant applications in the asynchronous world. So, embrace the async and await duo, dive into the event loop, and unlock the power of asynchronous programming in Python!

Introduction

If you’re a backend developer working with FastAPI, you already know the framework excels at simplifying API development with features like async support and automated Swagger docs. However, when it comes to integration testing–particularly mocking external services like MongoDB, AWS S3, and third-party APIs—the waters can get murky. This post is your guide to navigating these complexities.

This isn’t a one-stop-shop for all things testing; the focus is squarely on integration testing within FastAPI.

Prerequisites: Familiarity with FastAPI, PyTest, MongoDB, and AWS S3 is assumed. If you’re new to any of these technologies, you may want to get up to speed before proceeding.

What is Integration Testing?

Integration testing involves combining individual units of code and testing them as a group. This type of testing aims to expose faults in the interactions between integrated units. In our context, we could also probably call these API tests (and you’ll see that’s how I name my test files). In the context of FastAPI, these units often involve your API endpoints, external databases like MongoDB, and other services such as AWS S3.

Why It’s Challenging

When compared to unit tests, integration tests in FastAPI present unique difficulties. These challenges mostly stem from the interaction with external dependencies. Mocking these dependencies is not always straightforward, and mistakes can lead to false positives or negatives, undermining the purpose of the tests.

Why It Matters

So, why focus on integration testing in FastAPI? Because it’s here that you validate that various services and databases work in harmony. By ensuring that these integrated units function as expected, you not only increase code reliability but also save debugging time in the long run.

Unit tests are great for testing individual units of code, but they don’t test the interactions between these units. I also find integration tests (especially this kind, which test our endpoints) are particularly useful before doing a large refactor–going from a v0 to v1 of an app, where unit tests might not make a ton of sense because you’re rewriting all of your ‘units’.

A Glimpse into Our Test App

Before we delve into the technicalities of mocking various elements, let’s take a quick look at the FastAPI application we’ll be using as a test subject. This app serves as a sandbox for our integration tests, built to showcase different aspects of FastAPI that commonly require mocking in a test environment.

Our sample application has a straightforward schema designed for demonstration purposes:

 1/login  # simple login
 2  POST: Login
 3
 4/users/me/  # example for mocking auth
 5  GET: Read Users Me
 6
 7/users/me/preferences  # example for mocking mongodB
 8  GET: Get Preferences
 9  POST: Save Preferences
10
11/users/me/profile_pic  # example for mocking s3
12  GET: Get Profile Picture
13  POST: Save Profile Picture
14
15/weather/{city}  # example for mocking external API
16  GET: Get Weather

Our tests live in tests/ where they are organized according to the application components they evaluate. We employ PyTest for test execution and adhere to its conventions for discovering tests and initial set up. This includes utilizing the conftest.py configuration file for shared hooks and fixtures.

Mocking Authentication in FastAPI

As we move through the article, we’ll see that FastAPI provides an easy way to do dependency injection, which is especially useful for our testing scenarios. Using dependency_overrides, we can inject our mocked functions into the FastAPI app, but remember, this only works for endpoints/functions using the Depends() syntax. You can read more about dependency injection in FastAPI here.

In our FastAPI application, we have endpoints that require authentication. During testing, we don’t want to use real authentication because it would require us to manage real user credentials and tokens. This would complicate our tests and potentially expose sensitive information. Therefore, we mock the authentication process.

Testing Our Login

Before we get to dependency injection or mocking out our services, let’s make sure our auth works. We have simple authentication defined in the project that checks if a user is in the database, if their password matches, and returns a token if they are. (I am not going to focus on how to do authentication, but you can check out the code in auth.py if you’re interested.)

For the purposes of this tutorial, our database is just a dictionary with one hard coded user.

(I’ll be using my name as the username in this tutorial in order to burn it into your brain)

1# File: app/db.py
2users_db: Dict[str, UserInDB] = {
3    "alexjacobs": UserInDB(
4        username="alexjacobs",
5        email="alex@example.com",
6        hashed_password=get_password_hash("secret"),
7    )
8}

and our login endpoint…

 1# File: app/main.py
 2@app.post("/login", response_model=Token)
 3async def login(_login: Login):
 4    user = authenticate_user(users_db, _login.username, _login.password)
 5    if not user:
 6        raise HTTPException(
 7            status_code=status.HTTP_401_UNAUTHORIZED,
 8            detail="Incorrect username or password",
 9            headers={"WWW-Authenticate": "Bearer"},
10        )
11    access_token = create_access_token(
12        data={"sub": user.username}
13    )
14    return {"jwt": access_token, "token_type": "bearer"}

and we have some simple tests just to verify that our login endpoint works as expected

 1# File: tests/test_auth_api.py
 2def test_login(client):
 3    response = client.post("/login", json={"username": "alexjacobs", "password": "secret"})
 4    assert response.status_code == 200
 5    assert "jwt" in response.json()
 6
 7
 8def test_login_fail(client):
 9    response = client.post("/login", json={"username": "alexjacobs", "password": "not_the_right_password"})
10    assert response.status_code == 401
11    assert response.json() == {'detail': 'Incorrect username or password'}

These initial tests don’t require mocking the authentication process because they are designed to test the endpoint’s basic functionality. They act as a foundational layer upon which we will build more complex test scenarios that require mocking.

Mocking Authentication in Our Test Client

Now, let’s say we have another endpoint that requires authentication. We’ll use the Depends function to inject our authentication function into our endpoint. Our /users/me endpoint returns information about the user logged in.

1# File: app/main.py
2@app.get("/users/me/", response_model=User)
3async def read_users_me(_user: TokenData = Depends(get_auth)):
4    user = users_db.get(_user.username)
5    if user is None:
6        raise HTTPException(status_code=404, detail="User not found")
7    return user

Authentication is handled by the get_auth function, which is injected into our endpoint using the Depends function.
Since we don’t want to use real authentication in our tests, we’re going to mock this function. I’m going to show multiple ways of doing this so you can choose the one that works best for you.

The most standard way of mocking this function is to use the dependency_overrides feature of FastAPI, before we initialize our TestClient.

 1# File: tests/conftest.py
 2@pytest.fixture
 3def client(mock_s3_bucket):
 4    # we patch auth within our client fixture
 5    from app.main import app
 6
 7    def mock_get_auth():
 8        return TokenData(username="alexjacobs")
 9
10    app.dependency_overrides[get_auth] = mock_get_auth
11    with TestClient(app) as test_client:
12        yield test_client
13
14    app.dependency_overrides.clear()

You’ll see we declare a function called mock_get_auth that returns a TokenData object. Then in line 10, app.dependency_overrides[get_auth] = mock_get_auth, we ‘inject’ our mock function into our app in place of the get_auth function.

This code is essentially replacing the get_auth function in our app with a mock function that returns the TokenData object hardcoded into the function we’re pathing with.

Then, in our test we pass in the client fixture, and we can see that our test passes.

1# File: tests/test_auth_api.py
2def test_get_me_patched_auth(client):
3    # auth works without real jwt because we patched it in the client fixture
4    response = client.get("/users/me", headers={"Authorization": "Bearer " + 'fake.jwt'})
5    assert response.status_code == 200
6    assert response.json() == {'username': 'alexjacobs', 'email': 'alex@example.com'}

(we really don’t even need to include auth headers, since we’re mocking the auth function, but I’m keeping it here for clarity)

Mocking Authentication Directly in your Tests

Now, what if we want to mock the auth function in a different way? We can do this by mocking the auth function directly in our test.

First, we’ll create a second client fixture that doesn’t patch the auth function.

1# File: tests/conftest.py
2@pytest.fixture
3def client_unpatched_auth():
4    # we don't patch auth for this client
5    from app.main import app
6
7    with TestClient(app) as test_client_2:
8        yield test_client_2

Now we’re going to write a test to verify that auth fails (since we’re not patching the auth function)

1# File: tests/test_auth_api.py
2def test_get_me_unpatched_auth(client_unpatched_auth):
3    # auth fails without real jwt because we're using the unpatched client fixture
4    response = client_unpatched_auth.get("/users/me", headers={"Authorization": "Bearer " + 'fake.jwt'})
5    assert response.status_code == 401
6    assert response.json() == {"detail": "Could not validate credentials"}

To make this work, there are two approaches. The first is to mock the auth function directly in the test

 1# File: tests/test_auth_api.py
 2def test_get_me_path_auth_in_fn(client_unpatched_auth):
 3    # auth works because we patch it in this test (not in the client fixture)
 4    def mock_get_auth():
 5        return TokenData(username="alexjacobs")
 6
 7    app.dependency_overrides[get_auth] = mock_get_auth
 8
 9    response = client_unpatched_auth.get("/users/me", headers={"Authorization": "Bearer " + 'fake.jwt'})
10    assert response.status_code == 200

All we’ve done here is moved the code that patches the auth function into the test itself. This could be useful if you wanted to mock the auth function in some tests, but not others (but only wanted to have one client fixture).

Next, we’ll do the same thing, but we’re going to use a new fixture and factory function to create our mock auth function. So first, we’ll create a new fixture,

1# File: tests/conftest.py
2@pytest.fixture
3def mock_get_auth_factory():
4    def mock_get_auth():
5        return TokenData(username="alexjacobs")
6
7    return mock_get_auth

and then we’ll use this fixture in our test

1# File: tests/test_auth_api.py
2def test_get_me_patch_auth_with_fixture(client_unpatched_auth, mock_get_auth_factory):
3    # auth works because we patch it with a fixture instead of in the client fixture
4    app.dependency_overrides[get_auth] = mock_get_auth_factory
5    response = client_unpatched_auth.get("/users/me", headers={"Authorization": "Bearer " + 'fake.jwt'})
6    assert response.status_code == 200

Notice that when we’re passing in the mock_get_auth_factory fixture, we’re passing in the function itself, not the return value of the function. This is because the fixture is a factory function that returns a function, so we need to pass in the function itself.

This may not seem very useful (and for mocking auth, it may not be), but there are plenty of scenarios when you may want to mock a function in some tests, but not others. This is a good way to do that.

Mocking External APIs

Our FastAPI application makes external API calls to fetch weather data. During testing, we don’t want to make real API calls because they can be slow and unreliable. Therefore, we mock the external API calls.

We mock the external API calls by patching the fetch_weather function in our FastAPI application. This function is responsible for making the actual API call and returning the weather data. We replace it with a mock function that always returns a predefined weather data. But, this function does use dependency injection (the Depends funciton) in our app, so we have to mock it in a different way.

First, let’s look at our endpoint and the function it calls.

1# File: app/main.py
2@app.get("/weather/{city}", response_model=WeatherResponse)
3async def get_weather(city: str, _user: TokenData = Depends(get_auth)):
4    weather = fetch_weather(city)
5    return WeatherResponse(city=city, weather=weather)

and our fetch_weather() function

1# File: app/helpers.py
2def fetch_weather(city_name):
3    url = f"http://wttr.in/{city_name}?format=%C+%t"
4    response = requests.get(url)
5    return response.text

Pretty simple… we are hitting an external API, though, so we need to mock this out in our tests.

We have three ways to mock the external API calls:

Mocking External APIs with unittest.mock.patch Directly in Our Test

Using unittest.mock.patch, we patch our fetch_weather function to return ‘sunny’. We then verify our endpoint returns the expected response (and verify that our mock function was called–this last part probably isn’t really necessary here, but is a good demonstration)

1# File: tests/test_weather_api.py
2def test_get_weather(client):
3    with patch('app.main.fetch_weather', return_value='sunny') as mock_fetch_weather:
4        response = client.get("/weather/atlanta")
5        assert response.status_code == 200
6        assert response.json() == {'city': 'atlanta', 'weather': 'sunny'}
7        mock_fetch_weather.assert_called_once_with('atlanta')

Creating a fixture that patches the function

Let’s suggest that we may want to test multiple endpoints that call the fetch_weather function. We could patch the function in each test, but that’s a lot of code duplication. Instead, we can create a fixture that patches the function. First, we’ll set up our fixture (this is another factor function). We’re using unittest’s Mock and Patch functions in order to replace the fetch_weather function with a mock function that returns ‘rainy’.

Note: As before, we’re using a factory function to create our mock function, so we need to pass in the function itself, not the return value of the function.

1# File: tests/conftest.py
2@pytest.fixture
3def mock_fetch_weather_factory():
4    def mock_fetch_weather(city):
5        return "rainy"
6
7    mock = Mock(side_effect=mock_fetch_weather)
8    with patch.object(app.main, 'fetch_weather', new=mock):
9        yield

In our test, we just need to again pass in the fixture as an argument.

1# File: tests/test_weather_api.py
2def test_get_weather1(client, mock_fetch_weather_factory):
3    response = client.get("/weather/atlanta")
4    assert response.status_code == 200
5    assert response.json() == {'city': 'atlanta', 'weather': 'rainy'}

Creating a parametrized fixture

The above example probably isn’t very useful in practice. In the real world, if we’re testing multiple endpoints that call the same function, we probably want to test different scenarios. For example, we may want to test that our endpoint returns the correct response for different weather conditions. We could do this by creating multiple fixtures that patch the function with different mock functions, but this is a lot of code duplication and basically defeats the purpose of using a fixture at all. Instead, we can use a parametrized fixture to pass in values to our fixture to make it behave differently depending on our test.

To do this, we’re going to create another fixture, but this one will take a parameter. It essentially wraps our previous factory function, but now we can pass in a parameter to the fixture.

 1# File: tests/conftest.py
 2@pytest.fixture
 3def mock_fetch_weather_parametrized(request):
 4    def mock_fetch_weather_factory(weather):
 5        def mock_fetch_weather(*args, **kwargs):
 6            return weather
 7
 8        return mock_fetch_weather
 9
10    mock_weather = request.param
11    with patch.object(app.main, 'fetch_weather', new=mock_fetch_weather_factory(mock_weather)):
12        yield

And then, when we call our test, we need to decorate it with pytest.mark.parametrize, and pass in the fixture as an argument. I’ve set up two tests here so we can really see how it works.

 1# File: tests/test_weather_api.py
 2@pytest.mark.parametrize('mock_fetch_weather_parametrized', ['cloudy'], indirect=True)
 3def test_get_weather_parameterized(client, mock_fetch_weather_parametrized):
 4    response = client.get("/weather/atlanta")
 5    assert response.status_code == 200
 6    assert response.json() == {'city': 'atlanta', 'weather': 'cloudy'}
 7
 8
 9@pytest.mark.parametrize('mock_fetch_weather_parametrized', ['tornados'], indirect=True)
10def test_get_weather_parameterized(client, mock_fetch_weather_parametrized):
11    response = client.get("/weather/atlanta")
12    assert response.status_code == 200
13    assert response.json() == {'city': 'atlanta', 'weather': 'tornados'}

The parameterized fixture is more complicated to set up, but it is incredibly useful in practice when you have to simulate different responses from external APIs.

Mocking MongoDB

Our FastAPI application interacts with MongoDB. During testing, we might not want to (or really be able to in some cases) hit a real database with real/mocked data. Instead, we acn mock MongoDB by using the mongomock library, which simulates a MongoDB client. (Note: In my experience, mongomock can be difficult to work with and some practice to get working, but were going to proceed with it for now)

Creating a Mock MongoDB Client

In our application, we employ context management for database interactions, utilizing Python’s with statement. This demands that the object used within the with statement must implement context management protocols, specifically __enter__ and __exit__ methods.

 1# File: app/db.py
 2@contextmanager
 3def get_mongodb():
 4    try:
 5        with MongoClient() as client:
 6            db = client["preferences"]
 7            yield db
 8    except Exception as e:
 9        print(f'Error: {e}')
10        raise

The mongomock library doesn’t implement these methods, so to align with these requirements, we define a custom MockMongoClient class to wrap our mongomock client. This class mimics the behavior of the actual MongoClient by implementing the __enter__ and __exit__ methods. This ensures compatibility with the existing code that expects a context-managed database client.

 1# File: tests/conftest.py
 2class MockMongoClient:
 3    def __init__(self, db):
 4        self.db = db
 5
 6    def __enter__(self):
 7        return self.db
 8
 9    def __exit__(self, *args):
10        pass

Using our MockMongoClient class, we can now create our mock database client. We’ll do this in a fixture so we can reuse it in multiple tests.

Creating a Mock MongoDB Client Fixtures

I’m going to initialize two separate fixtures here, one with an empty database and one with some data initialized. (In theory, we should be able to set the scope of the fixture to session or module and just initialize the database once, add data through other tests, and then use that data for testing later, but I haven’t been able to get that working with mongomock. The project seems to have been designed more with unit tests in mind and is not a complete implementation or drop in replacement. If you know how to make this work, please let me know!)

1# File: tests/conftest.py
2@pytest.fixture
3def mock_mongodb():
4    def mock_get_mongodb():
5        mock_client = MongoClient()
6        return MockMongoClient(mock_client.db)
7
8    return mock_get_mongodb

and initialize some data…

1# File: tests/conftest.py
2@pytest.fixture
3def mock_mongodb_initialized():
4    def mock_get_mongodb():
5        mock_client = MongoClient()
6        mock_client.db.preferences.insert_one({"username": "alexjacobs", "city": "Berlin"})
7        return MockMongoClient(mock_client.db)
8
9    return mock_get_mongodb

And now we can write our tests. We’ll pass in our fixture and again use the dependency_overrides feature to inject our mock database client into our app (overriding the get_mongodb function)

Writing Tests Integration Tests Using Our Mocked MongoDB Client

We’ve got three simple tests here.
First, we test that our endpoint correctly returns a 404 if no user preferences exist (we use our non-initialized mock_mongodb fixture for this)

Next, we use our initialized mock_mongodb fixture to test that our endpoint correctly returns the user preferences.

Finally, we test that we can save user preferences (we use our non-initialized mock_mongodb fixture for this, but it should work with either)

 1# File: tests/user_preference_api.py
 2from app.main import app
 3from app.fake_db import get_mongodb
 4
 5
 6def test_get_user_preferences_404(client, mock_mongodb):
 7    # should return 404 since no user preferences exist
 8    app.dependency_overrides[get_mongodb] = mock_mongodb
 9    response = client.get("/users/me/preferences")
10    assert response.status_code == 404
11    assert response.json() == {'detail': 'Preferences not found'}
12
13
14def test_get_user_preferences_initialized(client, mock_mongodb_initialized):
15    # we're using our mock_mongodb_initialized fixture here which has our user preferences already set
16    app.dependency_overrides[get_mongodb] = mock_mongodb_initialized
17    response = client.get("/users/me/preferences")
18    assert response.status_code == 200
19    assert response.json() == {'city': 'Berlin'}
20
21
22def test_post_user_preferences(client, mock_mongodb):
23    app.dependency_overrides[get_mongodb] = mock_mongodb
24    response = client.post("/users/me/preferences", json={"city": "Berlin"})
25    assert response.status_code == 200
26    assert response.json() == {"detail": "success"}

And that’s it! Pretty simple to write the actual tests once we have our mocked database client set up correctly.

Mocking AWS S3

Our FastAPI application interacts with AWS S3 for storing and retrieving user profile pictures. During testing, we don’t want to use a real S3 bucket because it would require us to manage real AWS resources. This would complicate our tests and potentially incur costs. Therefore, we mock the S3 bucket. (The same patterns used here could be applied to other AWS services)

Creating the Mock S3 Fixture

We mock the S3 bucket by using the mock_s3 decorator from the moto library, which simulates an S3 bucket. This is done in a fixture so we can reuse it in multiple tests.

(moto is a great library for mocking AWS services, and you’ll see we are able to set our fixture scope to session, allowing us to maintain bucket state across multiple tests)

 1# File: tests/conftest.py
 2@pytest.fixture(scope="session")
 3def mock_s3_bucket():
 4    with mock_s3():
 5        conn = boto3.resource('s3', region_name='us-east-1')
 6        conn.create_bucket(Bucket=bucket)
 7        # we could upload a test file(s) here if we wanted to
 8        # s3_client = boto3.client('s3', region_name='us-east-1')
 9        # s3_client.upload_file('tests/assets/duck.png', bucket, 'profile_pics/alexjacobs.png') 
10        yield

Integrating with Test Client

This looks similar to our MockMongo fixtures, but this time, rather than pass our fixture into our tests, we pass it into the client fixture.

 1# File: tests/conftest.py
 2@pytest.fixture
 3def client(mock_s3_bucket):
 4    # we patch auth within our client fixture
 5    from app.main import app
 6
 7    def mock_get_auth():
 8        return TokenData(username="alexjacobs")
 9
10    app.dependency_overrides[get_auth] = mock_get_auth
11    with TestClient(app) as test_client:
12        yield test_client
13
14    app.dependency_overrides.clear()

Writing the Tests

Now we can write our tests. We’ll start by testing that we get the right message if no profile picture exists for the user

1# File: tests / test_user_preference_api.py
2def test_get_user_profile_pic_404(client):
3    response = client.get("/users/me/profile_pic")
4    assert response.status_code == 404
5    assert response.json() == {'detail': 'No profile pic found'}

Now we’ll test adding one…

1# File: tests/test_user_preference_api.py
2def test_set_user_profile_pic(client):
3    with open('tests/assets/duck.png', 'rb') as f:
4        response = client.post("/users/me/profile_pic", files={"picture": ("duck.png", f, "image/png")})
5
6    assert response.status_code == 200
7    assert response.json() == {'detail': 'success'}

Finally, we can test getting one. (notice how this is using the same file we uploaded in the previous test, this is due to the fact that we’re using the session scope for our mock_s3_bucket fixture)

1# File: tests/test_user_preference_api.py
2def test_get_user_profile_pic(client):
3    response = client.get("/users/me/profile_pic")
4    assert response.status_code == 200
5    with open('tests/assets/duck.png', 'rb') as f:
6        original_image_data = f.read()
7        original_base64 = base64.b64encode(original_image_data).decode('utf-8')
8
9    assert response.json()['image'] == original_base64

Wrapping Up

This was a fairly deep dive. We’ve unraveled the intricacies of integration testing in FastAPI, which is not without its challenges when it comes to mocking external dependencies. We’ve gone through a variety of techniques to mock authentication, from simple dependency_overrides to more advanced fixture-based strategies. We’ve also tackled how to mock external APIs using Python’s unittest.mock.patch and pytest’s parametrized fixtures.

When it comes to databases, MongoDB adds another layer of complexity. We’ve seen how Mongomock can be a useful tool, albeit with its own set of limitations. We crafted custom mock MongoDB clients and fixtures to ease this pain point. As for AWS S3, the Moto library proved to be a robust tool, enabling us to mock S3 buckets effectively, even allowing state persistence across tests.

The aim has been to arm you with a set of tools and strategies for your FastAPI testing arsenal. Whether it’s a simple authentication mock or a more complex external service, you should now be equipped to tackle these head-on. Happy testing.

Happy testing.