Maîtriser les tests FastAPI : Un guide complet de TestClient

FastAPI est devenu un framework de premier plan pour la construction d'API haute performance avec Python. Sa rapidité, sa facilité d'utilisation et la validation automatique des données en font un favori parmi les développeurs du monde entier. Cependant, une API bien construite n'est aussi bonne que ses tests. Des tests approfondis garantissent que votre API fonctionne comme prévu, reste stable sous pression et peut être déployée en production en toute confiance. Ce guide complet se concentre sur l'utilisation du TestClient de FastAPI pour tester efficacement vos points de terminaison d'API.

Pourquoi les tests sont-ils importants pour les applications FastAPI ?

Les tests sont une étape cruciale du cycle de vie du développement logiciel. Cela vous aide à :

• Identifier les bugs tôt : Détecter les erreurs avant qu'elles n'atteignent la production, ce qui permet d'économiser du temps et des ressources.
• Assurer la qualité du code : Promouvoir un code bien structuré et maintenable.
• Prévenir les régressions : Garantir que les nouvelles modifications ne cassent pas les fonctionnalités existantes.
• Améliorer la fiabilité de l'API : Renforcer la confiance dans la stabilité et les performances de l'API.
• Faciliter la collaboration : Fournir une documentation claire du comportement attendu pour les autres développeurs.

Présentation du TestClient de FastAPI

FastAPI fournit un TestClient intégré qui simplifie le processus de test de vos points de terminaison d'API. Le TestClient agit comme un client léger qui peut envoyer des requêtes à votre API sans démarrer un serveur à part entière. Cela rend les tests considérablement plus rapides et plus pratiques.

Principales caractéristiques de TestClient :

• Simule les requêtes HTTP : Vous permet d'envoyer des requêtes GET, POST, PUT, DELETE et d'autres requêtes HTTP à votre API.
• Gère la sérialisation des données : Sérialise automatiquement les données de requête (par exemple, les charges utiles JSON) et désérialise les données de réponse.
• Fournit des méthodes d'assertion : Offre des méthodes pratiques pour vérifier le code d'état, les en-têtes et le contenu des réponses.
• Prend en charge les tests asynchrones : Fonctionne de manière transparente avec la nature asynchrone de FastAPI.
• S'intègre aux frameworks de test : S'intègre facilement aux frameworks de test Python populaires comme pytest et unittest.

Configuration de votre environnement de test

Avant de commencer les tests, vous devez configurer votre environnement de test. Cela implique généralement l'installation des dépendances nécessaires et la configuration de votre framework de test.

Installation

Tout d'abord, assurez-vous d'avoir FastAPI et pytest installés. Vous pouvez les installer en utilisant pip :

            pip install fastapi pytest httpx
            

              
                Copy
              
            
          

httpx est un client HTTP que FastAPI utilise en coulisses. Bien que TestClient fasse partie de FastAPI, le fait d'avoir httpx installé garantit également des tests fluides. Certains tutoriels mentionnent également requests, cependant, httpx est plus aligné sur la nature asynchrone de FastAPI.

Exemple d'application FastAPI

Créons une application FastAPI simple que nous pouvons utiliser pour les tests :

            from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None

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

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
 return {"item_id": item_id, "q": q}

@app.post("/items/")
async def create_item(item: Item):
 return item

            

              
                Copy
              
            
          

Enregistrez ce code sous le nom de main.py. Cette application définit trois points de terminaison :

• / : Un point de terminaison GET simple qui renvoie un message "Hello World".
• /items/{item_id} : Un point de terminaison GET qui renvoie un élément en fonction de son ID.
• /items/ : Un point de terminaison POST qui crée un nouvel élément.

Écrire votre premier test

Maintenant que vous avez une application FastAPI, vous pouvez commencer à écrire des tests en utilisant le TestClient. Créez un nouveau fichier nommé test_main.py dans le même répertoire que main.py.

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_read_root():
 response = client.get("/")
 assert response.status_code == 200
 assert response.json() == {"message": "Hello World"}

            

              
                Copy
              
            
          

Dans ce test :

• Nous importons TestClient et l'instance app de FastAPI.
• Nous créons une instance de TestClient, en passant app.
• Nous définissons une fonction de test test_read_root.
• À l'intérieur de la fonction de test, nous utilisons client.get("/") pour envoyer une requête GET au point de terminaison racine.
• Nous affirmons que le code d'état de la réponse est 200 (OK).
• Nous affirmons que le JSON de la réponse est égal à {"message": "Hello World"}.

Exécuter vos tests avec pytest

Pour exécuter vos tests, ouvrez simplement un terminal dans le répertoire contenant votre fichier test_main.py et exécutez la commande suivante :

            pytest
            

              
                Copy
              
            
          

