Codeabdeckung über ein Ant-Script aktivieren

Durch eine Aktivierung der Codeabdeckung über ein Ant-Script können Sie prüfen, ob der von Ihnen erstellte Code die Abnahmekriterien für die Codeabdeckung erfüllt, die Sie definiert haben. Hierzu müssen Sie Folgendes ausführen:

Ant-Script zur Aktivierung der Codeabdeckung konfigurieren
Ant-Script ausführen
Codeabdeckungsstatistik generieren
Codeabdeckungsberichte generieren
Codeabdeckung inaktivieren

Sie haben außerdem die Möglichkeit, die Codeabdeckungsergebnisse in der Workbench anzuzeigen.

Ant-Script zur Aktivierung der Codeabdeckung konfigurieren

Um ein Ant-Script zur Aktivierung der Codeabdeckung zu konfigurieren, fügen Sie Folgendes zur Umgebungsvariablen CLASSPATH hinzu:
<installationsverzeichnis>/plugins/com.ibm.rational.llc.engine_1.0.0.<versionsnummer>
Anschließend definieren Sie eine neue Task in der Builddatei (Erstellungsdatei). Beispiel:

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

Die Instrumentierungstask hat das folgende Format:

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

Hierbei gilt Folgendes:

buildPath:: Gibt die Dateien an, für die Codeabdeckungsdaten erfasst werden sollen. Der Erstellungspfad kann entweder der Name einer Klassendatei, der Name einer JAR-Datei oder ein Verzeichnisname sein. Die Definition erfolgt wie bei allen anderen in Ant verwendeten Pfadreferenzen.
baseLineFile:: Gibt den Pfad an, in dem die Referenzdatei gespeichert ist. Bei der Referenzdatei handelt es sich um die Datei, mit der der instrumentierte Code zur Generierung der Codeabdeckungsstatistik verglichen wird. Außerdem dient sie als Eingabe für die Ant-Task zur Berichterstellung.
saveBackups:: Gibt an, ob die ursprünglichen Klassen- und JAR-Dateien in '*.bak' umbenannt werden sollen. Wird der Parameter 'saveBackups' auf den Wert true gesetzt, erfolgt eine Generierung der Sicherungsdateien. Die Verwendung des Wertes false für den Parameter 'saveBackups' führt dazu, dass die ursprünglichen Dateien überschrieben werden (und daher verlorengehen).
Anmerkung: Der Parameter 'saveBackups' ist optional, sein Standardwert lautet 'false'.
outputDir:: Gibt die Position für die Speicherung der instrumentierten Dateien an. Standardmäßig werden die instrumentierten Dateien an derselben Position gespeichert wie die Dateien, für die die Instrumentierung ausgeführt wurde.

Beispiel 1

Im folgenden Beispiel werden Codeabdeckungsdaten für alle Dateien im Verzeichnis bin/ erfasst. Die Referenzdatei ist unter blfile.coveragedata gespeichert und für die Dateien werden keine Sicherungen generiert. Die instrumentierten Dateien werden unter coverageData_files gespeichert.

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

Beispiel 2

Im folgenden Beispiel werden Codeabdeckungsdaten für alle Dateien im Verzeichnis bin generiert, das als build.Dir referenziert wird. Die Referenzdatei ist unter blfile.coveragedata gespeichert und für alle Dateien wird eine Sicherung generiert.

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

Beispiel 3

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

Beispiel 4

Im folgenden Beispiel werden Codeabdeckungsdaten für alle Unterverzeichnisse des Verzeichnisses bin/ generiert, deren Verzeichnisname die Zeichenfolge com enthält. Dateien in Unterverzeichnissen, deren Name die Zeichenfolge Test enthält, werden hierbei ausgeschlossen. Für alle Dateien, die der Codeabdeckungsanalyse unterzogen werden, wird eine Sicherung generiert. Die Referenzdatei ist unter blfile.coveragedata gespeichert.

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

Beispiel 5

Im folgenden Beispiel werden Codeabdeckungsdaten für alle Dateien im Verzeichnis bin/ generiert, allerdings mit Ausnahme der Dateien in den Unterverzeichnissen von 'bin', deren Namen die Zeichenfolge 'Test' enthalten. Außerdem werden Codeabdeckungsdaten für alle Dateien im Verzeichnis bin2/ generiert. Für alle Dateien, die der Codeabdeckungsanalyse unterzogen werden, wird eine Sicherung generiert. Die Referenzdatei ist unter blfile.coveragedata gespeichert.

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

Ant-Script ausführen

Nachdem Sie das Ant-Script zur Aktivierung der Codeabdeckung konfiguriert haben, können Sie entweder das Ant-Script über die Befehlszeile oder über die Workbench ausführen.

Script über die Befehlszeile ausführen

So führen Sie das Ant-Script über die Befehlszeile aus:

