Produire des métriques de couverture de code avec Cobertura dans Maven est relativement simple. Si vous êtes intéressés par la génération des données de couverture de code, il vous suffit de rajouter le cobertura-maven-plugin à la section build de votre fichier pom.xml:

 <project>
   ...
   <build>
      <plugins>
         <plugin>
            <groupId>org.codehaus.mojo</groupId>
             <artifactId>cobertura-maven-plugin</artifactId>
             <version>2.5.1</version>
             <configuration>
             <formats>
                <format>html</format>
                <format>xml</format>
             </formats>
           </configuration>
         </plugin>
         ...
      </plugins>
   <build>
   ...
</project>

Cela va générer les métriques de couverture de code quand vous lancerez le plugin Cobertura directement :

$ mvn cobertura:cobertura

Les données de couverture de code seront générées dans le répertoire target/site/cobertura, dans un fichier nommé coverage.xml.

Cependant, cette approche va instrumenter vos classes et produire les données de couverture de code pour chaque build, ce qui est inefficace. Une meilleure approche est de placer cette configuration dans un profil spécifique, comme montré ici :

 <project>
   ...
   <profiles>
    <profile>
      <id>metrics</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>cobertura-maven-plugin</artifactId>
            <version>2.5.1</version>
            <configuration>
              <formats>
                <format>html</format>
                <format>xml</format>
              </formats>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
    ...
  </profiles>
</project>

Dans ce cas, vous lancerez le plugin Cobertura en utilisant le profil metrics pour générer les données de couverture de code :

$ mvn cobertura:cobertura -Pmetrics

Une autre approche consiste à inclure les rapports de couverture de code dans vos rapports Maven. Cette approche est beaucoup plus lente et plus consommatrice en mémoire que de générer simplement les données de couverture de code, mais cela peut avoir du sens si vous générez aussi d'autres métriques de qualité de code et leurs rapports en même temps. Si vous voulez le faire avec Maven 2, vous devez aussi inclure le plugin Maven Cobertura plugin dans la section reporting, comme montré ici :

 <project>
   ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>cobertura-maven-plugin</artifactId>
        <version>2.5.1</version>
        <configuration>
          <formats>
            <format>html</format>
            <format>xml</format>
          </formats>
        </configuration>
      </plugin>
    </plugins>
  </reporting>
</project>

A présent, les données de couverture de code seront générées quand vous générerez le site Maven pour ce projet :

$ mvn site

Si votre projet Maven contient des modules (comme il est de pratique courante pour des gros projets Maven), vous devez mettre en place la configuration Cobertura dans le fichier pom.xml parent. Les métriques de couverture de code et le rapport seront générés séparément pour chaque module. Si vous utilisez l'option de configuration aggregate, le plugin Maven Cobertura génèrera aussi un rapport de plus haut niveau combinant les données de couverture de code de tous les modules. Cependant, que vous utilisiez cette option ou non, le plugin Jenkins Cobertura va lire les données de couverture de code de plusieurs fichiers et les combiner dans un seul rapport aggrégé.

Au moment de la rédaction, il y a une limitation avec le plugin Maven Cobertura — la couverture de code sera uniquement enregistrée pour les tests exécutés pendant la phase test, et pas les tests exécutés pendant la phase integration-test. Cela peut être un problème si vous utilisez cette phase pour lancer des tests d'intégration ou des tests web qui nécessitent une application complètement packagée et déployée — dans ce cas, la couverture de code des tests qui sont uniquement exécutés pendant la phase integration-test ne sera pas comptée dans les métriques de couverture de code Cobertura.

Intégrer Cobertura dans votre build Ant est un peu plus compliqué que de le faire avec Maven. Cependant, cela vous permet d'avoir un contrôle plus fin sur les classes qui sont instrumentées, et quand la couverture de code est mesurée.

Cobertura est livré avec une tâche Ant que vous pouvez utiliser pour intégrer Cobertura dans vos builds Ant. You devez télécharger la dernière distribution Cobertura, et la décompresser quelque part sur votre disque dur. Afin que votre build soit plus portable, et donc plus facile à déployer dans Jenkins, c'est une bonne idée de placer la distribution Cobertura que vous utilisez dans votre répertoire projet, et de la sauvegarder dans votre système de gestion de version. Ainsi, c'est le moyen le plus facile pour garantir que le build utilisera la même version de Cobertura quelle que soit la façon dont il est exécuté.

En supposant que vous avez téléchargé la dernière installation de Cobertura et que vous l'avez placée à l'intérieur de votre projet dans un répertoire nommé tools, vous pourriez faire quelque chose comme ceci :

<property name="cobertura.dir" value="/jenkins-guide-complet/hudsonbook-content-fr/tools/cobertura" />

<path id="cobertura.classpath">
    <fileset dir="${cobertura.dir}">
        <include name="cobertura.jar" />
        <include name="lib/**/*.jar" />
    </fileset>
</path>

<taskdef classpathref="cobertura.classpath" resource="tasks.properties" />

