--- title: "Les tests unitaires" version: 2.2 locale: fr source: https://docs.djangoproject.com/fr/2.2/internals/contributing/writing-code/unit-tests/ canonical: https://djangodocs.dev/fr/2.2/internals/contributing/writing-code/unit-tests/ --- # Les tests unitaires Django est livré avec sa propre suite de tests, dans le répertoire `tests` de la base de code. Notre politique est de nous assurer que tous les tests passent en tout temps. Nous apprécions toute contribution à la suite de tests ! Les tests de Django utilisent tous l’infrastructure de tests livrée avec Django pour tester les applications. Consultez [Écriture et lancement de tests](/fr/2.2/topics/testing/overview/) pour une explication sur la façon d’écrire de nouveaux tests. ## Lancement des tests unitaires ### Démarrage rapide Tout d’abord, créez votre [fork de Django sur GitHub](https://github.com/django/django/fork). Ensuite, créez et activez un environnement virtuel. Si vous n’êtes pas familier avec cette procédure, lisez le [tutoriel de contribution](/fr/2.2/intro/contributing/). Puis, créez un clone local de votre fork, installez quelques dépendances et lancez la suite de tests ```console $ git clone https://github.com/YourGitHubName/django.git django-repo $ cd django-repo/tests $ pip install -e .. $ pip install -r requirements/py3.txt $ ./runtests.py ``` L’installation des dépendances nécessite probablement l’installation de paquets de votre système d’exploitation. Il est généralement possible de savoir quels paquets installer en faisant une recherche Web à propos des dernières lignes du message d’erreur. Essayez d’ajouter le nom de votre système d’exploitation à la requête si nécessaire. Si vous avez des soucis d’installation des dépendances, vous pouvez omettre cette étape. Voir [Lancement de tous les tests](#running-unit-tests-dependencies) pour des détails sur l’installation des dépendances facultatives des tests. Si l’une des dépendances facultatives n’est pas installée, les tests qui l’exigent seront passés (skipped). Le lancement des tests exige un module de réglages Django définissant la base de données à utiliser. Pour faciliter le démarrage, Django fournit et utilise un module de réglages d’exemple utilisant la base de données SQLite. Voir [Utilisation d’un autre module de réglages settings](#running-unit-tests-settings) pour apprendre comment utiliser un module de réglages différent pour lancer les tests avec une autre base de données. > **Utilisateurs de Windows** > > Nous recommandons quelque chose comme [Git Bash](https://msysgit.github.io/) pour lancer les tests en utilisant l’approche ci-dessus. Des problèmes ? Voir [Dépannage](#troubleshooting-unit-tests) pour certaines problématiques courantes. ### Lancement des tests avec `tox` [Tox](https://tox.readthedocs.io/) est un outil pour exécuter des tests dans différents environnement virtuels. Django contient un fichier `tox.ini` basique qui automatise certains contrôles que notre serveur de construction effectue pour les requêtes de contribution. Pour exécuter les tests unitaires et autres contrôles (tels que l”[ordre des importations](/fr/2.2/internals/contributing/writing-code/coding-style/#coding-style-imports), la [correction orthographique de la documentation](/fr/2.2/internals/contributing/writing-documentation/#documentation-spelling-check) et la [mise en forme du code](/fr/2.2/internals/contributing/writing-code/coding-style/#coding-style-python)), installez et lancez la commande `tox` depuis n’importe quel endroit de l’arborescence source de Django ```console $ pip install tox $ tox ``` Par défaut, `tox` lance la suite de tests avec le fichier de réglages inclu pour SQLite, flake8\`, `isort` et la correction orthographique de la documentation. En plus des dépendances système mentionnées ailleurs dans cette documentation, la commande `python3` doit se trouver dans votre chemin et être liée à la version appropriée de Python. Une liste des environnements par défaut peut être listée comme suit ```console $ tox -l py3 flake8 docs isort ``` #### Test avec d’autres versions de Python et de moteurs de base de données En plus des environnements par défaut, `tox` prend en charge le lancement des tests unitaires pour d’autres versions de Python et de moteurs de base de données. Comme la suite de tests de Django ne livre pas de fichier de réglages pour les bases de données autres que SQLite, vous devez donc [créer et fournir vos propres réglages de tests](#running-unit-tests-settings). Par exemple, pour lancer les tests avec Python 3.5 en utilisant PostgreSQL ```console $ tox -e py35-postgres -- --settings=my_postgres_settings ``` Cette commande configure un environnement virtuel Python 3.5, installe les dépendances de la suite de tests de Django (y compris celles pour PostgreSQL) et appelle `runtests.py` avec les paramètres fournis (dans ce cas, `--settings=my_postgres_settings`). Le reste de cette documentation montre des commandes pour lancer les tests sans `tox`. Cependant, toute option transmise à `runtests.py` peut également être transmise à `tox` en préfixant la liste des paramètres par `--`, comme ci-dessus. Tox respecte également la variable d’environnement `DJANGO_SETTINGS_MODULE` quand elle est définie. Par exemple, la commande ci-dessous est équivalente à la précédente ```console $ DJANGO_SETTINGS_MODULE=my_postgres_settings tox -e py35-postgres ``` #### Lancement des tests JavaScript Django contient un ensemble de [tests unitaires JavaScript](/fr/2.2/internals/contributing/writing-code/javascript/#javascript-tests) ciblant des fonctions de certaines applications contrib. Les tests JavaScript ne sont pas lancés par défaut avec `tox` car ils ont besoin que Node.js soit installé et ne sont pas nécessaires pour la majorité des correctifs. Pour lancer les tests JavaScript en utilisant `tox`: ```console $ tox -e javascript ``` Cette commande exécute `npm install` pour s’assurer que les logiciels exigés par les tests sont à jour, puis lance `npm test`. ### Running tests using `django-docker-box` [django-docker-box](https://github.com/django/django-docker-box) allows you to run the Django’s test suite across all supported databases and python versions. See the [django-docker-box](https://github.com/django/django-docker-box) project page for installation and usage instructions. ### Utilisation d’un autre module de réglages `settings` Le module de réglages inclus (`tests/test_sqlite.py`) permet de lancer la suite de tests avec SQLite. Si vous souhaitez lancer les tests avec une autre base de données, vous devez définir votre propre fichier de réglages. Certains tests, comme ceux de `contrib.postgres`, sont spécifique à un moteur de base de données spécifique et seront omis quand une autre base de données est utilisée. Pour lancer les tests avec des réglages différents, assurez-vous que le module se trouve dans le chemin `PYTHONPATH` et indiquez ce module avec `--settings`. Le réglage [`DATABASES`](/fr/2.2/ref/settings/#std-setting-DATABASES) dans tout module de réglages pour les tests doit définir deux bases de données : - Une base de données `default`. Celle-ci doit utiliser le moteur que vous souhaitez tester de manière principale. - Une base de données avec l’alias `other`. Celle-ci est utilisée pour tester les requêtes qui sont dirigées vers d’autres bases de données. Elle devrait utiliser le même moteur que la base de données `default`, mais elle doit avoir un autre nom. Si vous utilisez un moteur autre que SQLite, il est nécessaire de fournir d’autres détails pour chaque base de données : - L’option [`USER`](/fr/2.2/ref/settings/#std-setting-USER) doit indiquer un compte utilisateur existant pour la base de données. Cet utilisateur a besoin de la permission d’exécuter `CREATE DATABASE` afin de pouvoir créer la base de données de test. - L’option [`PASSWORD`](/fr/2.2/ref/settings/#std-setting-PASSWORD) doit indiquer le mot de passe à utiliser pour l’utilisateur [`USER`](/fr/2.2/ref/settings/#std-setting-USER). Les noms des bases de données de test sont composés par le préfixe `test_` devant les réglages [`NAME`](/fr/2.2/ref/settings/#std-setting-NAME) des bases de données définies dans [`DATABASES`](/fr/2.2/ref/settings/#std-setting-DATABASES). Ces bases de données de test sont détruites lorsque les tests sont terminés. Vous devez aussi vous assurer que votre base de données utilise UTF-8 comme jeu de caractères par défaut. Si votre serveur de base de données n’utilise pas le jeu de caractères UTF-8 par défaut, vous devrez inclure une valeur pour le réglage [`CHARSET`](/fr/2.2/ref/settings/#std-setting-TEST_CHARSET) du dictionnaire des réglages de test pour la base de données concernée. ### Lancement de tests spécifiques La suite de tests complète de Django prend un certain temps à s’exécuter, et le lancement de tous les tests pourrait être superflu si par exemple vous avez juste ajouté un test à Django et que vous voulez le lancer rapidement sans tout le reste des tests. Il est possible de lancer un sous-ensemble des tests unitaires en ajoutant les noms des modules de test à `runtests.py` dans la ligne de commande. Par exemple, si vous souhaitez lancer les tests uniquement pour les relations génériques et la régionalisation, saisissez ```console $ ./runtests.py --settings=path.to.settings generic_relations i18n ``` Comment trouver les noms des tests individuels ? Regardez dans `tests/` — chaque nom de répertoire est le nom d’un module de tests. Si vous souhaitez uniquement lancer une classe précise de tests, vous pouvez indiquer une liste de chemins vers les classes de test concernées. Par exemple, pour lancer les tests `TranslationTests` du module `i18n`, saisissez ```console $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests ``` Pour aller encore plus loin, vous pouvez indiquer une méthode de test individuelle comme ceci ```console $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects ``` ### Lancement des tests Selenium Certains tests requièrent Selenium et un navigateur Web. Pour lancer ces tests, vous devez installer le paquet [selenium](https://pypi.org/project/selenium/) et lancer les tests avec l’option `--selenium=`. Par exemple, si Firefox et Google Chrome sont installés ```console $ ./runtests.py --selenium=firefox,chrome ``` Consultez le paquet [selenium.webdriver](https://github.com/SeleniumHQ/selenium/tree/master/py/selenium/webdriver) pour obtenir la liste des navigateurs disponibles. L’indication de `--selenium` définit automatiquement `--tags=selenium` pour ne lancer que les tests exigeant selenium. ### Lancement de tous les tests Si vous souhaitez lancer la suite de tests complète, vous devrez installer un certain nombre de dépendances : - [argon2-cffi](https://pypi.org/project/argon2_cffi/) 16.1.0+ - [bcrypt](https://pypi.org/project/bcrypt/) - [docutils](https://pypi.org/project/docutils/) - [geoip2](https://pypi.org/project/geoip2/) - [jinja2](https://pypi.org/project/jinja2/) 2.7+ - [numpy](https://pypi.org/project/numpy/) - [Pillow](https://pypi.org/project/Pillow/) 4.2.0+ - [PyYAML](https://pyyaml.org/wiki/PyYAML) - [pytz](https://pypi.org/project/pytz/) (obligatoire) - [pywatchman](https://pypi.org/project/pywatchman/) - [setuptools](https://pypi.org/project/setuptools/) - [memcached](https://memcached.org/), plus une [liaison Python prise en charge](/fr/2.2/topics/cache/#memcached) - [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) ([gettext et Windows](/fr/2.2/topics/i18n/translation/#gettext-on-windows)) - [selenium](https://pypi.org/project/selenium/) - [sqlparse](https://pypi.org/project/sqlparse/) 0.2.2+ (required) - [tblib](https://pypi.org/project/tblib/) 1.5.0+ Vous pouvez trouver ces dépendances dans des [fichiers de dépendances pip](https://pip.pypa.io/en/latest/user_guide/#requirements-files) dans le répertoire `tests/requirements` du code source de Django et vous pouvez les installer comme ceci ```console $ pip install -r tests/requirements/py3.txt ``` Si vous rencontrez une erreur durant l’installation, il est possible qu’une dépendance pour un ou plusieurs paquets Python manque sur votre système. Consultez la documentation du paquet problématique ou recherchez sur le Web avec le message d’erreur obtenu. Vous pouvez également installer les adaptateurs de base de données de votre choix en utilisant oracle.txt\`, `mysql.txt` ou `postgres.txt`. Si vous souhaitez tester le moteur de cache `memcached`, vous devrez aussi définir un réglage [`CACHES`](/fr/2.2/ref/settings/#std-setting-CACHES) pointant sur votre instance de memcached. Pour lancer les tests GeoDjango, il vous faudra [configurer une base de données spatiale et installer les bibliothèques géospatiales](/fr/2.2/ref/contrib/gis/install/). Ces dépendances sont facultatives. Si l’une d’entre elle est absente, les tests correspondants seront sautés. Pour exécuter certains tests `autoreload`, il vous faudra installer le service [Watchman](https://facebook.github.io/watchman/). ### La couverture de code Contributors are encouraged to run coverage on the test suite to identify areas that need additional tests. The coverage tool installation and use is described in [testing code coverage](/fr/2.2/topics/testing/advanced/#topics-testing-code-coverage). Coverage should be run in a single process to obtain accurate statistics. To run coverage on the Django test suite using the standard test settings: ```console $ coverage run ./runtests.py --settings=test_sqlite --parallel=1 ``` After running coverage, generate the html report by running: ```console $ coverage html ``` When running coverage for the Django tests, the included `.coveragerc` settings file defines `coverage_html` as the output directory for the report and also excludes several directories not relevant to the results (test code or external code included in Django). ## Applications contrib Les tests des applications contribuées se trouvent dans le répertoire `tests/`, typiquement sous `_tests`. Par exemple, les tests de `contrib.auth` se trouvent dans `tests/auth_tests`. ## Dépannage ### Test suite hangs or shows failures on `master` branch Ensure you have the latest point release of a [supported Python version](/fr/2.2/faq/install/#faq-python-version-support), since there are often bugs in earlier versions that may cause the test suite to fail or hang. On **macOS** (High Sierra and newer versions), you might see this message logged, after which the tests hang: ```console objc[42074]: +[__NSPlaceholderDate initialize] may have been in progress in another thread when fork() was called. ``` To avoid this set a `OBJC_DISABLE_INITIALIZE_FORK_SAFETY` environment variable, for example: ```console $ OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ./runtests.py ``` Or add `export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` to your shell’s startup file (e.g. `~/.profile`). ### Nombreux échecs de tests avec `UnicodeEncodeError` Si le paquet `locales` n’est pas installé, certains tests échoueront avec une exception `UnicodeEncodeError`. Il est possible de corriger cela par exemple sur les systèmes basés sur Debian en lançant ```console $ apt-get install locales $ dpkg-reconfigure locales ``` Il est possible de corriger cela sur les systèmes macOS en configurant la locale du shell ```console $ export LANG="en_US.UTF-8" $ export LC_ALL="en_US.UTF-8" ``` Lancez la commande `locale` pour confirmer la modification. Une autre possibilité est d’ajouter ces commandes d’exportation au fichier de démarrage du shell (par ex. `~/.bashrc` pour Bash) afin d’éviter de devoir les retaper. ### Tests that only fail in combination Dans le cas où un test passe lorsqu’il est lancé seul mais échoue lorsque la suite de tests entière est lancée, nous disposons de certains outils pour aider à analyser le problème. The `--bisect` option of `runtests.py` will run the failing test while halving the test set it is run together with on each iteration, often making it possible to identify a small number of tests that may be related to the failure. For example, suppose that the failing test that works on its own is `ModelTest.test_eq`, then using: ```console $ ./runtests.py --bisect basic.tests.ModelTest.test_eq ``` will try to determine a test that interferes with the given one. First, the test is run with the first half of the test suite. If a failure occurs, the first half of the test suite is split in two groups and each group is then run with the specified test. If there is no failure with the first half of the test suite, the second half of the test suite is run with the specified test and split appropriately as described earlier. The process repeats until the set of failing tests is minimized. The `--pair` option runs the given test alongside every other test from the suite, letting you check if another test has side-effects that cause the failure. So: ```console $ ./runtests.py --pair basic.tests.ModelTest.test_eq ``` will pair `test_eq` with every test label. With both `--bisect` and `--pair`, if you already suspect which cases might be responsible for the failure, you may limit tests to be cross-analyzed by [specifying further test labels](#runtests-specifying-labels) after the first one: ```console $ ./runtests.py --pair basic.tests.ModelTest.test_eq queries transactions ``` You can also try running any set of tests in reverse using the `--reverse` option in order to verify that executing tests in a different order does not cause any trouble: ```console $ ./runtests.py basic --reverse ``` ### Affichage des requêtes SQL durant un test Si vous souhaitez examiner les instructions SQL exécutées dans des tests en échec, vous pouvez activer la [journalisation SQL](/fr/2.2/topics/logging/#django-db-logger) en précisant l’option `--debug-sql`. Si vous combinez cela avec `--verbosity=2`, toutes les requêtes SQL seront affichées ```console $ ./runtests.py basic --debug-sql ``` ### Affichage de la trace d’erreur complète d’un échec de test Par défaut, les tests sont exécutés en parallèle avec un processus par cœur. Cependant, lorsque les tests sont exécutés en parallèle, vous ne verrez qu’une trace d’erreur tronquée pour chaque échec de test. Vous pouvez ajuster ce comportement avec l’option `--parallel`: ```console $ ./runtests.py basic --parallel=1 ``` Vous pouvez également utiliser la variable d’environnement `DJANGO_TEST_PROCESSES` à cet effet. ## Astuces d’écriture de tests ### Isolation de l’inscription des modèles Pour éviter de polluer le registre global [`apps`](/fr/2.2/ref/applications/#django.apps.apps) et empêcher des créations de table non désirées, les modèles définis dans une méthode de test devraient être liés à une instance `Apps` temporaire ```python from django.apps.registry import Apps from django.db import models from django.test import SimpleTestCase class TestModelDefinition(SimpleTestCase): def test_model_definition(self): test_apps = Apps(['app_label']) class TestModel(models.Model): class Meta: apps = test_apps ... ``` #### `django.test.utils.isolate_apps(*app_labels, attr_name=None, kwarg_name=None)` Comme ce procédé implique plusieurs lignes de code, Django fournit un décorateur [`isolate_apps()`](#django.test.utils.isolate_apps). Il est utilisé comme suit ```python from django.db import models from django.test import SimpleTestCase from django.test.utils import isolate_apps class TestModelDefinition(SimpleTestCase): @isolate_apps('app_label') def test_model_definition(self): class TestModel(models.Model): pass ... ``` > **Définition de app_label`** > > Les modèles définis dans une méthode de test sans [`app_label`](/fr/2.2/ref/models/options/#django.db.models.Options.app_label) explicite reçoivent automatiquement l’étiquette de l’application dans laquelle leur classe de test est située. > > Dans l’optique de s’assurer que les modèles définis dans le contexte d’instances [`isolate_apps()`](#django.test.utils.isolate_apps) sont correctement installées, vous devriez transmettre l’ensemble des `app_label` ciblées en tant que paramètres : > > *tests/app\_label/tests.py* > > ```python > from django.db import models > from django.test import SimpleTestCase > from django.test.utils import isolate_apps > > class TestModelDefinition(SimpleTestCase): > @isolate_apps('app_label', 'other_app_label') > def test_model_definition(self): > # This model automatically receives app_label='app_label' > class TestModel(models.Model): > pass > > class OtherAppModel(models.Model): > class Meta: > app_label = 'other_app_label' > ... > ``` Le décorateur peut aussi être appliqué à des classes : ```python from django.db import models from django.test import SimpleTestCase from django.test.utils import isolate_apps @isolate_apps('app_label') class TestModelDefinition(SimpleTestCase): def test_model_definition(self): class TestModel(models.Model): pass ... ``` L’instance temporaire `Apps` utilisée pour isoler l’inscription du modèle peut être récupérée comme un attribut lorsqu’utilisée en tant que décorateur de classe au moyen du paramètre `attr_name`: ```python from django.db import models from django.test import SimpleTestCase from django.test.utils import isolate_apps @isolate_apps('app_label', attr_name='apps') class TestModelDefinition(SimpleTestCase): def test_model_definition(self): class TestModel(models.Model): pass self.assertIs(self.apps.get_model('app_label', 'TestModel'), TestModel) ``` Ou en tant que paramètre de la méthode de test lorsqu’utilisée comme décoratrice de méthode au moyen du paramètre `kwarg_name`: ```python from django.db import models from django.test import SimpleTestCase from django.test.utils import isolate_apps class TestModelDefinition(SimpleTestCase): @isolate_apps('app_label', kwarg_name='apps') def test_model_definition(self, apps): class TestModel(models.Model): pass self.assertIs(apps.get_model('app_label', 'TestModel'), TestModel) ```