Setzen Sie die Umgebungsvariable JAVA_HOME auf das Verzeichnis, in dem das Java Development Kit (JDK) installiert ist.
Stellen Sie sicher, dass die Umgebungsvariable CLASSPATH den vollständigen Pfad und Dateinamen der Datei 'probekit.jar' enthält. Die Datei 'probekit.jar' befindet sich im Ordner 'plugins' Ihrer Produktinstallation im Unterordner 'org.eclipse.hyades.probekit' mit der höchsten Versionsnummer und der aktuellsten Zeitmarke.
Stellen Sie sicher, dass die Umgebungsvariable CLASSPATH die Variable JAVA_HOME enthält (also den Pfad zu Ihrer Java-Installation, damit 'JAVA_HOME/bin/java' gültig ist).
Stellen Sie sicher, dass die Umgebungsvariable PATH den vollständigen Pfad des entsprechenden Unterordners von 'org.eclipse.hyades.probekit' für Ihre Plattform enthält. Beispiel:
- Windows:
  <installationsverzeichnis>\plugins\org.eclipse.hyades.probekit_<version>\os\win32\x86
- Linux:
  <installationsverzeichnis>/plugins/org.eclipse.hyades.probekit_<version>/os/linux/x86
Legen Sie LLC_PLUGIN als Pfad zum Ordner 'plugins' fest:
set LLC_PLUGIN=<installationsverzeichnis>\plugins

Beispiel

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

Script über die Workbench ausführen

So führen Sie das Ant-Script über die Workbench aus:

Wählen Sie die Builddatei (Erstellungsdatei) aus.
Klicken Sie mit der rechten Maustaste und wählen Sie die Optionen Ausführen als > Ant-Erstellung... aus.
Wählen Sie die Registerkarte 'Klassenpfad' aus.
Wählen Sie Benutzereinträge aus.
Klicken Sie auf Externe JARs hinzufügen...
Fügen Sie die Angabe '<installationsverzeichnis>\plugins\org.eclipse.hyades.probekit_<version>\probekit.jar' zum CLASSPATH-Wert aus dem Plug-in-Unterordner 'org.eclipse.hyades.probekit' mit der höchsten Versionsnummer und der aktuellsten Zeitmarke hinzu.
Wählen Sie die Registerkarte 'Ziele' aus.
Wählen Sie die gewünschten Ziele aus.
Wählen Sie die Registerkarte 'Umgebung' aus.
Klicken Sie auf die Schaltfläche Neu...
Geben Sie im Dialogfenster 'Neue Umgebungsvariable' im Feld 'Name' die Zeichenfolge LLC_Plugin und im Feld 'Wert' den Pfad von LLC_PLUGIN ein (z. B. <installationsverzeichnis>\plugins).
Klicken Sie auf OK.
Klicken Sie auf die Schaltfläche Neu...
Geben Sie im Dialogfenster 'Neue Umgebungsvariable' im Feld 'Name' die Zeichenfolge PATH und im Feld 'Wert' die Angabe '<installationsverzeichnis>\plugins\org.eclipse.hyades.probekit_<version>\os\win32\x86' ein.
Klicken Sie auf OK.
Klicken Sie auf Ausführen.

Codeabdeckungsstatistik generieren

Stellen Sie sicher, dass Ihr Klassenpfad die folgende Angabe enthält:
<installationsverzeichnis>\plugins\com.ibm.rational.llc.engine_1.0.0.<versionsnummer>

Zur Generierung der Codeabdeckungsstatistik über die Befehlszeile führen Sie aus dem übergeordneten Verzeichnis des Codes heraus Folgendes aus:

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

Anmerkung: Möglicherweise müssen Sie Java übereinstimmend mit der Produktinstallation definieren.

Codeabdeckungsberichte generieren

So generieren Sie mit Ant einen Bericht:
Laden Sie die Komponente BIRT Runtime Report Engine (BIRT-Laufzeitberichtsengine) herunter und dekomprimieren Sie ihren Inhalt. Legen Sie die Umgebungsvariablen wie folgt fest:

Die Variable CLASSPATH muss auf 'org.eclipse.equinox.common_<versionsnummer>.jar' zeigen.
Die Variable LLC_COMMON_PLUGIN muss auf 'com.ibm.rational.llc.common_1.0.0.<versionsnummer>' zeigen.
Die Variable LLC_REPORT_PLUGIN muss auf 'com.ibm.rational.llc.report.birt_1.0.0.<versionsnummer>' zeigen.
Die Variable BIRT_HOME muss auf das Verzeichnis 'ReportEngine' aus der BIRT-Laufzeit zeigen.

Beispiel:
<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>

Definieren Sie in der Builddatei (Erstellungsdatei) eine neue Task für die Generierung von Codeabdeckungsberichten. Beispiel:

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

Die Task für Codeabdeckungsberichte hat das folgende Format:

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

Hierbei gilt Folgendes:

outputDir:

Gibt die Position für die Speicherung der Berichtsergebnisse an.

coverageDataFile:

Gibt eine oder mehrere Abdeckungsdatendateien an, aus denen der Bericht generiert wird. Die Definition erfolgt wie bei allen anderen in Ant verwendeten Pfadreferenzen.

baseLineFiles:

Gibt eine oder mehrere Referenzdateien an, die als Teil der Instrumentierungstask generiert wurden. Die Definition erfolgt wie bei allen anderen in Ant verwendeten Pfadreferenzen.