Ensuite, vous devez instrumenter les classes de l'application. Vous devez faire attention de placer ces classes instrumentées dans un répertoire différent, de telle manière qu'elles ne seront pas déployées en production par accident :

<target name="instrument" depends="init,compile">
    <delete file="cobertura.ser"/>
    <delete dir="${instrumented.dir}" />
    <cobertura-instrument todir="${instrumented.dir}">
        <fileset dir="${classes.dir}">
            <include name="**/*.class" />
            <exclude name="**/*Test.class" />
        </fileset>
    </cobertura-instrument>
</target>

A ce stade, le répertoire ${instrumented.dir} contient une version instrumentée de nos classes applicatives. Maintenant, tout ce que nous devons faire pour générer des données utiles de couverture de code est d'exécuter nos tests unitaires avec les classes de ce répertoire :

<target name="test-coverage" depends="instrument">
    <junit fork="yes" dir="/jenkins-guide-complet/hudsonbook-content-fr">
        <classpath location="${instrumented.dir}" />
        <classpath location="${classes.dir}" />
        <classpath refid="cobertura.classpath" />

        <formatter type="xml" />
        <test name="${testcase}" todir="${reports.xml.dir}" if="testcase" />
        <batchtest todir="${reports.xml.dir}" unless="testcase">
            <fileset dir="${src.dir}">
                <include name="**/*Test.java" />
            </fileset>
        </batchtest>
    </junit>
</target>

Cela va produire les données brutes de couverture de code dont nous avons besoin pour produire les rapports XML de couverture que Jenkins peut utiliser. Pour produire ces rapports, nous devons lancer une autre tâche, comme montré ici :

<target name="coverage-report" depends="test-coverage">
    <cobertura-report srcdir="${src.dir}" destdir="${coverage.xml.dir}" 
                      format="xml" />
</target>

Enfin, n'oubliez pas de faire le ménage une fois que tout est fini : la cible clean ne doit pas détruire uniquement les classes générées, mais aussi les classes générées instrumentées, les données de couverture de code Cobertura, et les rapports Cobertura :

<target name="clean" 
        description="Remove all files created by the build/test process.">
    <delete dir="${classes.dir}" />
    <delete dir="${instrumented.dir}" />
    <delete dir="${reports.dir}" />
    <delete file="cobertura.log" />
    <delete file="cobertura.ser" />
</target>

Une fois cela fait, vous êtes prêt à intégrer vos rapports de couverture de code dans Jenkins.

Une fois que les données de couverture de code sont générées dans le cadre de votre processus de build, vous pouvez configurer Jenkins pour les afficher. Ceci implique l'installation du plugin Jenkins Cobertura. Nous avons décrit ce processus dans Section 2.8, “Adding Code Coverage and Other Metrics”, mais nous allons le décrire à nouveau pour rafraîchir votre mémoire. Allez sur l'écran Administrer Jenkins, et cliquez sur Gestion des plugins. Cela va vous amener à l'écran du gestionnaire des plugins. Si Cobertura n'a pas été installé, vous trouverez le plugin Cobertura dans l'onglet Disponibles, dans la section Build Reports (voir Figure 6.11, “Installer le plugin Cobertura”). Pour l'installer, cochez simplement la case et appuyez sur Entrée (ou faites défiler jusqu'au bas de l'écran et cliquez sur le bouton “Installer”). Jenkins va télécharger et installer le plugin pour vous. Une fois que le téléchargement est fini, vous devez redémarrer votre serveur Jenkins.

Une fois que vous avez installé le plugin, vous pouvez mettre en place les rapports de couverture de code dans vos tâches de build. Puisque la couverture de code peut être lente et consommatrice en mémoire, vous devrez généralement créer une tâche de build séparée pour cela et les autres métriques de qualité de code, qui sera exécutée après les tests unitaires et d'intégration. Pour de gros projets, vous pouvez même le mettre en place via un build qui s'exécute sur une base quotidienne. En effet, le retour sur les métriques de couverture de code et autres n'est généralement pas aussi critique que le retour sur les résultats de test, et cela va libérer des exécuteurs de build pour des tâches de build qui peuvent bénéficier de retour rapide.

Comme nous le mentionnions précédemment, Jenkins ne fait pas d'analyse de couverture par lui-même — vous devez configurer votre build pour produire le fichier Cobertura coverage.xml (ou fichiers) avant que vous puissiez générer de jolis graphes ou rapports, généralement en utilisant une des techniques dont nous avons discuté précédemment (voir Figure 6.12, “Votre build de couverture de code doit produire les données de couverture de code”).

Une fois que vous avez configuré votre build pour produire des données de couverture de code, vous pouvez configurer Cobertura dans la section “Actions à la suite du build” de votre tâche de build. Si vous cochez la case “Publish Cobertura Coverage Report”, vous devriez voir quelque chose comme Figure 6.13, “Configurer les métriques de couverture de code dans Jenkins”.

