I. Introduction
Compiler une bibliothèque est relativement facile, mais vous ne savez pas s’il y a des bugs tant que vous ne la liez pas avec un exécutable et que vous n’avez pas exécuté cet exécutable (link, run).
Bien que la compilation de libwebrtc (et libjingle) soient devenues relativement faciles grâce à depot_tools, tester libwebrtc est un vrai problème. Comme les commits sont appliqués, testés et potentiellement retires dans le système de Google, il n’est pas possible d’être certain que la dernière révision (HEAD) soit stable a un moment donne.
En utilisant branch_heads il est possible de compiler et de tester les versions correspondant à une version publiée de Chrome. Cependant, tester des versions plus récentes de libwebrtc / libjingle, comme celles utilisées dans Canary, est quelque chose que l’on voudrait pouvoir faire afin d’être prêt lorsque ces versions entreront en production, mais c’est très difficile. Ce post va aborder deux points : le système de tests de Google (pour les curieux) et la manière d’atteindre le même niveau de test que Google avec quelques lignes de code CMake.
II. Je veux ma propre cascade de test!
La page officielle décrit comment voir les tests en cours d’exécution, ou comment en ajouter de nouveaux, mais pas comment faire pour les démarrer ou les lancer localement. Ce n’est pas que vous ne pouvez pas le faire, c’est juste que c’est assez compliqué de lancer les tests localement et que cela demande une machinerie assez importante. Ce que l’on voudrait vraiment être capable de faire, ce serait d’avoir, au minimum, la capacité de tester localement les résultats de la compilation avant de l’installer ou d’en faire un package (plus sur cela dans un prochain post). Dans le meilleur des cas, on souhaiterait disposer de l’équivalent d’une cascade qui pourrait être lancée à la demande. Tout d’abord, pour les pressés, il n’y a quasiment aucun moyen de réaliser cela par soi-même car l’infrastructure est la propriété de Google et nécessite que vous ayez un compte committer soit pour WebRTC soit pour Chrome. Je ne sais pas si c’est possible, je peux seulement dire que je ne connais personne dans l’écosystème (à l’exception d’un employé de chez Intel) qui bénéficie de ce privilège. Pour les curieux ou ceux qui ont le temps, lisez la suite pour savoir ce que vous pouvez faire pour obtenir le plus proche équivalent.
1. Les infos manquantes pour tester libwebrtc
Cette partie traitera de toutes les infos manquantes dans la page webrtc.org (mais diffusées sur les différentes pages wiki de Chromium) pour vraiment mettre en place les tests à la façon de Google.
Le système utilisé par Google pour le développement de Chromium est super. Honnêtement, il a beaucoup de sens et beaucoup d’efforts ont été déployés pour faire face au grand nombre de développeurs travaillant sur Cromium. La dernière « infra » (comme ils l’appellent) doit pouvoir traiter plus de 200 commits par jour sans interruption, et il semble qu’elle fasse du bon travail. Ceci étant dit, c’est assez démesuré pour quelqu’un qui voudrait seulement travailler sur libwebrtc et il est malheureux que même de petites équipes soient obligées soit d’utiliser ce mastodonte soit de faire l’impasse sur les tests.
La partie d’origine des tests de l’infra est constituée de plusieurs éléments : Gtest pour écrire les tests unitaires, les outils habituels pour intégrer Gtest au processus de construction (gyp, DEPS…), buildbot pour … eh bien, les bots de compilation et une nouvelle infrastructure d’essaimage spéciale (ici et là) couplée avec des tests isolés (ici et là). Je ne vais pas aborder ici GTest, gyp ou DEPS, mais traiter de ce qui doit être mis en place pour pouvoir effectuer les tests après une compilation réussie de libwebrtc. Plus précisément, je vais traiter uniquement des tests concernant libwebrtc en tant que bibliothèque indépendante et non ceux portant sur webrtc-in-chromium et autres tests intégrés (*ces tests sont en effet assez différents, tout spécialement ceux concernant le rendu, le partage d’écran, etc., aussi nous devons y aller pas à pas). Finalement, je vais compiler uniquement la bibliothèque de webrtc.org et non la version Gecko/Firefox (ici aussi, c’est assez différent, j’aime le partage d’écran sous Firefox et leur intégration de H.264, mais encore une fois nous devons y aller étape par étape).
Le lien ci-dessous vous indique pas à pas tout ce dont vous aurez besoin pour configurer en local vos propres buildbot (avec esclaves), trybot et autres. Notez bien que les liens que je mentionne vers les dépôts pourront être obsolètes quand vous lirez ce post (cible en mouvement RAPIDE…) et vous pourriez vouloir lire le code dans la partie « infra » de depot_tools pour connaître la dernière façon de faire les choses (sic), et plus spécifiquement, le contenu du répertoire /build qui peut être directement extrait de https://chromium.googlesource.com/chromium/tools/build.git . Les dossiers qui configurent les cascades de libwebrtc version autonome se trouvent dans master.client.webrtc . Chaque colonne de la cascade correspond à un buildbot (esclave) dont les informations se trouvent aussi dans le même dossier.
pour en savoir plus
- https://www.chromium.org/developers/testing/chromium-build-infrastructure
2. Test isolé, c’est quoi ca ?
Après la compilation de libwebrtc vous trouverez votre dossier de compilation (/src/out/<CONFIG> par défaut, <CONFIG> étant soit Debug soit Release) assez encombré. Parmi tous ces fichiers, vous allez voir quelques exécutables dont le nom contient « isolated » ou « isolated.state ». Ces fichiers sont utilisés par le système d’essaimage pour distribuer les tests (ici et là). Dans notre cas, l’information importante est qu’ils contiennent la liste des fichiers dont vous avez besoin comme arguments pour lancer les tests. Ce sont toujours des travaux en cours, mais ils sont d’ores et déjà assez stables pour pouvoir être utilisés. Il y a 22 tests semblables qui sont listés. Maintenant, si vous regardez la cascade, vous verrez qu’en gros il y a deux types de buildbots, les normaux qui lancent toutes les tests unitaires et les « Large » qui lancent les tests de performances et les longs tests tels que [vie|voe]_auto_test, video_capture_tests et audio_device_tests. Ceux-ci prennent assez de temps à s’exécuter et sont beaucoup plus longs que les autres tests, ce qui justifie de les lancer séparément sur des instances plus costaudes. Tous les tests doivent êtres lancés avec l’argument suplémentaire –-test-launcher-bot-mode. Pour être exhaustif, j’ajouterais que vie_ et voe_auto_test sont des exécutables interactifs très puissants qui méritent un post rien que pour eux. J’encourage tout le monde à les utiliser et à regarder leur code source. Quelle source d’inspiration ! Pour être lancés comme des tests vous devez leur ajouter l’argument supplémentaire –-automated.
3. Alors, comment faire pour lancer ces tests facilement avec CMake ?
CMake fait partie d’une trilogie (eh oui, encore une), la trilogie CMake/CTest/CDash. CMake est l’outil principal de configuration et de coompilation, CTest est votre principal outil de test et de gestion de gestion de tests, et c’est aussi un client pour CDash, l’équivalent de la cascade, c’est-à-dire un tableau de bord interactif qui interagit avec les résultats envoyés par CTest de vos compilations et des tests. L’avantage c’est que tout est intégré.
NOTE : la meilleure façon de faire serait d’analyser les fichiers isolés et d’en extraire la ligne de commande exacte ainsi que les fichiers de sortie. Dans notre cas, pour simplifier et gagner du temps, nous allons ajouter manuellement les 22 tests un par un et nous ignoreront leur sortie si le test a réussi. On peut améliorer cette méthode, mais elle vous fournira néanmoins 99% de ce que vous souhaitez obtenir en 30 minutes de travail…
Pour activer le module des tests dans CMake vous devez seulement ajouter au script CMake les deux lignes de code suivantes :
- enable_testing()
- include(CTest)
ATTENTION : sans ces deux lignes, le reste du code ne plantera pas ni ne soulèvera aucune erreur, mais aucun test ne sera généré.
Pour chaque test que vous souhaitez ajouter, vous pouvez utiliser la commande add_test() . Ci-dessous, un exemple qui supporte Windows et Mac pour ajouter un test normal, tout en vérifiant que le nom passé en argument correspond à un fichier existant (rappelez vous : cible en mouvement RAPIDE…):
- set( my_test_binary_name « common_audio_unittests »)
- set( my_test_binary ${my_test_binary_name) )
- if( WIN32 )
- set( my_test_binary ${my_test_binary} exe )
- endif()
- if( EXISTS ${MY_BUILD_DIR}/${my_test_binary )
- add_test(
- NAME imp_${my_test_binary_name}
- COMMAND ${my_test_binary} –test-launcher-bot-mode
- WORKING_DIRECTORY ${MY_BUILD_DIR}
- )
- else()
- message( WARNING « ${my_test_binary} – NOT FOUND. »)
- endif()
Vous pouvez recommencer pour d’autres exemples. Le code final peut être consulté ici (et la macro add_webrtc_test est définie ici).
Quand la compilation du projet est terminée, vous pouvez vérifier quels tests ont été ajoutés en lançant cette commande dans le répertoire de compilation : « ctest -N« . Cela donnera la liste des tests sans les lancer. Les commandes « ctest » ou « make test » (sous Mac/Linux) sont équivalentes et lancent tous les tests l’un après l’autre. Pour libwebrtc, il est préférable de ne pas utiliser l’option -jX pour lancer les tests en parallèle car ils accèdent au matériel et peuvent interférer les uns avec les autres. Pour être sûr que personne ne commette cette erreur, vous pouvez ajouter une dépendance entre chaque test et son prédécesseur dans la liste. Nous n’avons pas mis ça en place (même si ça ne représente qu’une seule ligne). Si vous souhaitez voir la sortie des tests sur votre écran, vous pouvez ajouter -V à la ligne de commande. Et voilà, vous pouvez tester la bibliothèque de façon aussi complète que les tests de Google le feraient (enfin presque, il manque la détection des fuites mémoire et autres conflits de threads, mais c’est déjà bien d’avoir les tests. L’ajout des contrôles de fuites mémoire et des calculs de couverture seront expliqués dans un prochain post). Maintenant nous pouvons faire la fête comme si on était en 1999, ou pas ?
NOTE : webrtc_perf_test a besoin d’un accès réseau, de même pour voe_auto_test, ainsi si vous testez sous Windows, il vous faudra soit configurer votre pare-feu pour l’autoriser, manuellement, en cliquant N fois sur autoriser quand vous y êtes invités, soit passer ce test si vous voulez lancer la suite de tests.
4. Ok, je peux lancer tous les tests localement mais je n’ai toujours pas ma cascade !
À ce stade vous en avez assez pour construire et tester la sortie sur une seule machine. C’est une bonne base pour préparer un package de la bibliothèque, un sujet que nous aborderons dans un prochain post. Toutefois vous n’avez aucune visibilité sur le résultat de la compilation de la même base de code sur différents systèmes et compilateurs, avec différentes options de compilateurs, et vous n’avez pas non plus de beau visuel en ligne sur votre tableau de bord.
C’est ici que CDash devient très utile. CDash est le composant serveur de la cascade et CTest peut être très facilement configuré pour envoyer les résultats de la compilation et des tests à un serveur CDash. KitWare, l’une des principales compagnies derrière cmake/ctest/cdash et le lieu de travail des ingénieurs les plus impressionnant avec qui j’ai pu travailler dans ma vie, propose un hébergement gratuit pour les projets open source et des options d’hébergements à un prix très raisonnable. Bien sûr, le code est gratuit et open source et vous pouvez installer votre propre serveur CDash en interne si vous préférez. J’ai choisi d’avoir mon propre petit compte et voici le contenu très simple du fichier CTestConfig.cmake que vous devez ABSOLUMENT garder dans la racine du code source.
- set(CTEST_PROJECT_NAME « libwebRTC ») # c’est relié a un projet que vous devez avoir préalablement créé sur le serveur.
- set(CTEST_NIGHTLY_START_TIME « 00:00:00 EST ») # L’heure que vous voulez, en général une heure où l’ordinateur n’est pas utilisé.
- set(CTEST_DROP_METHOD « http »)
- set(CTEST_DROP_SITE « my.cdash.org ») # Cela peut changer en fonction de l’installation de votre serveur.
- set(CTEST_DROP_LOCATION « /submit.php?project=libwebRTC »)
- set(CTEST_DROP_SITE_CDASH TRUE)
Depuis un répertoire vide (recommandé) vous pouvez lancer ctest -D Experimental pour configurer, compiler, lancer les tests (optionnellement vérifier les fuites mémoire, calculer la couverture…) et envoyer les résultats au tableau de bord. Pour cet exemple, voici à quoi ressemble le tableau de bord (Mac). Vous pouvez aussi voir apparaître las compilations Windows et Linux. Puisque CMake est multi-plateformes il fonctionne effectivement tel quel (sauf pour des détails de ligne de commande et des différences d’extensions) sur toutes les plateformes. Ici chaque ligne est esclave, par opposition à la cascade où c’est une colonne qui est esclave, et vous pouvez cliquer sur le résultat de chaque étape (configuration, compilation, test) pour récupérer les résultats tels qu’ils auraient étés affichés sur l’écran, vous donnant approximativement les mêmes fonctionnalités que le buildbot de la cascade. Éventuellement pour un projet plus mûr cela ressemblerait à ça.
CTest a également la capacité de télécharger des fichiers séparément. Dans un prochain post, j’expliquerais comment l’utiliser pour envoyer automatiquement vers un dépôt public une version compilée de la bibliothèque ou une version package de ces bibliothèques si et seulement si tous les tests ont réussi. Ainsi les développeurs peuvent faire confiance en toute bibliothèque ou paquet mis à disposition, sans avoir à les recompiler et les retester (choisissez vous même votre danse de la victoire).
Lectures suggérées
- https://www.cmake.org/Wiki/CMake/Testing_With_CTest
- https://www.cmake.org/Wiki/CMake_Scripting_Of_CTest (niveau avancé : comment mettre en place des instances de construction automatiques.)
III. Conclusion
Le système de Google est certainement plus évolutif que celui présenté ici. Il permet ainsi de déclencher automatiquement des compilations afin de valider des commits, ce qui est top. Alors que CMake/CTest/CDash a été amélioré au cours des 5 dernières années pour faire cela, c’est toujours une fonctionnalité difficile à déployer (POUR AUTANT QUE JE SACHE, je ne suis pas forcément à jour avec les dernières évolutions de CMake). Dans le cas d’un très gros projet (plus de 200 commits par jour …) avec seulement un petit nombre de compagnies impliquées, c’est top.
Ce qui est génial avec le système C^3, c’est que n’importe qui peut bénévolement mettre en place un hôte de compilation et contribuer au journal de bord. Vous avez une configuration inhabituelle (version initiale non publique d’un compilateur, vieille version d’un compilateur [BorlandCC 5.6]…) que personne ne peut tester, vous pouvez néanmoins toujours compiler et rapporter les erreurs pour que les développeurs les voient. Rapporter des erreurs est aussi simple que « ctest -D Experimental ». Si vous configurez votre ordinateur pour être un hôte de compilation nocturne, les développeurs peuvent modifier le code et vérifier si le résultat résout le problème sans avoir accès à votre machine (oui, vous pouvez diriger le bot vers une branche git, afin de ne pas polluer la branche de développement principale ou la branche master pendant le processus d’essais et d’erreurs). Donc, pour les projets plus simples, avec beaucoup de petites équipes qui contribuent (comme une communauté open source autour d’une bibliothèque…), c’est top. La barrière d’entrée est basse, tout en proposant un système assez puissant. Ce mécanisme est disponible depuis des années, et il a été utilisé dans de multiples projets, il est donc facile de trouver des gens qui ont la connaissance des outils (qui utilise depot-tools en dehors des membres du projet chromium ?). Il dispose également une grande base de code dont les gens peuvent s’inspirer. Et il prend en charge ninja…
Ici, en quelques heures, nous avons été capable d’apprendre à tester libwebrtc localement à un niveau équivalent à celui de Google, et à faire un rapport à un tableau de bord hébergé pouvant être partagé. Dans les posts suivants, nous verrons comment ajouter une analyse des fuites mémoire, un calcul de couverture de code (compiler c’est un bon départ, tester c’est mieux, mais quel pourcentage du code testons-nous exactement ?), comment créer des paquets qui permettront d’installer libwebrtc sur des ordinateurs, et comment importer automatiquement une version installée dans des projets utilisant CMake pour configurer leur compilation.