Écrire, exécuter et tester du code¶
Pour corriger un bug ou ajouter une fonctionnalité, vous devrez écrire du nouveau code.
Pour commencer à travailler sur le code, assurez-vous d'avoir configuré un environnement de développement et de travailler sur une branche.
Nous disposons d'un guide de style de codage qui présente nos directives pour l'écriture de code pour BeeWare.
Développement piloté par les tests¶
Un bon moyen de s'assurer que votre code fonctionnera comme prévu consiste à rédiger d'abord un scénario de test pour le vérifier. Ce scénario de test devrait initialement échouer, car le code qu'il est censé tester n'existe pas encore. Vous pouvez ensuite apporter les modifications nécessaires au code pour que le test réussisse, et ainsi avoir la certitude que ce que vous avez écrit résout bien le problème que vous souhaitiez résoudre.
Exécutez votre code¶
Une fois votre code écrit, vous devez vous assurer qu'il fonctionne. Vous devrez l'exécuter manuellement pour vérifier qu'il se comporte comme prévu. Si ce n'est pas déjà fait, il est conseillé de rédiger un scénario de test pour vos modifications ; comme indiqué plus haut, ce test devrait échouer si votre code est commenté ou s'il n'est pas présent.
Vous allez ajouter votre scénario de test à la suite de tests afin qu'il puisse être exécuté en même temps que les autres tests. L'étape suivante consiste à exécuter la suite de tests.
Exécution des tests et de la couverture¶
BeeWare utilise tox pour gérer le
processus de test et pytest pour sa
propre suite de tests.
La commande par défaut tox comprend l'exécution de :
- hooks de pré-commit
- Vérification des notes de mise à jour
-
vérification syntaxique de la documentation
-
suite de tests pour les versions disponibles de Python
-
rapports sur la couverture de code
C'est en substance ce que CI exécute lorsque vous soumettez une pull request.
Pour exécuter l'ensemble complet des tests, tapez :
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
L'exécution de la suite de tests complète peut prendre un certain temps. Vous
pouvez l'accélérer considérablement en exécutant tox en parallèle, en lançant
tox p (ou tox run-parallel). Lorsque vous exécutez la suite de tests en
parallèle, vous recevrez moins d'informations sur l'avancement de l'exécution,
mais vous obtiendrez tout de même un résumé des problèmes détectés à la fin de
la session de tests. Vous devriez voir s'afficher un message indiquant que les
tests ont été exécutés. Vous verrez peut-être des tests SKIPPED, mais vous ne
devriez jamais obtenir de résultats de test FAIL ou ERROR. Nous exécutons
notre suite de tests complète avant de fusionner chaque correctif. Si ce
processus détecte des problèmes, nous ne fusionnons pas le correctif. Si vous
constatez une erreur ou un échec de test, soit il y a quelque chose d'anormal
dans votre environnement de test, soit vous avez trouvé un cas limite que nous
n'avons jamais rencontré auparavant — dans tous les cas, faites-le-nous savoir !
Outre la réussite des tests, cela devrait indiquer une couverture de test de 100 %.
Exécution de variantes de test¶
Exécuter des tests pour plusieurs versions de Python¶
Par défaut, de nombreuses commandes tox tenteront d'exécuter la suite de tests
plusieurs fois, une fois pour chaque version de Python prise en charge par BeeWare. Pour cela, chacune de ces versions de Python doit toutefois être
installée sur votre machine et accessible au processus de [détection]tox de
Python de
(https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). En
général, si une version de Python est disponible via PATH, alors tox devrait
pouvoir la détecter et l'utiliser.
Exécuter uniquement la suite de tests¶
Si vous effectuez des itérations rapides sur une nouvelle fonctionnalité, vous n'avez pas besoin d'exécuter l'ensemble complet des tests ; vous pouvez exécuter uniquement les tests unitaires. Pour ce faire, exécutez la commande suivante :
(.venv) $ tox -e py
(.venv) $ tox -e py
(.venv) C:\...>tox -e py
Exécuter un sous-ensemble de tests¶
Par défaut, tox exécute tous les tests de la suite de tests unitaires. Lorsque
vous développez un nouveau test, il peut être utile de n'exécuter que ce
test-là. Pour ce faire, vous pouvez passer n'importe quel spécificateur
pytest
en argument à tox. Ces chemins d'accès aux tests sont relatifs au répertoire
briefcase. Par exemple, pour n'exécuter que les tests contenus dans un seul
fichier, tapez :
(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py
Vous obtiendrez tout de même un rapport de couverture lorsque vous exécuterez une partie de la suite de tests, mais les résultats de couverture ne porteront que sur les lignes de code qui ont été exécutées par les tests spécifiques que vous avez lancés.
Exécuter la suite de tests pour une version spécifique de Python¶
Par défaut, tox -e py s'exécutera en utilisant l'interpréteur associé à
python sur votre machine. Si plusieurs versions de Python sont installées et
que vous souhaitez tester une version spécifique parmi celles-ci, vous pouvez
indiquer la version de Python à utiliser. Par exemple, pour exécuter la suite de
tests avec Python 3.10, tapez :
(.venv) $ tox -e py310
(.venv) $ tox -e py310
(.venv) C:\...>tox -e py310
Il est possible d'exécuter un sous-ensemble de tests en ajoutant
-- et une spécification de test à la ligne de commande.
Exécuter la suite de tests sans couverture (rapidement)¶
Par défaut, tox exécute la suite de tests pytest en mode mono-thread. Vous
pouvez accélérer l'exécution de la suite de tests en la lançant en parallèle. Ce
mode ne génère pas de fichiers de couverture en raison de la complexité liée à
la capture de la couverture au sein des processus lancés. Pour exécuter une
seule version de Python en mode « rapide », tapez :
(.venv) $ tox -e py-fast
(.venv) $ tox -e py-fast
(.venv) C:\...>tox -e py-fast
Il est possible d'exécuter un sous-ensemble de tests en ajoutant
-- et une spécification de test à la ligne de commande ; il est possible
d'utiliser une version spécifique de Python en ajoutant la
version à la cible de test (par exemple, py310-fast
pour exécuter fast sur Python 3.10).
Couverture du code¶
BeeWare assure une couverture de 100 % de son code source. Lorsque vous ajoutez ou modifiez du code dans le projet, vous devez ajouter du code de test afin de garantir la couverture de toutes les modifications apportées.
Cependant, BeeWare cible plusieurs plateformes ainsi que plusieurs
versions de Python ; il n'est donc pas possible de vérifier la couverture
complète sur une seule plateforme et une seule version de Python. Pour pallier
cela, plusieurs règles de couverture conditionnelles sont définies dans la
section tool.coverage.coverage_conditional_plugin.rules de pyproject.toml
(par exemple, no-cover-if-is-windows peut être utilisé pour marquer un bloc de
code qui ne sera pas exécuté lors de l'exécution de la suite de tests sous
Windows). Ces règles servent à identifier les sections de code qui ne sont
couvertes que sur certaines plateformes ou versions de Python.
Il convient de noter que la génération de rapports de couverture peut présenter quelques particularités selon la version de Python utilisée. Par exemple, si les fichiers de couverture sont générés avec une version de Python mais que le rapport est établi avec une autre, celui-ci peut contenir des faux positifs concernant des branches non couvertes. C'est pourquoi il est recommandé de toujours utiliser, pour la génération du rapport, la version de Python la plus ancienne ayant servi à créer les fichiers de couverture.
Comprendre les résultats de la couverture¶
À la fin du test de couverture, un rapport contenant les données de couverture recueillies devrait s'afficher :
Nom Déclarations Manquants Branche Partie Couverture Manquants
---------------------------------------------------
TOTAL 7540 0 1040 0 100,0 %
Cela nous indique que la suite de tests a parcouru toutes les branches possibles du code. Cela ne garantit pas à 100 % l'absence de bogues, mais cela signifie que nous testons chaque ligne de code de la base de code.
Si vous apportez des modifications au code, il est possible que vous créiez une
lacune dans cette couverture. Dans ce cas, le rapport de couverture vous
indiquera quelles lignes ne sont pas exécutées. Par exemple, supposons que nous
ayons apporté une modification à some/interesting_file.py, en ajoutant une
nouvelle logique. Le rapport de couverture pourrait ressembler à ceci :
Nom Stmts Miss Branch BrPart Couverture Manquant
-------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1 % 170, 302-307, 320->335
-------------------------------------------------------------------------------
TOTAL 7540 1 1726 0 99,9 %
Cela signifie que la ligne 170, les lignes 302 à 307 et un saut de branche de la ligne 320 à la ligne 335 ne sont pas exécutés par la suite de tests. Vous devrez ajouter de nouveaux tests (ou modifier un test existant) pour rétablir cette couverture.
Rapport de couverture pour la plateforme hôte et la version de Python¶
Vous pouvez générer un rapport de couverture pour votre plateforme et votre version de Python. Par exemple, pour exécuter la suite de tests et générer un rapport de couverture sur Python 3.10, exécutez la commande suivante :
(.venv) $ tox -m test310
(.venv) $ tox -m test310
(.venv) C:\...>tox -m test310
Rapport de couverture pour la plateforme hôte¶
Si toutes les versions prises en charge de Python sont disponibles pour tox,
la couverture pour la plate-forme hôte peut être générée en exécutant :
(.venv) $ tox p -m test-platform
(.venv) $ tox p -m test-platform
(.venv) C:\...>tox p -m test-platform
Rapports de couverture au format HTML¶
Il est possible de générer un rapport de couverture HTML en ajoutant -html à
n'importe quel nom d'environnement de couverture tox, par exemple :
(.venv) $ tox -e coverage-platform-html
(.venv) $ tox -e coverage-platform-html
(.venv) C:\...>tox -e coverage-platform-html
Il ne s'agit pas seulement d'écrire des tests !¶
Même si nous veillons à tester l'intégralité de notre code, notre travail ne consiste pas uniquement à maintenir ce niveau de test. Une partie de notre travail consiste à vérifier le code au fur et à mesure. On pourrait bien sûr écrire un ensemble complet de tests pour un gilet de sauvetage en béton… mais un gilet de sauvetage en béton resterait tout de même inutile pour l'usage auquel il est destiné !
Au fur et à mesure que vous développez des tests, vous devriez également
vérifier que le module principal est cohérent en interne. Si vous remarquez
des noms de méthodes qui ne sont pas cohérents en interne (par exemple, une
méthode appelée on_select dans un module, mais on_selected dans un autre),
ou si les données ne sont pas traitées de manière cohérente, signalez-le-nous en
créant un ticket. Ou, si vous êtes sûr de savoir ce qu'il faut faire, créez une
pull request qui corrige le problème que vous avez trouvé.
Une fois que tout fonctionne, vous pouvez soumettre une demande d'extraction avec vos modifications.