Activation de la couverture de code à partir d'un script Ant

Pour vérifier que le code que vous créez répond à vos critères définis de couverture de code autorisés, vous pouvez activer la couverture de code à partir d'un script Ant. Pour ce faire, vous devez :

Configurer un script Ant pour activer la couverture de code
Exécuter le script Ant
Générer les statistiques de couverture de code
Générer les rapports de couverture de code
Désactiver la couverture de code

Vous pouvez également afficher les résultats de la couverture de code dans le plan de travail.

Configuration d'un script Ant pour activer la couverture de code

Pour configurer un script Ant pour activer la couverture de code, ajoutez ce qui suit à votre variable d'environnement CLASSPATH :
<rép_install>/plugins/com.ibm.rational.llc.engine_1.0.0.<numéro_version>
et définissez une nouvelle tâche dans le fichier build. Par exemple :

<taskdef name="instrument" classname="com.ibm.rational.llc.engine.instrumentation.anttask.InstrumentationTask" classpath="${install_dir}/plugins/com.ibm.rational.llc.engine_1.0.0.<numéro_version>"/>

Le format de la tâche de création est le suivant :

<instrument buildPath="" baseLineFile="" saveBackups="" outputDir=""/>

où :

buildPath:: Indique les fichiers pour lesquels les données de la couverture de code sont collectées. Le chemin build peut faire référence soit à un nom de fichier de classe, à un nom de fichier jar ou à un nom de répertoire. Il peut être défini exactement comme n'importe quelle autre référence de chemin utilisée dans Ant.
baseLineFile:: Indique le chemin de l'emplacement de stockage du fichier baseLine. Le fichier baseLine est le fichier auquel le code créé est comparé et qui déclenche la génération des statistiques de couverture de code. Il sert également d'entrée dans la tâche ant de génération de rapports.
saveBackups:: Indique s'il faut renommer la classe d'origine et les fichiers jar avec l'extension *.bak. Si vous paramétrez saveBackups sur true, les fichiers de sauvegarde seront générés ; si vous paramétrez saveBackups sur false, les fichiers d'origine sont écrasés (et donc perdus).
Remarque : saveBackups est facultatif et sa valeur par défaut est false.
outputDir:: Indique l'emplacement de stockage des fichiers créés. Par défaut, les fichiers créés sont stockés au même endroit que les fichiers en cours de création.

Exemple 1

Dans l'exemple suivant, les données de couverture de code sont collectées pour tous les fichiers dans bin/, le fichier baseLine est stocké dans blfile.coveragedata, aucune sauvegarde n'est générée pour ces fichiers et les fichiers créés sont stockés dans coverageData_files.

<instrument saveBackups="false" baseLineFile="blfile.coveragedata" buildPath="bin/" outputDir="coverageData_files"/>

Exemple 2

Dans l'exemple suivant, les données de couverture de code sont collectées pour tous les fichiers dans bin/, à savoir build.Dir, le fichier baseLine est stocké dans blfile.coveragedata et une sauvegarde de chacun de ces fichiers est générée.

<path id="build.Dir"> <pathelement location="bin"/> </path> <instrument saveBackups="true" baseLineFile="blfile.coveragedata" buildPathRef="build.Dir" />

Exemple 3

Dans l'exemple suivant, les données de couverture de code sont collectées pour tous les fichiers dans bin/, le fichier baseLine est stocké dans blfile.coveragedata et une sauvegarde de chacun de ces fichiers est générée.

<instrument saveBackups="true" baseLineFile="blfile.coveragedata"> <buildPath> <pathelement location="bin"/> </buildPath> </instrument>

Exemple 4

Dans l'exemple suivant, les données de couverture de code sont activées pour tous les sous-répertoires dans bin/ dont le nom de répertoire contient com et les fichiers se trouvant dans des sous-répertoires dont le nom contient Test sont exclus. Une sauvegarde est générée pour chaque fichier subissant une analyse de couverture de code et le fichier baseLine est stocké dans blfile.coveragedata.

<instrument saveBackups="true" baseLineFile="blfile.coveragedata"> <buildPath> <fileset dir="bin"> <exclude name="**/*Test*"/> <include name="**/*com*/*"> </fileset> </buildPath> </instrument>

Exemple 5

Dans l'exemple suivant, les données de couverture de code sont activées pour tous les fichiers dans bin/, à l'exception des fichiers des sous-répertoires bin dont le nom contient Test et bin2/. Une sauvegarde est générée pour chaque fichier subissant une analyse de couverture de code et le fichier baseLine est stocké dans blfile.coveragedata.

<instrument saveBackups="true" baseLineFile="blfile.coveragedata"> <buildPath> <fileset dir="bin"> <exclude name="**/*Test*"/> </fileset> </buildPath> <buildPath> <pathelement location="bin2"/> </buildPath> </instrument>

Exécutez le script Ant

Une fois que vous avez configuré le script Ant pour activer la couverture de code, vous pouvez exécuter le script Ant soit à partir de la ligne de commande, soit à partir du plan de travail.