pytest découvrira et exécutera automatiquement tous les tests de votre projet. Vous devriez voir une sortie similaire à ceci :

            ============================= test session starts ==============================
platform darwin -- Python 3.9.6, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /path/to/your/project
collected 1 item

test_main.py .

============================== 1 passed in 0.01s ===============================
            

              
                Copy
              
            
          

Tester différentes méthodes HTTP

Le TestClient prend en charge toutes les méthodes HTTP standard, y compris GET, POST, PUT, DELETE et PATCH. Voyons comment tester chacune de ces méthodes.

Tester les requêtes GET

Nous avons déjà vu un exemple de test d'une requête GET dans la section précédente. Voici un autre exemple, testant le point de terminaison /items/{item_id} :

            def test_read_item():
 response = client.get("/items/1?q=test")
 assert response.status_code == 200
 assert response.json() == {"item_id": 1, "q": "test"}

            

              
                Copy
              
            
          

Ce test envoie une requête GET à /items/1 avec un paramètre de requête q=test. Il affirme ensuite que le code d'état de la réponse est 200 et que le JSON de la réponse contient les données attendues.

Tester les requêtes POST

Pour tester une requête POST, vous devez envoyer des données dans le corps de la requête. Le TestClient sérialise automatiquement les données en JSON.

            def test_create_item():
 item_data = {"name": "Example Item", "description": "A test item", "price": 9.99, "tax": 1.00}
 response = client.post("/items/", json=item_data)
 assert response.status_code == 200
 assert response.json() == item_data

            

              
                Copy
              
            
          

Dans ce test :

• Nous créons un dictionnaire item_data contenant les données du nouvel élément.
• Nous utilisons client.post("/items/", json=item_data) pour envoyer une requête POST au point de terminaison /items/, en passant item_data comme charge utile JSON.
• Nous affirmons que le code d'état de la réponse est 200 et que le JSON de la réponse correspond à item_data.

Tester les requêtes PUT, DELETE et PATCH

Tester les requêtes PUT, DELETE et PATCH est similaire au test des requêtes POST. Vous utilisez simplement les méthodes correspondantes sur le TestClient :

            def test_update_item():
 item_data = {"name": "Updated Item", "description": "An updated test item", "price": 19.99, "tax": 2.00}
 response = client.put("/items/1", json=item_data)
 assert response.status_code == 200
 # Add assertions for the expected response

def test_delete_item():
 response = client.delete("/items/1")
 assert response.status_code == 200
 # Add assertions for the expected response

def test_patch_item():
 item_data = {"price": 29.99}
 response = client.patch("/items/1", json=item_data)
 assert response.status_code == 200
 # Add assertions for the expected response
            

              
                Copy
              
            
          

N'oubliez pas d'ajouter des assertions pour vérifier que les réponses sont comme prévu.

Techniques de test avancées

Le TestClient offre plusieurs fonctionnalités avancées qui peuvent vous aider à écrire des tests plus complets et efficaces.

Tester avec des dépendances

Le système d'injection de dépendances de FastAPI vous permet d'injecter facilement des dépendances dans vos points de terminaison d'API. Lors des tests, vous pouvez remplacer ces dépendances pour fournir des implémentations simulées ou spécifiques aux tests.

Par exemple, supposons que votre application dépende d'une connexion à la base de données. Vous pouvez remplacer la dépendance de la base de données dans vos tests pour utiliser une base de données en mémoire :

            from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import sessionmaker, declarative_base, Session

# Database Configuration
DATABASE_URL = "sqlite:///./test.db"  # In-memory database for testing
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

# Define User Model
class User(Base):
 __tablename__ = "users"

 id = Column(Integer, primary_key=True, index=True)
 username = Column(String, unique=True, index=True)
 password = Column(String)

Base.metadata.create_all(bind=engine)

# FastAPI App
app = FastAPI()

# Dependency to get the database session
def get_db():
 db = TestingSessionLocal()
 try:
 yield db
 finally:
 db.close()

# Endpoint to create a user
@app.post("/users/")
async def create_user(username: str, password: str, db: Session = Depends(get_db)):
 db_user = User(username=username, password=password)
 db.add(db_user)
 db.commit()
 db.refresh(db_user)
 return db_user

            

              
                Copy
              
            
          

            from fastapi.testclient import TestClient
from .main import app, get_db, Base, engine, TestingSessionLocal

client = TestClient(app)

# Override the database dependency for testing

def override_get_db():
 try:
 db = TestingSessionLocal()
 yield db
 finally:
 db.close()

app.dependency_overrides[get_db] = override_get_db

def test_create_user():
 # First, ensure the tables are created, which may not happen by default
 Base.metadata.create_all(bind=engine) # important: create the tables in the test db
 response = client.post("/users/", params={"username": "testuser", "password": "password123"})
 assert response.status_code == 200
 assert response.json()["username"] == "testuser"

 # Clean up the override after the test if needed
