TestClient basics in FastAPI - Mini Project: Build & Apply

TestClient basics

📖 Scenario: You are building a simple FastAPI app that returns a greeting message. You want to test this app using FastAPI's TestClient to make sure it works correctly.

🎯 Goal: Create a FastAPI app with one route, then write a test using TestClient to check the response status and content.

📋 What You'll Learn

Create a FastAPI app instance named app

Add a GET route /hello that returns JSON {"message": "Hello, FastAPI!"}

Create a TestClient instance using the app

Write a test function test_hello() that sends a GET request to /hello

Assert the response status code is 200

Assert the response JSON matches {"message": "Hello, FastAPI!"}

💡 Why This Matters

🌍 Real World

Testing web APIs is essential to ensure they work correctly before deployment. FastAPI's TestClient lets you simulate requests without running a server.

💼 Career

Backend developers often write automated tests for APIs to catch bugs early and maintain code quality. Knowing how to use TestClient is a key skill.

1

Create the FastAPI app with a greeting route

Create a FastAPI app instance called app. Add a GET route /hello that returns JSON {"message": "Hello, FastAPI!"}.

FastAPI

from fastapi import FastAPI

# Create FastAPI app instance

# Add GET route /hello

Hint

Use FastAPI() to create the app. Use @app.get("/hello") decorator for the route. Return the dictionary with the message.

2

Import TestClient and create a client instance

Import TestClient from fastapi.testclient. Create a client instance using the app.

FastAPI

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/hello")
async def read_hello():
    return {"message": "Hello, FastAPI!"}

# Create TestClient instance

Hint

Import TestClient and create client = TestClient(app).

3

Write a test function to request the /hello route

Write a test function called test_hello(). Inside it, use client.get("/hello") to send a GET request and store the response in response.

FastAPI

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/hello")
async def read_hello():
    return {"message": "Hello, FastAPI!"}

client = TestClient(app)

# Write test function test_hello

Hint

Define def test_hello(): and call client.get("/hello") inside it.

4

Assert the response status and JSON content

Inside test_hello(), add assertions to check that response.status_code is 200 and response.json() equals {"message": "Hello, FastAPI!"}.

FastAPI

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/hello")
async def read_hello():
    return {"message": "Hello, FastAPI!"}

client = TestClient(app)

def test_hello():
    response = client.get("/hello")
    # Add assertions for status code and JSON content

Hint

Use assert response.status_code == 200 and assert response.json() == {"message": "Hello, FastAPI!"}.

Practice

1. What is the main purpose of FastAPI's TestClient?

easy

A. To test FastAPI applications without running a real server

B. To deploy FastAPI applications to production

C. To generate API documentation automatically

D. To create database migrations for FastAPI apps

Solution

1. Step 1: Understand what TestClient does

   TestClient simulates HTTP requests to your FastAPI app internally without needing a real server.

2. Step 2: Compare options with TestClient's purpose

   Only To test FastAPI applications without running a real server describes testing without a real server, which matches TestClient's role.

3. Final Answer:

   To test FastAPI applications without running a real server -> Option A

4. Quick Check:

   TestClient purpose = testing without server [OK]

Hint: TestClient runs tests without starting a real server [OK]

Common Mistakes:

• Confusing TestClient with deployment tools
• Thinking TestClient generates docs
• Assuming TestClient manages databases

2. Which of the following is the correct way to import and create a TestClient instance for a FastAPI app named app?

easy

A. from fastapi import TestClient
client = TestClient(app)

B. from fastapi.testclient import Client
client = Client(app)

C. import TestClient from fastapi
client = TestClient(app)

D. from fastapi.testclient import TestClient
client = TestClient(app)

Solution

1. Step 1: Recall correct import path

   The TestClient is imported from fastapi.testclient, not directly from fastapi or other names.

2. Step 2: Check instantiation syntax

   TestClient is instantiated by passing the FastAPI app object as an argument.

3. Final Answer:

   from fastapi.testclient import TestClient\nclient = TestClient(app) -> Option D

4. Quick Check:

   Correct import and instantiation = from fastapi.testclient import TestClient client = TestClient(app) [OK]

Hint: Import TestClient from fastapi.testclient exactly [OK]

Common Mistakes:

• Importing TestClient directly from fastapi
• Using wrong class name like Client
• Incorrect import syntax

3. Given this FastAPI app and test code, what will response.status_code be?

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/hello")
def hello():
    return {"message": "Hi"}

client = TestClient(app)
response = client.get("/hello")
print(response.status_code)

medium

A. 404

B. 403

C. 200

D. 500

Solution

1. Step 1: Check route definition

   The app defines a GET route at "/hello" that returns a JSON message with status 200 by default.

2. Step 2: Analyze the test client request

   The client sends a GET request to "/hello", which matches the route, so the response status code is 200.

3. Final Answer:

   200 -> Option C

4. Quick Check:

   GET /hello returns 200 status [OK]

Hint: Matching route returns 200 status by default [OK]

Common Mistakes:

• Assuming 404 because of missing route
• Thinking 500 due to server error
• Confusing status codes

4. What is wrong with this test code using TestClient?

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

client = TestClient(app)
response = client.get("/items/item1")
print(response.status_code)

medium

A. The route path parameter expects an int, but 'item1' is a string

B. TestClient is not imported correctly

C. The route decorator is missing parentheses

D. The app instance is not created

Solution

1. Step 1: Check route parameter type

   The route expects an integer item_id but the test sends 'item1' which is a string.

2. Step 2: Understand FastAPI's type validation

   FastAPI will reject the request with a 422 error because 'item1' cannot be converted to int.

3. Final Answer:

   The route path parameter expects an int, but 'item1' is a string -> Option A

4. Quick Check:

   Type mismatch in path parameter causes error [OK]

Hint: Match path parameter types exactly in test URLs [OK]

Common Mistakes:

• Ignoring type mismatch in path parameters
• Assuming string works for int parameters
• Overlooking FastAPI validation errors

5. You want to test a POST endpoint /users/ that expects JSON data {"name": "Alice"}. Which TestClient call correctly sends this data and checks for a 201 status code?

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.post("/users/")
def create_user(user: dict):
    return user, 201

client = TestClient(app)
# Which call is correct?

hard

A. response = client.get("/users/", json={"name": "Alice"})
assert response.status_code == 201

B. response = client.post("/users/", json={"name": "Alice"})
assert response.status_code == 201

C. response = client.post("/users/", data="{'name': 'Alice'}")
assert response.status_code == 201

D. response = client.post("/users/", params={"name": "Alice"})
assert response.status_code == 201

Solution

1. Step 1: Identify correct HTTP method and data format

   The endpoint expects a POST request with JSON data. Using json= sends JSON correctly.

2. Step 2: Check status code assertion

   The endpoint returns status 201 on success, so asserting response.status_code == 201 is correct.

3. Final Answer:

   response = client.post("/users/", json={"name": "Alice"})\nassert response.status_code == 201 -> Option B

4. Quick Check:

   POST with json= and check 201 status [OK]

Hint: Use json= for POST JSON data, not data= or params= [OK]

Common Mistakes:

• Using GET instead of POST
• Sending data as string instead of JSON
• Using params instead of JSON body