# Documentation Django 6.0.7

# 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 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.

Ensuite, créez et activez un environnement virtuel. Si vous n’êtes pas familier avec cette procédure, lisez le tutoriel de contribution.

Puis, créez un clone local de votre fork, installez quelques dépendances et lancez la suite de tests :

/ 

    $ git clone https://github.com/YourGitHubName/django.git django-repo
    $ cd django-repo/tests
    $ python -m pip install -e ..
    $ python -m pip install -r requirements/py3.txt
    $ ./runtests.py

    ...\> git clone https://github.com/YourGitHubName/django.git django-repo
    ...\> cd django-repo\tests
    ...\> py -m pip install -e ..
    ...\> py -m 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.

If you have trouble installing an optional test dependency, you can skip that dependency locally. For example, if installing `pylibmc` fails, comment out its line in `requirements/py3.txt` and continue with `./runtests.py`. Tests that require `pylibmc` will be skipped automatically. See Lancement de tous les tests for details on installing the optional test dependencies.

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 pour apprendre comment utiliser un module de réglages différent pour lancer les tests avec une autre base de données.

Des problèmes ? Voir Dépannage pour certaines problématiques courantes.

### Lancement des tests avec `tox`

Tox 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, la correction orthographique de la documentation et la mise en forme du code), installez et lancez la commande `tox` depuis n’importe quel endroit de l’arborescence source de Django :

/ 

    $ python -m pip install tox
    $ tox

    ...\> py -m pip install tox
    ...\> tox

Par défaut, `tox` lance la suite de tests avec le fichier de réglages inclus pour SQLite, `black`, `blacken-docs`, `flake8`, `isort`, `lint-docs`, `zizmor` 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 :

/ 

    $ tox -l
    py3
    black
    blacken-docs
    flake8>=3.7.0
    docs
    isort>=7.0.0
    lint-docs
    zizmor>=1.19.0

    ...\> tox -l
    py3
    black
    blacken-docs
    flake8>=3.7.0
    docs
    isort>=7.0.0
    lint-docs
    zizmor>=1.19.0

#### 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. Par exemple, pour lancer les tests avec Python 3.12 en utilisant PostgreSQL :

/ 

    $ tox -e py312-postgres -- --settings=my_postgres_settings

    ...\> tox -e py312-postgres -- --settings=my_postgres_settings

Cette commande configure un environnement virtuel Python 3.12, 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 :

    $ DJANGO_SETTINGS_MODULE=my_postgres_settings tox -e py312-postgres

Les utilisateurs de Windows devraient écrire :

    ...\> set DJANGO_SETTINGS_MODULE=my_postgres_settings
    ...\> tox -e py312-postgres

#### Lancement des tests JavaScript

Django contient un ensemble de tests unitaires JavaScript 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`:

/ 

    $ tox -e javascript

    ...\> 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`.

### Lancement des tests avec `django-docker-box`

django-docker-box permet de lancer la suite de tests de Django en combinant toutes les bases de données prises en charge et les versions de Python. Consultez la page du projet django-docker-box pour des instructions d’installation et d’utilisation.

### 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. Certains tests sont omis ou leur échec est attendu avec certains moteurs de base de données (voir `DatabaseFeatures.django_test_skips` et `DatabaseFeatures.django_test_expected_failures` pour chaque moteur).

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` 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` 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` doit indiquer le mot de passe à utiliser pour l’utilisateur `USER`.

Les noms des bases de données de test sont composés par le préfixe `test_` devant les réglages `NAME` des bases de données définies dans `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` 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 :

/ 

    $ ./runtests.py --settings=path.to.settings generic_relations i18n

    ...\> 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 lancer uniquement 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 :

/ 

    $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests

    ...\> 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 :

/ 

    $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects

    ...\> runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects

Vous pouvez lancer les tests en commençant par un module de premier niveau avec l’option `--start-at`. Par exemple :

/ 

    $ ./runtests.py --start-at=wsgi

    ...\> runtests.py --start-at=wsgi

Vous pouvez aussi lancer les tests en commençant après un module de premier niveau avec l’option `--start-after`. Par exemple :

/ 

    $ ./runtests.py --start-after=wsgi

    ...\> runtests.py --start-after=wsgi

Notez que l’option `--reverse` n’a pas d’influence sur les options `--start-at` et `--start-after`. De plus, ces options ne peuvent pas être utilisées quand vous indiquez des noms de tests.

### Lancement des tests Selenium

Certains tests requièrent Selenium et un navigateur Web. Pour lancer ces tests, vous devez installer le paquet selenium et lancer les tests avec l’option `--selenium=<NAVIGATEURS>`. Par exemple, si Firefox et Google Chrome sont installés :

/ 

    $ ./runtests.py --selenium=firefox,chrome

    ...\> runtests.py --selenium=firefox,chrome

Consultez le paquet 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.

Certains navigateurs (par ex. Chrome ou Firefox) prennent en charge les tests sans interface, ce qui peut être plus rapide et plus stable. Ajoutez l’option `--headless` pour activer ce mode.

#### Tests des captures d’écran

Pour tester des modifications à l’interface d’administration, les tests selenium peuvent être lancés avec l’option `--screenshots`. Les captures d’écran seront enregistrées dans le répertoire `tests/screenshots/`.

Pour définir quand des captures d’écran devraient être prises pendant un test selenium, la classe de test doit utiliser le décorateur `@django.test.selenium.screenshot_cases` avec une liste de types de captures prises en charge (`"desktop_size"`, `"mobile_size"`, `"small_screen_size"`, `"rtl"`, `"dark"` et `"high_contrast"`). Le test peut alors appeler self.take_screenshot(« nom-de-capture-unique »)` au moment opportun pour produire les captures. Par exemple :

    from django.test.selenium import SeleniumTestCase, screenshot_cases
    from django.urls import reverse

    class SeleniumTests(SeleniumTestCase):
        @screenshot_cases(["desktop_size", "mobile_size", "rtl", "dark", "high_contrast"])
        def test_login_button_centered(self):
            self.selenium.get(self.live_server_url + reverse("admin:login"))
            self.take_screenshot("login")
            ...

