Les tests unitaires dans le dépôt Bitcoin Core

Ce que couvre ce README

Le fichier src/test/README.md est la documentation de la suite de tests unitaires du dépôt Bitcoin Core. Il explique où se trouve le code de test, comment construire l'exécutable de test, comment l'exécuter et comment ajouter de nouveaux tests. Les métadonnées du dépôt décrivent le projet comme un arbre d'intégration et de staging Bitcoin Core, écrit en C++. Ce README ne couvre pas le reste du code de Bitcoin Core, donc tout ce qui est hors du flux de travail des tests unitaires est hors du cadre de cet article.

Pour bitcoin/bitcoin, ce point doit être lu avec la section « Ce que couvre ce README ». Le README précise que bitcoin est un projet en C++, publié sous MIT. Les éléments non décrits, comme les valeurs par défaut, les volumes acceptés, les erreurs détaillées ou les besoins matériels précis, restent à établir dans la documentation et le code du dépôt. Une lecture utile consiste à relier la fonctionnalité nommée ici au fichier ou à la commande indiquée par le projet, puis à comparer l'observation obtenue avec le comportement annoncé. Cette vérification concerne bitcoin lui-même et ne doit pas être remplacée par une promesse générale.

Compiler et exécuter test_bitcoin

Le système de construction compile un exécutable nommé test_bitcoin qui exécute tous les tests unitaires. Le fichier source principal de la bibliothèque de test est util/setup_common.cpp. Les tests unitaires sont compilés automatiquement si les dépendances ont été satisfaites lors de la génération du système de construction et si les tests n'ont pas été explicitement désactivés. Pour exécuter tous les tests unitaires, utilisez ctest --test-dir build, qui inclut également les tests des sous-arbres. Lancez build/bin/test_bitcoin --list_content pour obtenir la liste complète des tests. Après avoir modifié un fichier de test, exécutez cmake --build build puis relancez le test. Si vous avez modifié un fichier non lié aux tests, utilisez cmake --build build --target test_bitcoin pour recompiler uniquement ce qui est nécessaire aux tests unitaires. Les exemples supposent que le répertoire de construction s'appelle build.

Exécuter des tests individuels

L'exécutable test_bitcoin accepte les arguments de ligne de commande du framework Boost. Pour voir les arguments disponibles, lancez build/bin/test_bitcoin --help. Par exemple, pour exécuter uniquement les tests du fichier getarg_tests avec une journalisation complète, utilisez --log_level=all --run_test=getarg_tests, ou la forme courte -l all -t getarg_tests. Un test unique peut être ciblé, comme getarg_tests/doubledash. L'exécutable accepte aussi certains arguments de bitcoind après un séparateur --. Par exemple, -- -printtoconsole=1 envoie la journalisation de débogage, qui va normalement uniquement dans debug.log dans le répertoire de données, également sur la sortie du terminal. L'argument --log_level ou -l contrôle la verbosité de la sortie des tests.

Pour bitcoin/bitcoin, ce point doit être lu avec la section « Exécuter des tests individuels ». Le README précise que bitcoin est un projet en C++, publié sous MIT. Les éléments non décrits, comme les valeurs par défaut, les volumes acceptés, les erreurs détaillées ou les besoins matériels précis, restent à établir dans la documentation et le code du dépôt. Une lecture utile consiste à relier la fonctionnalité nommée ici au fichier ou à la commande indiquée par le projet, puis à comparer l'observation obtenue avec le comportement annoncé. Cette vérification concerne bitcoin lui-même et ne doit pas être remplacée par une promesse générale.

Le répertoire de données temporaire

Lancer test_bitcoin crée un répertoire de données temporaire avec un chemin généré aléatoirement dans test_common bitcoin/, lui-même sous le répertoire temporaire du système. Ce répertoire ressemble à une forme simplifiée du répertoire de données standard de bitcoind et contient toujours debug.log. Vous pouvez spécifier son emplacement avec -testdatadir. Le répertoire utilisé est le chemin de l'argument suivi de /test_common bitcoin/<test-name>/datadir, et il est créé si nécessaire. Spécifier cet argument empêche la suppression du répertoire après le dernier test, ce qui facilite le débogage. Il est supprimé au début du prochain lancement de test, donc aucun état résiduel n'est utilisé. Si vous exécutez une suite complète ou toutes les suites, un répertoire distinct est créé pour chaque test individuel.

