Si vous avez évité d’écrire des tests parce qu’ils vous semblent une corvée, ce tutoriel pytest devrait vous faire changer d’avis. Pytest supprime la majeure partie de la cérémonie : il n’y a aucune classe dont on peut hériter et aucune méthode d’assertion spéciale à retenir. Un test peut comporter seulement deux lignes.

Nous allons construire un petit panier et le tester étape par étape. Nous avons tout exécuté sur Python 3.13 avec pytest 9.2, et le résultat affiché est réel, bien que nous ayons supprimé les chemins de fichiers et les détails de synchronisation qui différeront sur votre machine.

Pourquoi pytester ?

Python est livré avec unittest, qui fonctionne bien, mais pytest est généralement le choix le plus pratique. Voici le même chèque dans chacun :

Pytest peut également exécuter vos tests unittest existants, afin que vous puissiez basculer progressivement. Il dispose également d’un vaste écosystème de plugins, comprenant pytest-cov pour la couverture et pytest-xdist pour les exécutions parallèles.

Installer pytest

Créez d’abord un environnement virtuel, comme expliqué dans notre Tutoriel sur l’environnement virtuel Python, puis installez-le :

pip install pytest
pytest --version

# pytest 9.2.0

Créez un dossier de projet contenant deux fichiers, cart.py et test_cart.py. Pytest trouve automatiquement les tests en suivant les règles de dénomination : fichiers nommés test_*.py ou *_test.py, fonctions commençant par test et classes commençant par Test. Si un test n’est pas récupéré, une incompatibilité de nom est la première chose à vérifier.

Le code à tester

# cart.py
class Cart:
    def __init__(self):
        self.items = []

    def add(self, name, price, qty=1):
        if qty < 1:
            raise ValueError("qty must be at least 1")
        self.items.append((name, price, qty))

    def total(self, discount=0):
        subtotal = sum(price * qty for _, price, qty in self.items)
        return round(subtotal * (1 - discount / 100), 2)

Vos premiers tests

# test_cart.py
from cart import Cart

def test_empty_cart_is_free():
    assert Cart().total() == 0

C’est un test complet. Exécutez pytest à partir du dossier du projet et il signale un test réussi. Si vous obtenez une erreur d’importation, exécutez-la en tant que python -m pytest, ce qui ajoute le dossier actuel au chemin d’importation.

Échecs de lecture

C’est là que pytest brille vraiment. Voici un test avec une valeur attendue volontairement erronée :

def test_wrong_total():
    c = Cart()
    c.add("Keyboard", 1500)
    assert c.total() == 1400

Et voici ce qu’il a imprimé lorsque nous l’avons exécuté :

    def test_wrong_total():
        c = Cart()
        c.add("Keyboard", 1500)
>       assert c.total() == 1400
E       assert 1500.0 == 1400
E        +  where 1500.0 = total()

FAILED fail_example.py::test_wrong_total - assert 1500.0 == 1400
============================== 1 failed in 0.12s ==============================

Le > marque la ligne défaillante et les lignes E affichent les valeurs réelles. Vous n’avez pas besoin d’ajouter un message personnalisé, car pytest réécrit les instructions assert afin qu’elles puissent rapporter ce qu’elles ont comparé. Il fait la même chose pour les listes et les dictionnaires, en indiquant exactement quels éléments diffèrent.

Test des exceptions

La gestion des erreurs est aussi un comportement et mérite des tests. pytest.raises ne passe que si le bloc lève l’exception attendue :

import pytest

def test_rejects_zero_qty():
    with pytest.raises(ValueError, match="at least 1"):
        Cart().add("Pen", 10, qty=0)

L’argument facultatif match vérifie le message à l’aide d’une expression régulière, donc un autre ValueError ne passera pas par accident. Pour savoir comment générer et gérer des erreurs comme celle-ci, lisez notre guide sur la Gestion des exceptions Python.

Luminaires : configuration réutilisable

La plupart des tests nécessitent d’abord quelque chose de préparé. Un luminaire est une fonction qui le fournit. Décorez-le avec @pytest.fixture, et tout test qui le nomme comme argument reçoit le résultat :

@pytest.fixture
def cart():
    c = Cart()
    c.add("Keyboard", 1500)
    c.add("Mouse", 500, qty=2)
    return c

def test_total(cart):
    assert cart.total() == 2500

Chaque test reçoit un nouveau panier par défaut, les tests ne peuvent donc pas s’influencer mutuellement. Pytest fait correspondre le nom de l’argument au nom de l’appareil, et vous n’appelez jamais l’appareil vous-même. @pytest.fixture est un décorateur, que nous expliquons dans Les décorateurs Python expliqués.

Nettoyage avec rendement

Utilisez yield au lieu de return lorsque vous devez nettoyer par la suite. Le code après yield s’exécute à la fin du test, même s’il échoue :

@pytest.fixture
def temp_db():
    print("\nopen db")
    yield {"users": []}
    print("close db")

def test_db(temp_db):
    assert temp_db["users"] == []