Cela va générer plusieurs captures d’écran de la page de connexion : une pour un écran d’ordinateur, une pour une taille d’appareil mobile, une pour des langues droite-à-gauche sur un ordinateur, une pour le mode sombre sur un ordinateur et une pour le mode contraste élevé en utilisant Chrome.

### Lancement de tous les tests

Si vous souhaitez lancer la suite de tests complète, vous devrez installer un certain nombre de dépendances :

- aiosmtpd 1.4.5+

- argon2-cffi 23.1.0+

- asgiref 3.9.1+ (required)

- bcrypt 4.1.1+

- colorama 0.4.6+

- docutils 0.22+

- geoip2 4.8.0+

- Jinja2 2.11+

- numpy 1.26.0+

- Pillow 10.1.0+

- PyYAML 6.0.2+

- pywatchman

- redis 5.1.0+

- pymemcache, plus une liaison Python prise en charge

- gettext (gettext et Windows)

- selenium 4.23.0+

- sqlparse 0.5.0+ (required)

- tblib 3.0.0+

Vous pouvez trouver ces dépendances dans des fichiers de dépendances pip dans le répertoire `tests/requirements` du code source de Django et vous pouvez les installer comme ceci :

/ 

    $ python -m pip install -r tests/requirements/py3.txt

    ...\> py -m 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 les moteurs de cache `memcached` ou `Redis`, vous devrez aussi définir un réglage `CACHES` pointant sur votre instance memcached ou Redis.

Pour lancer les tests GeoDjango, il vous faudra configurer une base de données spatiale et installer les bibliothèques géospatiales.

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.

### La couverture de code

Les contributeurs sont encouragés à exécuter la couverture de code sur la suite de tests pour identifier les zones qui ont besoin de tests supplémentaires. L’installation et l’utilisation de l’outil de couverture sont décrites dans test de couverture du code.

Pour mesurer la couverture des tests de la suite de tests de Django en utilisant les réglages de test standards :

/ 

    $ coverage run ./runtests.py --settings=test_sqlite

    ...\> coverage run runtests.py --settings=test_sqlite

Après avoir lancé la couverture des tests, combinez toutes les statistiques de couverture en exécutant :

/ 

    $ coverage combine

    ...\> coverage combine

Puis, produisez le rapport HTML en exécutant :

/ 

    $ coverage html

    ...\> coverage html