filters:

Optional: Wird zur Filterung der Berichtsergebnisse verwendet.

filter:

type: Der Typ des Filters, der auf den Bericht angewendet werden soll.

value: Der Wert des Filters, der auf den Bericht angewendet werden soll.

Verfügbare Filter:

Schwellenwert für Zeilenabdeckung: Legt einen Schwellenwert für den Zeilenabdeckungsbericht fest, damit Daten unter dem angegebenen Prozentsatz angezeigt werden. type=line_coverage_threshold, value=schwellenwert

configurations:

Optional: Wird zur Angabe verschiedener Berechnungskonfigurationen verwendet.

configuration:

name: Der Name der Konfiguration.

value: Der Wert der Konfiguration.

Verfügbare Konfigurationen:

Einschluss des Standardkonstruktors: Konfigurieren Sie, ob Standardkonstruktoren bei den Berechnungen für die Codeabdeckung berücksichtigt werden sollen oder nicht. Standardmäßig werden die Standardkonstruktoren eingeschlossen. Falls eine Klasse keinen Konstruktor definiert, generiert der Compiler standardmäßig einen Konstruktor ohne Argument. Dieser Konstruktor wird jedoch in der eigentlichen Quellendatei nicht dargestellt. Wenn diese Klasse während der Programmausführung nicht instanziiert wird, wird dieser verdeckte Standardkonstruktor nicht ausgeführt und die Abdeckung liegt entgegen der Erwartung nicht bei 100%. Dieses Verhalten kann durch die folgende Konfiguration geändert werden: name=excludeDefaultConstructor, value=true oder false

Beispiel 1

Im folgenden Beispiel wird die Berichterstellung für coverage-data/coverage.coveragedata unter Verwendung der Referenzdatei coverage-data/blfile.coveragedata erfasst. Der Bericht wird unter coverage-reports gespeichert und der Filter 'line_coverage_threshold' wird mit einem Schwellenwert von 80% angewendet. Standardkonstruktoren werden aus den Berechnungen für die Codeabdeckung ausgeschlossen.

<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>

Beispiel 2

Im folgenden Beispiel wird die Berichterstellung für die beiden Abdeckungsdateien coverage1.coveragedata und coverage2.coveragedata unter Verwendung der Referenzdateien blfile1.coveragedata und blfile2.coveragedata erfasst. Der Bericht wird unter coverage-reports gespeichert. Standardkonstruktoren werden standardmäßig in die Berechnungen für die Codeabdeckung eingeschlossen.

<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>

Codeabdeckungsergebnisse in der Workbench anzeigen

So können Sie die Codeabdeckungsergebnisse des Ant-Scripts in der Workbench anzeigen:

Importieren Sie die Ergebnisdatei der Abdeckungsdaten. Gehen Sie hierzu folgendermaßen vor:

Wählen Sie die Optionen Datei > Importieren... aus.
Wählen Sie die Optionen Codeabdeckung > Datendatei für Codeabdeckung aus.
Klicken Sie auf die Schaltfläche Weiter.
Wählen Sie den Importtyp 'Dateisystem' aus.
Klicken Sie auf die Schaltfläche Weiter.
Geben Sie die Position der zu importierenden Abdeckungsdatendatei (im obigen Beispiel ist dies die Position 'coverage_data.coveragedata'), den Namen des Zielordners für den Import und die Projekte ein, die der Abdeckungsdatendatei zugeordnet sind.
Klicken Sie auf die Schaltfläche Fertig stellen. Anschließend werden Sie aufgefordert, das Projekt erneut zu erstellen, falls es für die Codeabdeckung noch nicht aktiviert ist.

Generieren Sie den Codeabdeckungsbericht. Gehen Sie hierzu folgendermaßen vor:

Wählen Sie die Optionen Ausführen > Codeabdeckung > Bericht generieren... aus.
Wählen Sie unter der Spalte Name einen oder mehrere Java-Startvorgänge aus.
Wählen Sie das Format des Berichts aus (entweder Eclipse-basiert oder HTML-basiert).
Klicken Sie auf Ausführen.

Anmerkung: Statt eine oder mehrere Abdeckungsdateiendateien auszuwählen, können Sie auch mit der rechten Maustaste klicken und dann die Optionen Codeabdeckung > Bericht generieren... auswählen. Geben Sie das zugeordnete Projekt und die Ordnerposition für den Bericht an und klicken Sie auf Fertig stellen.

Codeabdeckung inaktivieren

Um Klassen zu inaktivieren, die mit der Ant-Task instrumentiert wurden, müssen Sie das Projekt erneut kompilieren oder die Dateien '.class' durch die Dateien '.class.bak' ersetzten, falls der Parameter 'saveBackups' aktiviert wurde.

Zugehörige Konzepte
Codeabdeckungsanzeiger

Zugehörige Tasks
Codeabdeckung aktivieren
Stufen und Filter für Codeabdeckung konfigurieren
Codeabdeckungsanzeiger konfigurieren
Codeabdeckungsberichte analysieren