Exécution à partir d'une ligne de commande

Pour exécuter le script Ant à partir de la ligne de commande :

Paramétrez la variable d'environnement JAVA_HOME sur le répertoire d'installation de JDK.
Vérifiez que votre variable d'environnement CLASSPATH contient bien le chemin complet et le nom du fichier probekit.jar. Le fichier probekit.jar se trouve dans le sous-dossier org.eclipse.hyades.probekit avec le numéro de version ultérieur et le dernier horodatage du dossier plugins de votre installation de produit.
Vérifiez que votre variable d'environnement CLASSPATH contient bien JAVA_HOME (le chemin de votre installation Java comme JAVA_HOME/bin/java est valide).
Vérifiez que votre variable d'environnement PATH contient bien le chemin complet du sous-dossier org.eclipse.hyades.probekit qui est propre à votre plateforme. Par exemple :
- Sous Windows :
  <rép_install>\plugins\org.eclipse.hyades.probekit_<version>\os\win32\x86
- Sous Linux :
  <rép_install>/plugins/org.eclipse.hyades.probekit_<version>/os/linux/x86
Paramétrez LLC_PLUGIN comme étant le chemin du dossier plugins :
set LLC_PLUGIN=<rép_install>\plugins

Exemple

ant -lib=<rép_install>\plugins\org.eclipse.hyades.probekit_<version>\probekit.jar myTarget

Exécution à partir du plan de travail

Pour exécuter le script Ant à partir du plan de travail :

Sélectionnez votre fichier build
Cliquez avec le bouton droit de la souris et sélectionnez Exécuter en tant que > Build Ant...
Sélectionnez l'onglet Classpath
Sélectionnez Entrées définies par l'utilisateur
Cliquez sur Ajouter des fichiers JAR externes...
Ajoutez <rép_install>\plugins\org.eclipse.hyades.probekit_<version>\probekit.jar à CLASSPATH à partir du sous-dossier plug-in org.eclipse.hyades.probekit avec le numéro de version ultérieur et le dernier horodatage
Sélectionnez l'onglet Cibles
Vérifiez la ou les cibles visées
Sélectionnez l'onglet Environnement
Cliquez sur le bouton Nouveau...
Dans la boîte de dialogue Nouvelle variable d'environnement, dans la zone Nom, entrez LLC_Plugin et dans la zone Valeur, entrez le chemin LLC_PLUGIN (par exemple <rép_install>\plugins)
Cliquez sur OK
Cliquez sur le bouton Nouveau...
Dans la boîte de dialogue Nouvelle variable d'environnement, dans la zone Nom, entrez PATH et dans la zone Valeur, entrez : <rép_install>\plugins\org.eclipse.hyades.probekit_<version>\os\win32\x86
Cliquez sur OK
Cliquez sur Exécuter

Génération des statistiques de couverture de code

Vérifiez que votre variable d'environnement classpath contient les éléments suivants :
<rép_install>\plugins\com.ibm.rational.llc.engine_1.0.0.<numéro_version>

Pour générer les statistiques de couverture de code à partir de la ligne de commande, dans le répertoire situé au-dessus du code, exécutez :

java -Dcoverage.out.file=C:\coverage_report\coverage_data.coveragedata com.ibm.rational.llc.example

Remarque : il se peut que vous soyez obligé de paramétrer votre programme Java pour qu'il corresponde à celui de l'installation du produit.

Génération de rapports de couverture de code

Pour générer un rapport à l'aide du script Ant :
Téléchargez le moteur de rapports d'exécution BIRT et dézippez son contenu. Paramétrez les variables d'environnement suivantes :

CLASSPATH - vers org.eclipse.equinox.common_<numéro_version>.jar
LLC_COMMON_PLUGIN - vers com.ibm.rational.llc.common_1.0.0.<numéro_version>
LLC_REPORT_PLUGIN - vers com.ibm.rational.llc.report.birt_1.0.0.<numéro_version>
BIRT_HOME - vers le répertoire ReportEngine à partir de l'exécution BIRT

Par exemple,
<path id="lib.path"> <pathelement location="${env.LLC_COMMON_PLUGIN}"/> <pathelement location="${env.LLC_REPORT_PLUGIN}"/> <fileset dir="${env.BIRT_HOME}/lib" includes="*.jar"/> </path>

définit une nouvelle tâche dans le fichier build pour la génération de rapport de couverture de code, par exemple :

<taskdef name="code-coverage-report" classname="com.ibm.rational.llc.report.birt.adapters.ant.ReportGenerationTask" classpathref="lib.path"/>

Le format de la tâche de rapport de couverture de code est le suivant :

<code-coverage-report outputDir="" coverageDataFile="" baseLineFiles=""> <filters> <filter type="" value=""/> </filters> <configurations> <configuration name="" value=""/> </configurations> </code-coverage-report>

où :

outputDir:

Indique l'emplacement de stockage des résultats des rapports.

coverageDataFile:

Indique un ou plusieurs fichiers de données de couverture pour lesquels un rapport doit être généré. Il peut être défini exactement comme n'importe quelle autre référence de chemin utilisée dans Ant.

baseLineFiles:

Indique un ou plusieurs fichiers baseLine ayant été générés au cours de la tâche de création. Il peut être défini exactement comme n'importe quelle autre référence de chemin utilisée dans Ant.

filters:

Facultatif : permet de filtrer les résultats de rapports.

filter:

type : indique le type de filtre à appliquer au rapport.

value : indique la valeur du filtre à appliquer au rapport.

Filtres disponibles :

Seuil de couverture de ligne : indique un seuil, pour le rapport de couverture de ligne, d'affichage des données inférieur à la valeur de pourcentage définie. type=line_coverage_threshold, value=threshold value

Configurations :

Facultatif : permet de définir différentes configurations de calcul.

Configuration :

name : nom de la configuration.

value : valeur de la configuration.

Configurations disponibles :

Inclusion du constructeur par défaut : détermine si les constructeurs par défaut sont exclus ou inclus dans les calculs de couverture de code. Par défaut, les constructeurs sont inclus. Si une classe ne définit aucun constructeur, le compilateur génère un défaut indiquant aucun constructeur d'argument. Cependant, ce constructeur n'apparaît pas dans le fichier source réel. Au cours de l'exécution du programme, si cette classe n'est pas instanciée, ce constructeur par défaut masqué n'est pas exécuté et, par conséquent, la couverture n'est pas de 100 % comme prévu. Ce comportement peut être modifié grâce à cette configuration : name=excludeDefaultConstructor, value=true or false

Exemple 1

Dans l'exemple suivant, la génération de rapport est collectée dans coverage-data/coverage.coveragedata en utilisant coverage-data/blfile.coveragedata comme fichier baseLine, le rapport est stocké dans coverage-reports et le filtre line_coverage_threshold est appliqué avec un seuil de 80 pour cent. Les constructeurs par défaut sont exclus des calculs de couverture de code.

<code-coverage-report outputDir="coverage-reports/" coverageDataFile="coverage-data/coverage.coveragedata" baseLineFiles="coverage-data/blfile.coveragedata"> <filters> <filter type="line_coverage_threshold" value="80"/> </filters> <configurations> <configuration name="excludeDefaultConstructor" value="true"/> </configurations> </code-coverage-report>

Exemple 2

Dans l'exemple suivant, la génération de rapport est collectée dans deux fichiers de couverture coverage1.coveragedata et coverage2.coveragedata en utilisant blfile1.coveragedata et blfile2.coveragedata comme fichiers baseLine et le rapport est stocké dans coverage-reports. Par défaut, les constructeurs sont inclus dans les calculs de couverture de code.

<code-coverage-report outputDir="coverage-reports/" coverageDataFile="coverage-data/coverage1.coveragedata;coverage-data/coverage2.coveragedata" baseLineFiles="coverage-data/blfile1.coveragedata;coverage-data/blfile2.coveragedata"> </code-coverage-report>

Affichage des résultats de la couverture de code dans le plan de travail

Pour afficher les résultats de la couverture de code du script Ant dans le plan de travail :

Importez le fichier de résultats coveragedata :

Sélectionnez Fichier > Importer...
Sélectionnez Couverture de code > Fichier de données de couverture de code
Cliquez sur le bouton Suivant
Sélectionnez le type d'importation du système de fichiers
Cliquez sur le bouton Suivant
Entrez l'emplacement du fichier de données de couverture à importer (coverage_data.coveragedata dans l'exemple ci-dessus), le nom du dossier dans lequel il va être importé et le ou les projects associés au fichier de données de couverture
Cliquez sur le bouton Terminer. Vous êtes alors invité à régénérer le projet s'il n'est pas encore activé pour la couverture de code.

Génération du rapport de couverture de code :

Sélectionnez Exécuter > Couverture de code > Générer un rapport...
Sélectionner un ou plusieurs lancements Java dans la colonne Nom.
Choisissez un rapport Eclipse ou HTML
Cliquez sur Exécuter

Remarque : vous pouvez, au lieu de sélectionner un ou plusieurs fichiers de données de couverture, cliquer avec le bouton droit de la souris, puis sélectionner Couverture de code > Générer un rapport.... Indiquez le projet associé ainsi que l'emplacement de dossier du rapport, puis cliquez sur Terminer.

Désactivation de la couverture de code

Pour désactiver les classes créées à l'aide de la tâche ant, recompilez le projet ou remplacez les fichiers .class par les fichiers .class.bak si l'option saveBackups a été activée.

Concepts connexes
Indicateurs de couverture de code

Rubriques connexes
Activation de la couverture de code
Configuration des niveaux et des filtres de couverture de code
Configuration des indicateurs de couverture de code
Analyse des rapports de couverture de code