Lors de l’exécution de la couverture des tests Django, le fichier de réglages inclus `coveragerc` définit coverage_html` comme répertoire de sortie pour le rapport et exclut également plusieurs répertoires non pertinents pour les résultats (code de test ou code externe inclus dans Django).

### Couverture de code dans les requêtes de contribution

Django’s continuous integration (CI) system automatically runs code coverage analysis on pull requests and posts a comment with a diff coverage report. This helps reviewers see which lines in the changed code are covered by tests.

What the coverage report shows:

The coverage report posted on pull requests uses diff-cover to analyze only the lines that were changed or added in the PR. It shows:

- Lines that are covered by tests (✓)

- Lines that are not covered by tests (✗)

- Lines that cannot be covered (e.g., comments, blank lines)

Important limitations:

When reviewing coverage reports on pull requests, keep these limitations in mind:

- Database-specific code: The CI coverage job runs tests using PostgreSQL on Ubuntu. Code paths specific to other databases (SQLite, MySQL, Oracle) will appear as « not covered » even if database-specific tests exist. This is expected and acceptable.

- Platform-specific code: Similarly, code that only runs on certain operating systems (Windows, macOS) will appear as not covered when run on Ubuntu.

- Coverage doesn’t equal quality: A line being « covered » only means it was executed during tests. It doesn’t guarantee the line is well-tested or that all edge cases are handled. During review, assess test quality beyond just coverage numbers.

Missing coverage should be considered a warning rather than a blocker and should be evaluated in context.

## Applications contrib

Les tests des applications contribuées se trouvent dans le répertoire tests/, typiquement sous `<nom_app>_tests`. Par exemple, les tests de `contrib.auth` se trouvent dans tests/auth_tests.

## Dépannage

### La suite de tests plante ou affiche des échecs sur la branche `main`

Vérifiez que la version de Python installée et prise en charge soit à jour avec sa dernière publication (dernier chiffre de version), dans la mesure où il y a souvent des bogues dans des versions précédentes qui peuvent causer l’échec ou le plantage de la suite de tests.

Sur macOS (High Sierra et plus récent), vous pourriez voir ce message journalisé, après lequel les tests sont bloqués :

    objc[42074]: +[__NSPlaceholderDate initialize] may have been in progress in
    another thread when fork() was called.

Pour éviter cela, définissez une variable d’environnement `OBJC_DISABLE_INITIALIZE_FORK_SAFETY`, par exemple :

    $ OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ./runtests.py

Ou ajoutez `export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` au fichier de démarrage de votre shell (par ex. `~/.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 :

    $ apt-get install locales
    $ dpkg-reconfigure locales

Il est possible de corriger cela sur les systèmes macOS en configurant la locale du shell :

    $ 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 qui n’échouent que lorsqu’ils sont combinés

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.

L’option `--bisect` de `runtests.py` va exécuter le test en échec en divisant par deux le groupe de tests avec lesquels il est exécuté lors de chaque itération, ce qui rend souvent possible l’identification d’un petit nombre de tests qui pourraient être liés à cet échec.

Par exemple, supposons que le test en échec qui fonctionne lorsqu’il est lancé seul est `ModelTest.test_eq`. Alors, avec :

/ 

    $ ./runtests.py --bisect basic.tests.ModelTest.test_eq

    ...\> runtests.py --bisect basic.tests.ModelTest.test_eq

on va essayer de déterminer un test qui interfère avec notre test cible. Pour commencer, le test est exécuté avec la première moitié de la suite de tests. Si un échec survient, cette première moitié est partagée en deux groupes et chaque groupe est ensuite exécuté avec le test cible. Si aucun échec ne survient avec la première moitié de la suite de tests, c’est la seconde moitié qui est exécutée avec le test cible et de nouveau partagée selon le procédé ci-dessus. Ceci se répète jusqu’à ce que le groupe de tests avec échec soit le plus petit possible.

L’option `--pair` exécute le test donné conjointement avec chaque autre test de la suite, ce qui permet de vérifier si un autre test présente des effets de bord pouvant être la cause de l’échec. Donc :

/ 

    $ ./runtests.py --pair basic.tests.ModelTest.test_eq

    ...\> runtests.py --pair basic.tests.ModelTest.test_eq

lancera `test_eq` conjointement avec tous les autres tests individuels.

En combinant –bisect` et `--pair`, si vous suspectez déjà quels cas pourraient être responsables de l’échec, vous pouvez limitez la combinaison des tests en indiquant d’autres étiquettes de test à la suite du premier :

/ 

    $ ./runtests.py --pair basic.tests.ModelTest.test_eq queries transactions

    ...\> runtests.py --pair basic.tests.ModelTest.test_eq queries transactions

Vous pouvez aussi essayer de lancer un ensemble de tests dans un ordre aléatoire ou inversé avec les options `--shuffle` et `--reverse`. Cela peut aider à vérifier que l’exécution des tests dans un autre ordre ne cause pas de problème :

/ 

    $ ./runtests.py basic --shuffle
    $ ./runtests.py basic --reverse

    ...\> runtests.py basic --shuffle
    ...\> 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 en précisant l’option `--debug-sql`. Si vous combinez cela avec `--verbosity=2`, toutes les requêtes SQL seront affichées :

/ 

    $ ./runtests.py basic --debug-sql

    ...\> 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`:

/ 

    $ ./runtests.py basic --parallel=1

    ...\> 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` 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. Pour cela, utilisez le décorateur `isolate_apps()`:

    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` 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()` sont correctement installées, vous devriez transmettre l’ensemble des `app_label` ciblées en tant que paramètres :

`tests/app_label/tests.py`

    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"

            ...