app.dependency_overrides = {}

            

              
                Copy
              
            
          

Cet exemple remplace la dépendance get_db par une fonction spécifique au test qui renvoie une session à une base de données SQLite en mémoire. Important : La création des métadonnées doit être explicitement invoquée pour que la base de données de test fonctionne correctement. Si la table n'est pas créée, des erreurs liées à l'absence de tables se produiront.

Tester le code asynchrone

FastAPI est conçu pour être asynchrone, vous devrez donc souvent tester le code asynchrone. Le TestClient prend en charge les tests asynchrones de manière transparente.

Pour tester un point de terminaison asynchrone, définissez simplement votre fonction de test comme async :

            import asyncio

from fastapi import FastAPI

app = FastAPI()

@app.get("/async")
async def async_endpoint():
 await asyncio.sleep(0.1) # Simulate some async operation
 return {"message": "Async Hello"}

            

              
                Copy
              
            
          

            import pytest
from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

@pytest.mark.asyncio # Needed to be compatible with pytest-asyncio
async def test_async_endpoint():
 response = client.get("/async")
 assert response.status_code == 200
 assert response.json() == {"message": "Async Hello"}

            

              
                Copy
              
            
          

Remarque : Vous devez installer pytest-asyncio pour utiliser @pytest.mark.asyncio : pip install pytest-asyncio. Vous devez également vous assurer que asyncio.get_event_loop() est configuré si vous utilisez d'anciennes versions de pytest. Si vous utilisez pytest version 8 ou plus récente, cela peut ne pas être nécessaire.

Tester le téléchargement de fichiers

FastAPI facilite la gestion des téléchargements de fichiers. Pour tester les téléchargements de fichiers, vous pouvez utiliser le paramètre files des méthodes de requête du TestClient.

            from fastapi import FastAPI, File, UploadFile
from typing import List

app = FastAPI()

@app.post("/files/")
async def create_files(files: List[bytes] = File()):
 return {"file_sizes": [len(file) for file in files]}

@app.post("/uploadfiles/")
async def create_upload_files(files: List[UploadFile]):
 return {"filenames": [file.filename for file in files]}

            

              
                Copy
              
            
          

            from fastapi.testclient import TestClient
from .main import app
import io

client = TestClient(app)

def test_create_files():
 file_content = b"Test file content"
 files = [('files', ('test.txt', io.BytesIO(file_content), 'text/plain'))]
 response = client.post("/files/", files=files)
 assert response.status_code == 200
 assert response.json() == {"file_sizes": [len(file_content)]}

def test_create_upload_files():
 file_content = b"Test upload file content"
 files = [('files', ('test_upload.txt', io.BytesIO(file_content), 'text/plain'))]
 response = client.post("/uploadfiles/", files=files)
 assert response.status_code == 200
 assert response.json() == {"filenames": ["test_upload.txt"]}

            

              
                Copy
              
            
          

Dans ce test, nous créons un fichier factice en utilisant io.BytesIO et nous le transmettons au paramètre files. Le paramètre files accepte une liste de tuples, où chaque tuple contient le nom du champ, le nom du fichier et le contenu du fichier. Le type de contenu est important pour une gestion précise par le serveur.

Tester la gestion des erreurs

Il est important de tester la façon dont votre API gère les erreurs. Vous pouvez utiliser le TestClient pour envoyer des requêtes non valides et vérifier que l'API renvoie les réponses d'erreur correctes.

            from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
 if item_id > 100:
 raise HTTPException(status_code=400, detail="Item ID too large")
 return {"item_id": item_id}

            

              
                Copy
              
            
          

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_read_item_error():
 response = client.get("/items/101")
 assert response.status_code == 400
 assert response.json() == {"detail": "Item ID too large"}

            

              
                Copy
              
            
          

Ce test envoie une requête GET à /items/101, qui lève une HTTPException avec un code d'état de 400. Le test affirme que le code d'état de la réponse est 400 et que le JSON de la réponse contient le message d'erreur attendu.

Tester les fonctionnalités de sécurité

Si votre API utilise l'authentification ou l'autorisation, vous devrez également tester ces fonctionnalités de sécurité. Le TestClient vous permet de définir des en-têtes et des cookies pour simuler des requêtes authentifiées.

            from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm

app = FastAPI()

# Security
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
 # Simulate authentication
 if form_data.username != "testuser" or form_data.password != "password123":
 raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Incorrect username or password")
 return {"access_token": "fake_token", "token_type": "bearer"}

@app.get("/protected")
async def protected_route(token: str = Depends(oauth2_scheme)):
 return {"message": "Protected data"}

            

              
                Copy
              
            
          

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_login():
 response = client.post("/token", data={"username": "testuser", "password": "password123"})
 assert response.status_code == 200
 assert "access_token" in response.json()