Ajouter des cas de test

Pour ajouter des tests unitaires, ajoutez des fonctions BOOST_AUTO_TEST_CASE aux fichiers .cpp existants dans le répertoire test/, ou créez de nouveaux fichiers .cpp qui implémentent des sections BOOST_AUTO_TEST_SUITE. Les nouveaux fichiers de test doivent être listés dans src/test/CMakeLists.txt, ou dans src/wallet/test/CMakeLists.txt pour les tests liés au portefeuille. Le modèle consiste à créer un fichier de test pour chaque classe ou fichier source que vous voulez tester, avec la convention de nommage <source_filename>_tests.cpp, et la suite doit être appelée <source_filename>_tests. Le README cite uint256_tests.cpp comme exemple. Les tests unitaires GUI sont ajoutés dans src/qt/test/ et src/qt/test/test_main.cpp, et ils s'exécutent avec build/bin/test_bitcoin-qt.

Pour bitcoin/bitcoin, ce point doit être lu avec la section « Ajouter des cas de test ». Le README précise que bitcoin est un projet en C++, publié sous MIT. Les éléments non décrits, comme les valeurs par défaut, les volumes acceptés, les erreurs détaillées ou les besoins matériels précis, restent à établir dans la documentation et le code du dépôt. Une lecture utile consiste à relier la fonctionnalité nommée ici au fichier ou à la commande indiquée par le projet, puis à comparer l'observation obtenue avec le comportement annoncé. Cette vérification concerne bitcoin lui-même et ne doit pas être remplacée par une promesse générale.

Journalisation et débogage

ctest --test-dir build écrit dans le fichier de journal build/Testing/Temporary/LastTest.log. Vous pouvez utiliser l'option --output-on-failure pour afficher automatiquement les journaux des tests échoués. Pour écrire dans les journaux depuis les tests unitaires, utilisez les méthodes de message fournies par Boost, la plus simple étant BOOST_TEST_MESSAGE. Pour déboguer, lancez l'exécutable test_bitcoin avec gdb ou lldb, comme n'importe quel autre programme. En cas de défaut de segmentation, exécutez gdb build/bin/test_bitcoin puis utilisez la commande bt dans gdb pour obtenir une trace. Valgrind peut aussi aider. Par défaut, le runner Boost intercepte les erreurs système et ne produit pas de fichier core. Pour en obtenir un, ajoutez --catch_system_errors=no aux arguments de test_bitcoin et réglez les ulimits correctement. Le fichier core résultant peut être examiné avec gdb build/bin/test_bitcoin core.

Licence et vérification

Les métadonnées du dépôt enregistrent un identifiant SPDX MIT et décrivent le projet comme un arbre d'intégration et de staging Bitcoin Core. L'extrait de licence fourni avec les métadonnées indique qu'aucun fichier LICENSE n'a été trouvé au chemin habituel. Par conséquent, le texte réel de la licence n'est pas disponible dans le matériel fourni, et cet article ne peut pas indiquer ce que la licence accorde ou exige. Le README lui-même ne mentionne pas de licence. Pour vérifier la licence, examinez le fichier LICENSE à la racine du dépôt et comparez son texte avec l'identifiant SPDX.

Pour bitcoin/bitcoin, ce point doit être lu avec la section « Licence et vérification ». Le README précise que bitcoin est un projet en C++, publié sous MIT. Les éléments non décrits, comme les valeurs par défaut, les volumes acceptés, les erreurs détaillées ou les besoins matériels précis, restent à établir dans la documentation et le code du dépôt. Une lecture utile consiste à relier la fonctionnalité nommée ici au fichier ou à la commande indiquée par le projet, puis à comparer l'observation obtenue avec le comportement annoncé. Cette vérification concerne bitcoin lui-même et ne doit pas être remplacée par une promesse générale.

Conclusion éditoriale

Le README décrit un flux de travail ciblé : compiler test_bitcoin, filtrer les tests avec les arguments Boost, examiner le répertoire de données temporaire et ajouter des cas de test avec BOOST_AUTO_TEST_CASE. La licence elle-même n'est pas établie car le matériel fourni ne contient aucun texte de licence.

Sources officielles

1. Official documentation
2. Official README
3. Project repository
4. Release notes