L’exécution avec -s pour afficher la sortie imprimée a confirmé que la commande était ouverte, testée, puis fermée.

Portée du luminaire et conftest.py

Par défaut, un appareil s’exécute une fois par test. Pour une configuration coûteuse, comme une base de données ou un navigateur, modifiez sa durée de vie avec scope :

Mettez les appareils utilisés par plusieurs fichiers dans un fichier appelé conftest.py. Pytest le charge automatiquement, afin que les tests puissent utiliser ses appareils sans importation. Soyez prudent avec les étendues partagées, car une modification apportée par un test peut s’infiltrer dans le suivant.

Paramétrer : un test, plusieurs entrées

Plutôt que de copier un test pour chaque valeur, listez les cas :

@pytest.mark.parametrize("discount, expected", [
    (0, 2500),
    (10, 2250),
    (100, 0),
])
def test_discount(cart, discount, expected):
    assert cart.total(discount) == expected

Chaque ligne devient son propre test, et vous pouvez le voir dans le résultat détaillé de notre exécution du fichier complet :

test_cart.py::test_total PASSED                        [ 16%]
test_cart.py::test_discount[0-2500] PASSED             [ 33%]
test_cart.py::test_discount[10-2250] PASSED            [ 50%]
test_cart.py::test_discount[100-0] PASSED              [ 66%]
test_cart.py::test_rejects_zero_qty PASSED             [ 83%]
test_cart.py::test_empty_cart_is_free PASSED           [100%]

============================== 6 passed in 0.05s ==============================

Si une ligne échoue, les autres s’exécutent toujours et le nom vous indique exactement quelles valeurs sont à l’origine du problème. Notez que nous avons combiné le paramétrage avec le luminaire cart. Pour choisir les valeurs susceptibles de détecter des bogues, utilisez l’analyse des valeurs limites.

Luminaires intégrés utiles

Pytest comprend plusieurs appareils prêts à l’emploi. Ces deux-là sont particulièrement utiles, et tous deux ont réussi notre test :

def test_write_report(tmp_path):
    report = tmp_path / "report.txt"
    report.write_text("passed")
    assert report.read_text() == "passed"

def read_mode():
    return os.environ.get("APP_MODE", "dev")

def test_mode(monkeypatch):
    monkeypatch.setenv("APP_MODE", "staging")
    assert read_mode() == "staging"

tmp_path donne à chaque test un dossier temporaire unique, afin que les tests ne touchent jamais de vrais fichiers. monkeypatch modifie les variables ou les attributs d’environnement et annule la modification à la fin du test. Un autre outil utile est capsys, qui capture la sortie imprimée afin que vous puissiez la vérifier.

Marqueurs : sauter et xfail

Les marqueurs ajoutent des étiquettes et des comportements aux tests :

@pytest.mark.skip(reason="payment sandbox is down")
def test_payment():
    assert False

@pytest.mark.xfail(reason="floating point")
def test_rounding():
    assert 0.1 + 0.2 == 0.3

skip n’exécute pas du tout le test. xfail l’exécute mais s’attend à un échec, donc un problème connu n’interrompt pas votre build. Avec les autres tests supplémentaires dans le même fichier, notre exécution se résume à 3 passed, 1 skipped, 1 xfailed. D’ailleurs, ce test d’arrondi échoue vraiment : en arithmétique à virgule flottante, 0,1 + 0,2 n’est pas exactement 0,3. Utilisez pytest.approx(0.3) pour comparer des décimales.

Vous pouvez également créer vos propres marqueurs, tels que @pytest.mark.slow, et exécuter uniquement ceux avec pytest -m slow, ou les laisser de côté avec -m "not slow". Enregistrez des marqueurs personnalisés dans votre fichier de configuration pour éviter les avertissements.

Indicateurs de ligne de commande utiles

Exécuter pytest dans CI

Les tests sont plus utiles lorsqu’ils s’exécutent automatiquement à chaque modification. Un travail GitHub Actions minimal ressemble à ceci :

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: "3.13"
  - run: pip install -r requirements.txt
  - run: python -m pytest

Pytest se termine avec un code différent de zéro lorsque les tests échouent, ce qui entraîne l’arrêt du pipeline. Nous n’avons pas exécuté ce fichier de workflow, alors adaptez-le à votre projet. Notre Guide CI/CD GitHub Actions explique les détails. Pytest fonctionne également bien pour les tests de navigateur, comme le montrent nos Tutoriel Selenium Python et Tutoriel Modèle d’objet de page.

Pour conclure

Vous disposez désormais de ce dont vous avez besoin pour la plupart des suites de tests Python : des assertions simples, des paramètres pour la configuration, des paramètres pour les variations et quelques indicateurs pour la vitesse. Commencez petit. Choisissez une fonction dans laquelle vous avez récemment corrigé un bug et écrivez d’abord un test pour ce bug. Si vous ne savez pas quoi tester à chaque niveau, lisez les informations sur les tests unitaires et d’intégration.

Questions fréquentes

Continuez à apprendre