--- title: "Outils de test" version: 4.0 locale: fr source: https://docs.djangoproject.com/fr/4.0/topics/testing/tools/ canonical: https://djangodocs.dev/fr/4.0/topics/testing/tools/ --- # Outils de test Django propose un petit set d’outils bien pratiques lors de l’écriture de tests. ## Le client de test Le client de test est une classe Python se comportant comme un navigateur web simpliste, permettant de tester les vues et d’interagir par programmation avec votre application Django. Voici plusieurs choses que vous pouvez faire avec le client de test : - Simuler des requêtes GET et POST sur une URL et examiner la réponse, que ce soit les détails HTTP de bas niveau (en-têtes de la réponse et codes d’état) ou le contenu de la page renvoyée. - Voir la chaîne des redirections (le cas échéant) et contrôler l’URL et le code de statut à chaque étape. - Tester qu’une requête données est rendue par un gabarit Django donné, et que le contexte du gabarit contient certaines valeurs. Notez que le client de test n’est pas conçu pour remplacer [Selenium](https://www.selenium.dev/) ou d’autres systèmes utilisant un navigateur réel. Le client de test de Django a un objectif différent. En bref : - Utiliser le client de test de Django pour confirmer que le gabarit correct a été utilisé pour le rendu et que ce gabarit à reçu les bonnes données de contexte. - Utilisez des systèmes basés sur de vrais navigateurs comme [Selenium](https://www.selenium.dev/) pour tester le HTML *produit* et le *comportement* des pages web, en particulier les fonctionnalités JavaScript. Django offre aussi une prise en charge spéciale pour ces systèmes ; consultez la section sur [`LiveServerTestCase`](#django.test.LiveServerTestCase) pour plus de détails. Une suite de tests complète devrait utiliser une combinaison de ces deux types. ### Aperçu et exemple rapide Pour utiliser le client de test, créez une instance de `django.test.Client` et récupérez des pages web : ``` >>> from django.test import Client >>> c = Client() >>> response = c.post('/login/', {'username': 'john', 'password': 'smith'}) >>> response.status_code 200 >>> response = c.get('/customer/details/') >>> response.content b'>> c.get('/login/') ``` Mais pas ceci : ``` >>> c.get('https://www.example.com/login/') ``` Le client de test n’est pas capable de récupérer des pages web qui ne sont pas basées sur votre projet Django. Si vous avez besoin de récupérer d’autres pages web, utilisez un module standard de la bibliothèque Python, comme [`urllib`](https://docs.python.org/3/library/urllib.html#module-urllib). - Pour résoudre des URL, le client de test utilise la configuration d’URL qui est désignée par le réglage [`ROOT_URLCONF`](/fr/4.0/ref/settings/#std-setting-ROOT_URLCONF). - Même si l’exemple ci-dessus fonctionne dans un interpréteur Python interactif, certaines fonctionnalités du client de test, notamment celles liées aux gabarits, ne sont disponibles que *lorsque les tests sont lancés*. Ceci s’explique par le fait que le lanceur de tests de Django fait sa propre cuisine pour déterminer quel gabarit a été chargé pour une vue donnée. Cette « cuisine » (essentiellement un correctif en mémoire du système de gabarits de Django) n’est opérée que durant le fonctionnement des tests. - Par défaut, le client de test désactive tous les contrôles CSRF effectués par votre site. Si pour une raison quelconque vous \* voulez\* que le client de test effectue les contrôles CSRF, vous pouvez créer une instance du client de test avec les contrôles CSRF actifs. Pour cela, passez le paramètre `enforce_csrf_checks` au moment de créer le client : ``` >>> from django.test import Client >>> csrf_client = Client(enforce_csrf_checks=True) ``` ### Lancement de requêtes La classe `django.test.Client` permet de simuler des requêtes HTTP. #### `class Client(enforce_csrf_checks=False, json_encoder=DjangoJSONEncoder, **defaults)` Aucun paramètre n’est obligatoire au moment de la création de l’instance. Vous pouvez cependant indiquer des paramètres nommés pour définir des en-têtes par défaut. Dans l’exemple suivant, un en-tête HTTP `User-Agent` est envoyé avec chaque requête : ``` >>> c = Client(HTTP_USER_AGENT='Mozilla/5.0') ``` Les valeurs de paramètres nommés passés dans `extra` aux méthodes [`get()`](#django.test.Client.get), [`post()`](#django.test.Client.post), etc. ont la priorité sur les valeurs par défaut transmises au constructeur de la classe. Le paramètre `enforce_csrf_checks` peut être utilisé pour tester la protection CSRF (voir au-dessus). Le paramètre `json_encoder` permet de définir un codeur JSON personnalisé pour la sérialisation JSON décrite dans [`post()`](#django.test.Client.post). Le paramètre `raise_request_exception` permet de contrôler si les exceptions générées pendant la requête doivent aussi être générées dans le test. Vaut `True` par défaut. Dès que vous avez à disposition une instance de `Client`, vous pouvez appeler au choix l’une des méthodes suivantes : #### `get(path, data=None, follow=False, secure=False, **extra)` Procède à une requête GET utilisant le chemin `path` indiqué et renvoie un objet `Response`, qui est documenté plus bas. Les paires clé-valeur dans le dictionnaire `data` servent à créer les données utiles de GET. Par exemple : ``` >>> c = Client() >>> c.get('/customers/details/', {'name': 'fred', 'age': 7}) ``` …aboutit à l’évaluation d’une requête GET équivalente à : ``` /customers/details/?name=fred&age=7 ``` Le paramètre nommé `extra` peut être utilisé pour indiquer les en-têtes envoyés avec la requête. Par exemple : ``` >>> c = Client() >>> c.get('/customers/details/', {'name': 'fred', 'age': 7}, ... HTTP_ACCEPT='application/json') ``` …envoie l’en-tête HTTP `HTTP_ACCEPT` à la vue de détail, ce qui constitue une bonne manière de tester des chemins de code utilisant la méthode [`django.http.HttpRequest.accepts()`](/fr/4.0/ref/request-response/#django.http.HttpRequest.accepts). > **Spécification CGI** > > Les en-têtes envoyés par `**extra` doivent respecter la spécification [CGI](https://www.w3.org/CGI/). Par exemple, pour émuler un en-tête « Host » différent de celui envoyé dans la requête HTTP du navigateur vers le serveur, il faut transmettre `HTTP_HOST`. Si vous disposez déjà des paramètres GET sous une forme déjà codée pour l’URL, vous pouvez utiliser cette forme au lieu du paramètre `data`. Par exemple, la requête GET précédente pourrait aussi être émise par : ``` >>> c = Client() >>> c.get('/customers/details/?name=fred&age=7') ``` Si vous fournissez à la fois une URL contenant des données GET codée et un paramètre `data`, ce dernier a la priorité. Si vous définissez `follow` à `True`, le client suit d’éventuelles redirections et l’objet réponse possédera un attribut `redirect_chain` contenant des tuples formés des URL intermédiaires et de leur code d’état. Si vous aviez une URL `/redirect_me/` redirigeant vers `/next/`, redirigeant lui-même vers `/final/`, voici ce que vous obtiendriez : ``` >>> response = c.get('/redirect_me/', follow=True) >>> response.redirect_chain [('http://testserver/next/', 302), ('http://testserver/final/', 302)] ``` Si vous définissez `secure` à `True`, le client émule une requête HTTPS. #### `post(path, data=None, content_type=MULTIPART_CONTENT, follow=False, secure=False, **extra)` Procède à une requête POST utilisant le chemin `path` indiqué et renvoie un objet `Response`, qui est documenté plus bas. Les paires clé-valeur dans le dictionnaire `data` servent à créer les données de soumission POST. Par exemple : ``` >>> c = Client() >>> c.post('/login/', {'name': 'fred', 'passwd': 'secret'}) ``` …aboutit à l’évaluation d’une requête POST vers cette URL : ``` /login/ ``` …contenant ces données POST : ``` name=fred&passwd=secret ``` Si vous indiquez `application/json` dans `content_type`, les données `data` sont sérialisées en utilisant [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps) s’il s’agit d’un dict, d’une liste ou d’un tuple. La sérialisation est appliquée par défaut avec [`DjangoJSONEncoder`](/fr/4.0/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder), mais cette classe peut être remplacée en fournissant le paramètre `json_encoder` à [`Client`](#django.test.Client). Cette sérialisation se produit également pour les requêtes [`put()`](#django.test.Client.put), [`patch()`](#django.test.Client.patch) et [`delete()`](#django.test.Client.delete). Si vous renseignez tout autre `content_type` (par ex. `text/xml` pour des données utiles XML), le contenu de `data` est envoyé tel quel dans la requête POST, en plaçant le contenu de `content_type` dans l’en-tête HTTP `Content-Type`. Si le paramètre `content_type` n’est pas renseigné, les valeurs contenues dans `data` sont transmises avec un type de contenu `multipart/form-data`. Dans ce cas, les paires clé-valeur de `data` sont codées sous forme de message composite (`multipart`) et servent à créer les données utiles de POST. Pour envoyer plusieurs valeurs pour un même clé, par exemple pour indiquer les sélections d’un élément `', '' ) ``` `html1` et `html2` doivent contenir du code HTML. Une exception `AssertionError` est générée si l’une de ces deux valeurs ne peut pas être analysée comme du code HTML. L’affichage en cas d’erreur peut être personnalisé avec le paramètre `msg`. > **Changed in Django 4.0** > > Dans les anciennes versions, tout attribut (pas seulement les booléens) sans valeur était considéré comme égal à un attribut avec le nom et la valeur identique. #### `SimpleTestCase.assertHTMLNotEqual(html1, html2, msg=None)` Confirme que les chaînes `html1` et `html2` ne sont *pas* équivalentes. La comparaison prend en compte la sémantique HTML. Voir [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual) pour plus de détails. `html1` et `html2` doivent contenir du code HTML. Une exception `AssertionError` est générée si l’une de ces deux valeurs ne peut pas être analysée comme du code HTML. L’affichage en cas d’erreur peut être personnalisé avec le paramètre `msg`. #### `SimpleTestCase.assertXMLEqual(xml1, xml2, msg=None)` Confirme que les chaînes `xml1` et `xml2` sont équivalentes. La comparaison prend en compte la sémantique XML. Sur le même principe que [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual), la comparaison se fait sur le contenu analysé, ce qui fait que seules les différences sémantiques sont prises en compte, pas la syntaxe elle-même. Si le contenu XML de l’un des paramètres n’est pas valide, une exception `AssertionError` est toujours générée, même si les deux chaînes sont identiques. La déclaration XML, le type de document, les instructions de traitement et les commentaires sont ignorés. Seul l’élément racine (root) et ses descendants sont comparés. L’affichage en cas d’erreur peut être personnalisé avec le paramètre `msg`. #### `SimpleTestCase.assertXMLNotEqual(xml1, xml2, msg=None)` Confirme que les chaînes `xml1` et `xml2` ne sont *pas* équivalentes. La comparaison prend en compte la sémantique xML. Voir [`assertXMLEqual()`](#django.test.SimpleTestCase.assertXMLEqual) pour plus de détails. L’affichage en cas d’erreur peut être personnalisé avec le paramètre `msg`. #### `SimpleTestCase.assertInHTML(needle, haystack, count=None, msg_prefix='')` Confirme que le fragment HTML `needle` est contenu dans le contenu `haystack`. Si le paramètre nombre entier `count` est indiqué, un contrôle supplémentaire est effectué que le nombre d’occurrences de `needle` correspond à `count`. Dans la plupart des cas, les blancs sont ignorés et l’ordre des attributs n’est pas pris en compte. Voir [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual) pour plus de détails. #### `SimpleTestCase.assertJSONEqual(raw, expected_data, msg=None)` Confirme que les fragments JSON `raw` et `expected_data` sont égaux. Les règles habituelles de JSON concernant les blancs non significatifs s’appliquent, car le gros du travail est confié à la bibliothèque [`json`](https://docs.python.org/3/library/json.html#module-json). L’affichage en cas d’erreur peut être personnalisé avec le paramètre `msg`. #### `SimpleTestCase.assertJSONNotEqual(raw, expected_data, msg=None)` Confirme que les fragments JSON `raw` et `expected_data` *ne sont pas* égaux. Voir [`assertJSONEqual()`](#django.test.SimpleTestCase.assertJSONEqual) pour plus de détails. L’affichage en cas d’erreur peut être personnalisé avec le paramètre `msg`. #### `TransactionTestCase.assertQuerysetEqual(qs, values, transform=None, ordered=True, msg=None)` Confirme que le jeu de requête `qs` correspond à une itération particulière de valeurs `values`. Si `transform` est indiqué, `values` est comparé à une liste produite en appliquant `transform` à chaque membre de `qs`. Par défaut, la comparaison dépend aussi de l’ordre de tri. Si `qs` ne comporte pas d’ordre de tri implicite, vous pouvez définir le paramètre `ordered` à `False`, ce qui provoquera une comparaison sur des objets `collections.Counter`. Si l’ordre est indéfini (si le paramètre `qs` n’est pas trié et que la comparaison se fait avec plus d’une valeur triée) une exception `ValueError` est générée. L’affichage en cas d’erreur peut être personnalisé avec le paramètre `msg`. > **Changed in Django 3.2** > > La valeur par défaut de l’argument `transform` est passée à `None`. > **New in Django 3.2** > > La prise en charge de la comparaison directe entre jeux de requête a été ajoutée. > **Deprecated since Django 3.2** > > Obsolète depuis la version 3.2: Si `transform` n’est pas fourni et que `values` est une liste de chaînes, la comparaison se fait avec une liste produite en appliquant `repr()` à chaque membre de `qs`. Ce comportement est obsolète et sera supprimé dans Django 4.1. Si vous souhaitez le conserver, définissez explicitement `transform` à `repr`. #### `TransactionTestCase.assertNumQueries(num, func, *args, **kwargs)` Confirme que lorsque `func` est appelée avec `*args` et `**kwargs`, `num` requêtes de base de données sont effectuées. Si une clé `"using"` est présente dans `kwargs`, cette valeur est utilisée comme alias de base de données pour laquelle le nombre de requêtes sera contrôlé ``` self.assertNumQueries(7, using='non_default_db') ``` Si vous souhaitez appeler une fonction avec un paramètre `using`, vous pouvez le faire en enveloppant l’appel dans une fonction `lambda` pour y ajouter un paramètre supplémentaire ``` self.assertNumQueries(7, lambda: my_function(using=7)) ``` Vous pouvez également l’utiliser comme un gestionnaire de contexte : ``` with self.assertNumQueries(2): Person.objects.create(name="Aaron") Person.objects.create(name="Daniel") ``` ### Étiquetage des tests Il est possible d’étiqueter les tests afin de pouvoir plus facilement lancer un sous-ensemble particulier. Par exemple, vous pourriez étiqueter les tests rapides ou lents : ``` from django.test import tag class SampleTestCase(TestCase): @tag('fast') def test_fast(self): ... @tag('slow') def test_slow(self): ... @tag('slow', 'core') def test_slow_but_core(self): ... ``` Il est aussi possible d’étiqueter un cas de test : ``` @tag('slow', 'core') class SampleTestCase(TestCase): ... ``` Les sous-classes héritent des classes parentes, et les méthodes héritent des étiquettes de leur classe. Par exemple ``` @tag('foo') class SampleTestCaseChild(SampleTestCase): @tag('bar') def test(self): ... ``` `SampleTestCaseChild.test` possédera les étiquettes `'slow'`, `'core'`, `'bar'` et `'foo'`. Puis, vous pouvez choisir quels tests lancer. Par exemple, pour ne lancer que les tests rapides : ```console $ ./manage.py test --tag=fast ``` *Windows* ```doscon ...\> manage.py test --tag=fast ``` Ou pour lancer les tests rapides et les tests principaux (même s’ils sont lents) : ```console $ ./manage.py test --tag=fast --tag=core ``` *Windows* ```doscon ...\> manage.py test --tag=fast --tag=core ``` Il est aussi possible d’exclure des tests par leur étiquette. Pour lancer les tests principaux qui ne sont pas lents : ```console $ ./manage.py test --tag=core --exclude-tag=slow ``` *Windows* ```doscon ...\> manage.py test --tag=core --exclude-tag=slow ``` [`test --exclude-tag`](/fr/4.0/ref/django-admin/#cmdoption-test-exclude-tag) a la priorité sur [`test --tag`](/fr/4.0/ref/django-admin/#cmdoption-test-tag), si donc un test possède deux étiquettes et que vous choisissez l’une d’elle tout en excluant l’autre, le test ne sera pas lancé. ## Test de code asynchrone Si vous souhaitez simplement tester le résultat de vues asynchrones, le client de test standard les lance dans une boucle asynchrone dédiée sans travail supplémentaire de votre part. Cependant, si vous souhaitez écrire des tests pleinement asynchrones pour un projet Django, vous devrez prendre en compte plusieurs choses. Tout d’abord, vos tests doivent être des méthodes `async def` de la classe de test (afin de leur fournir un contexte asynchrone). Django détectera automatiquement tout test de type `async def` et les enveloppera afin qu’ils s’exécutent dans leur propre boucle événementielle. Si vous testez depuis une fonction asynchrone, vous devez éaglement utiliser le client de test asynchrone. Il est disponible comme `django.test.AsyncClient` ou comme `self.async_client` dans chaque test. `AsyncClient` possède les mêmes méthodes et signatures que le client de test synchrone (normal), avec deux exceptions : - Le paramètre `follow` n’est pas pris en charge. - Les en-têtes transmis dans le paramètre nommé `extra` ne doivent pas comporter de préfixe `HTTP_` tel que requis par le client synchrone (voir [`Client.get()`](#django.test.Client.get)). Par exemple, voici comment définir un en-tête HTTP `Accept`: ``` >>> c = AsyncClient() >>> c.get( ... '/customers/details/', ... {'name': 'fred', 'age': 7}, ... ACCEPT='application/json' ... ) ``` En utilisant `AsyncClient`, toute méthode effectuant une requête doit être appelée avec `await`: ``` async def test_my_thing(self): response = await self.async_client.get('/some-url/') self.assertEqual(response.status_code, 200) ``` Le client asynchrone peut aussi appeler des vues synchrones ; il s’exécute au travers du [chemin de requête asynchrone](/fr/4.0/topics/async/) de Django, qui prend en charge les deux modes. Toute vue appelée par `AsyncClient` reçoit un objet `ASGIRequest` dans son attribut `request` au lieu de l’objet `WSGIRequest` créé par le client normal. > **Warning** > > Si vous utilisez des décorateurs de tests, ils doivent être compatibles avec l’asynchrone pour fonctionner correctement. Les décorateurs intégrés de Django se comporteront correctement, mais ceux de tierces parties peuvent sembler ne pas s’exécuter (ils « enveloppent » la mauvaise partie du flux d’exécution au lieu de votre test). > > Si vous avez besoin d’utiliser ces décorateurs, vous devez alors plutôt décorer vos méthodes de test avec [`async_to_sync()`](/fr/4.0/topics/async/#asgiref.sync.async_to_sync) *à l’intérieur* de celles-ci : > > ``` > from asgiref.sync import async_to_sync > from django.test import TestCase > > class MyTests(TestCase): > > @mock.patch(...) > @async_to_sync > async def test_my_thing(self): > ... > ``` ## Services de messagerie Si l’une de vos vues Django envoie des courriels via la [fonctionnalité d’envoi de courriels de Django](/fr/4.0/topics/email/), vous ne souhaiterez probablement pas réellement envoyer un courriel lors de chaque test de cette vue. C’est pour cette raison que le lanceur de tests de Django redirige automatiquement tous les courriels qu’il envoie dans une boîte artificielle. Cela vous permet aussi de tester chaque aspect de l’envoi de courriels, du nombre de messages envoyés jusqu’au contenu de chaque message, sans jamais envoyer réellement les messages. Le lanceur de tests fait cela en remplaçant de manière transparente le moteur de messagerie normal par un moteur de test (n’ayez crainte, cela n’a aucun effet sur l’expédition de courriels en dehors de Django, comme un éventuel serveur de messagerie tournant sur votre machine). #### `django.core.mail.outbox` Durant le fonctionnement des tests, chaque courriel sortant est enregistré dans `django.core.mail.outbox`. Il s’agit d’une liste de toutes les instances de [`EmailMessage`](/fr/4.0/topics/email/#django.core.mail.EmailMessage) qui ont été envoyées. L’attribut `outbox` est un attribut spécial qui est *uniquement* créé lorsque le moteur de messagerie `locmem` est actif. Il ne fait normalement pas partie du module [`django.core.mail`](/fr/4.0/topics/email/#module-django.core.mail) et il ne peut être importé directement. Le code ci-dessous montre comment accéder correctement à cet attribut. Voici un exemple de test qui examine la longueur et le contenu de `django.core.mail.outbox`: ``` from django.core import mail from django.test import TestCase class EmailTest(TestCase): def test_send_email(self): # Send message. mail.send_mail( 'Subject here', 'Here is the message.', 'from@example.com', ['to@example.com'], fail_silently=False, ) # Test that one message has been sent. self.assertEqual(len(mail.outbox), 1) # Verify that the subject of the first message is correct. self.assertEqual(mail.outbox[0].subject, 'Subject here') ``` Comme noté [précédemment](#emptying-test-outbox), la boîte de messagerie de test est vidée au début de chaque test des classes Django `*TestCase`. Pour vider la boîte manuellement, attribuez une liste vide à `mail.outbox`: ``` from django.core import mail # Empty the test outbox mail.outbox = [] ``` ## Commandes d’administration Les commandes d’administration peuvent être testées avec la fonction [`call_command()`](/fr/4.0/ref/django-admin/#django.core.management.call_command). La sortie peut être redirigée vers une instance de `StringIO`: ``` from io import StringIO from django.core.management import call_command from django.test import TestCase class ClosepollTest(TestCase): def test_command_output(self): out = StringIO() call_command('closepoll', stdout=out) self.assertIn('Expected output', out.getvalue()) ``` ## Exclusion de tests La bibliothèque unittest fournit les décorateurs [`@skipIf`](https://docs.python.org/3/library/unittest.html#unittest.skipIf) rz [`@skipUnless`](https://docs.python.org/3/library/unittest.html#unittest.skipUnless) pour permettre d’exclure des tests si vous savez à l’avance que ces tests vont échouer dans certaines conditions. Par exemple, si la réussite d’un test exige la présence d’une certaine bibliothèque, il est possible de décorer le cas de test avec [`@skipIf`](https://docs.python.org/3/library/unittest.html#unittest.skipIf). Puis, le lanceur de tests signalera que le test n’a pas été exécuté ainsi que la raison, au lieu de laisser le test échouer ou d’ignorer totalement le test. En plus de ces comportements d’exclusion de test, Django ajoute deux décorateurs de test supplémentaires. Au lieu de se baser sur une valeur booléenne générique, ces décorateurs contrôlent les capacités d’une base de données et excluent le test concerné si la base de données ne gère pas la capacité nommément indiquée. Ces décorateurs utilisent un identifiant textuel pour désigner les capacités de base de données. Cet identifiant correspond à un attribut de la classe des capacités de connexion de base de données. Voir [la classe django.db.backends.base.features.BaseDatabaseFeatures](https://github.com/django/django/blob/stable/4.0.x/django/db/backends/base/features.py) pour obtenir une liste complète des capacités de base de données pouvant être utilisées comme critères d’exclusion de tests. #### `skipIfDBFeature(*feature_name_strings)` Exclut le test ou la classe `TestCase` décorés si toutes les capacités de base de données indiquées sont prises en charge. Par exemple, le test suivant ne sera pas exécuté si la base de données gère les transactions (par ex. il ne serait *pas* exécuté avec PostgreSQL, mais il le serait avec MySQL utilisant des tables MyISAM) : ``` class MyTests(TestCase): @skipIfDBFeature('supports_transactions') def test_transaction_behavior(self): # ... conditional test code pass ``` #### `skipUnlessDBFeature(*feature_name_strings)` Exclut le test ou la classe `TestCase` décorés si au moins une des capacités de base de données indiquées *n’est pas* prise en charge. Par exemple, le test suivant ne sera exécuté que si la base de données gère les transactions (par ex. il serait exécuté avec PostgreSQL, mais il ne le serait *pas* avec MySQL utilisant des tables MyISAM) ``` class MyTests(TestCase): @skipUnlessDBFeature('supports_transactions') def test_transaction_behavior(self): # ... conditional test code pass ```