Le premier et plus important champ ici est le chemin des données XML Cobertura que nous avons générées. Votre projet peut contenir un seul fichier coverage.xml, ou plusieurs. Si vous avez un projet Maven multi-modules, par exemple, le plugin Maven Cobertura va générer un fichier coverage.xml distinct pour chaque module.

Le chemin accepte des caractères génériques du style Ant, et il est donc facile d'inclure les données de couverture de code à partir de plusieurs fichiers. Pour tout projet Maven, un chemin tel que **/target/site/cobertura/coverage.xml inclura toutes les métriques de couverture de code de tous les modules dans le projet.

Il y a en fait plusieurs types de couverture de code, et il est parfois utile de les distinguer. La plus intuitive est la couverture de lignes, qui compte le nombre de fois qu'une ligne donnée est exécutée pendant les tests automatisés. “Conditional Coverage” (aussi appelé “Branch Coverage”) prend en compte si les expressions booléennes dans les instructions if et semblables sont testées d'une manière qui vérifie tous les résultats possibles d'une expression conditionnelle. Par exemple, étant donné le fragment de code suivant:

if (price > 10000) {
  managerApprovalRequired = true;
}

Pour obtenir une couverture de code complète pour ce code, vous devez l'exécuter deux fois : une fois avec une valeur supérieure à 10,000, une autre avec une valeur inférieure ou égale à 10,000.

D'autres métriques de couverture de code plus basiques incluent les méthodes (combien de méthodes dans l'application ont été exécutées par les tests), classes et packages.

Jenkins vous permet de définir lesquelles de ces métriques vous voulez suivre. Par défaut, le plugin Cobertura enregistre les couvertures conditionnelles, lignes, et méthodes, ce qui est généralement suffisant. Cependant, il est facile de rajouter d'autres métriques de couverture de code si vous pensez que ce peut être utile pour votre équipe.

Le traitement par Jenkins des métriques de couverture de code n'est pas uniquement un affichage passif — Jenkins vous permet de définir comment ces métriques affectent le résultat du build. Vous pouvez définir des valeurs de palier pour les métriques de couverture de code qui affectent à la fois le résultat du build et le rapport météo sur le tableau de bord Jenkins (voir Figure 6.14, “Les résultats des tests de couverture de code contribuent à l'état du projet sur le tableau de bord”). Chaque métrique de couverture de code que vous suivez possède trois valeurs de palier.

Le premier (celui avec une icône ensoleillée) est la valeur minimale que le build doit atteindre pour avoir une icône ensoleillée. La seconde indique la valeur en dessous de laquelle le build aura une icône orageuse. Jenkins va extrapoler les valeurs intermédiaires entre ces deux-ci pour d'autres icônes météo plus nuancées.

Le dernier palier est simplement la valeur en dessous de laquelle un build sera marqué comme “instable” — avec une balle jaune. Bien que n'étant pas aussi mauvais qu'une balle rouge (pour un build cassé), une balle jaune entrainera un message de notification et apparaîtra comme mauvais sur le tableau de bord.

Cette fonctionnalité n'est pas un simple détail esthétique — elle fournit un moyen précieux de fixer des objectifs de qualité de code pour vos projets. Bien qu'elle ne puisse pas être interprétée seule, une mauvaise couverture de code n'est généralement pas un bon signe pour un projet. Donc si vous prenez la couverture de code au sérieux, utilisez ces valeurs de palier pour fournir un retour direct quand les choses ne sont pas à la hauteur.

Jenkins affiche vos rapports de couverture de code sur la page d'accueil de la tâche de build. La première fois qu'il est exécuté, il produit un simple graphique à barres (voir Figure 2.30, “Jenkins displays code coverage metrics on the build home page”). A partir du second build, un graphique est affiché, indiquant les différents types de couverture que vous suivez dans le temps (voir Figure 6.15, “Configurer les métriques de couverture de code dans Jenkins”). Dans les deux cas, le graphique affichera aussi les métriques de couverture de code pour le dernier build.

Jenkins offre une grande valeur ajoutée en vous permettant de descendre dans les métriques de couverture de code, affichant les erreurs de couverture de code pour les packages, classes à l'intérieur d'un package, et les lignes de code à l'intérieur d'une classe (voir Figure 6.16, “Afficher les métriques de couverture de code”). Quel que soit le niveau de détail que vous regardiez, Jenkins affichera un graphe en haut de la page montrant la tendance de couverture dans le temps. Plus bas, vous trouverez la répartition par package ou classe.

Lorsque vous arrivez au niveau de détail de la classe, Jenkins affiche aussi le code source de la classe, avec les lignes colorées en fonction de leur niveau de couverture. Les lignes qui ont été complètement exécutées pendant les tests sont en vert, et les lignes qui n'ont jamais été exécutées sont marquées en rouge. Un nombre dans la marge indique le nombre de fois que la ligne en question a été exécutée. Enfin, un ombrage jaune dans la marge est utilisée pour indiquée une couverture conditionnelle insuffisante (par exemple, une instruction if qui a seulement été testé avec un résultat).