def test_protected_route():
 # First, get a token
 token_response = client.post("/token", data={"username": "testuser", "password": "password123"})
 token = token_response.json()["access_token"]

 # Then, use the token to access the protected route
 response = client.get("/protected", headers={"Authorization": f"Bearer {token}"}) # corrected format.
 assert response.status_code == 200
 assert response.json() == {"message": "Protected data"}

            

              
                Copy
              
            
          

Dans cet exemple, nous testons le point de terminaison de connexion, puis nous utilisons le token obtenu pour accéder à une route protégée. Le paramètre headers des méthodes de requête du TestClient vous permet de définir des en-têtes personnalisés, y compris l'en-tête Authorization pour les jetons bearer.

Meilleures pratiques pour les tests FastAPI

Voici quelques bonnes pratiques à suivre lors du test de vos applications FastAPI :

• Écrivez des tests complets : Visez une couverture de test élevée pour vous assurer que toutes les parties de votre API sont testées de manière approfondie.
• Utilisez des noms de test descriptifs : Assurez-vous que les noms de vos tests indiquent clairement ce que le test vérifie.
• Suivez le modèle Arrange-Act-Assert : Organisez vos tests en trois phases distinctes : Arrange (préparer les données de test), Act (effectuer l'action testée) et Assert (vérifier les résultats).
• Utilisez des objets mock : Simulez les dépendances externes pour isoler vos tests et éviter de vous fier aux systèmes externes.
• Testez les cas limites : Testez votre API avec des entrées non valides ou inattendues pour vous assurer qu'elle gère les erreurs avec élégance.
• Exécutez les tests fréquemment : Intégrez les tests dans votre flux de travail de développement pour détecter les bugs tôt et souvent.
• Intégrez avec CI/CD : Automatisez vos tests dans votre pipeline CI/CD pour vous assurer que toutes les modifications de code sont testées de manière approfondie avant d'être déployées en production. Des outils comme Jenkins, GitLab CI, GitHub Actions ou CircleCI peuvent être utilisés pour y parvenir.

Exemple : Test d'internationalisation (i18n)

Lors du développement d'API pour un public mondial, l'internationalisation (i18n) est essentielle. Tester l'i18n implique de vérifier que votre API prend correctement en charge plusieurs langues et régions. Voici un exemple de la façon dont vous pouvez tester l'i18n dans une application FastAPI :

            from fastapi import FastAPI, Header
from typing import Optional

app = FastAPI()

messages = {
 "en": {"greeting": "Hello, world!"},
 "fr": {"greeting": "Bonjour le monde !"},
 "es": {"greeting": "¡Hola Mundo!"},
}

@app.get("/")
async def read_root(accept_language: Optional[str] = Header(None)):
 lang = accept_language[:2] if accept_language else "en"
 if lang not in messages:
 lang = "en"
 return {"message": messages[lang]["greeting"]}

            

              
                Copy
              
            
          

            from fastapi.testclient import TestClient
from .main import app

client = TestClient(app)

def test_read_root_en():
 response = client.get("/", headers={"Accept-Language": "en-US"})
 assert response.status_code == 200
 assert response.json() == {"message": "Hello, world!"}

def test_read_root_fr():
 response = client.get("/", headers={"Accept-Language": "fr-FR"})
 assert response.status_code == 200
 assert response.json() == {"message": "Bonjour le monde !"}

def test_read_root_es():
 response = client.get("/", headers={"Accept-Language": "es-ES"})
 assert response.status_code == 200
 assert response.json() == {"message": "¡Hola Mundo!"}

def test_read_root_default():
 response = client.get("/")
 assert response.status_code == 200
 assert response.json() == {"message": "Hello, world!"}

            

              
                Copy
              
            
          

Cet exemple définit l'en-tête Accept-Language pour spécifier la langue souhaitée. L'API renvoie le message d'accueil dans la langue spécifiée. Les tests garantissent que l'API gère correctement les différentes préférences linguistiques. Si l'en-tête Accept-Language est absent, la langue par défaut "en" est utilisée.

Conclusion

Les tests sont une partie essentielle de la création d'applications FastAPI robustes et fiables. Le TestClient fournit un moyen simple et pratique de tester vos points de terminaison d'API. En suivant les meilleures pratiques décrites dans ce guide, vous pouvez écrire des tests complets qui garantissent la qualité et la stabilité de vos API. Des requêtes de base aux techniques avancées telles que l'injection de dépendances et les tests asynchrones, le TestClient vous permet de créer un code bien testé et maintenable. Adoptez les tests comme une partie essentielle de votre flux de travail de développement, et vous créerez des API à la fois puissantes et fiables pour les utilisateurs du monde entier. N'oubliez pas l'importance de l'intégration CI/CD pour automatiser les tests et assurer une assurance qualité continue.