このセクションの内容

はじめに

実行中のアプリケーションで手動または自動での機能テストを実行しながらカバレッジ データをモニターおよび収集できます。カバレッジ データおよびテスト結果を DTP サーバーにレポートし、データをマージして関連付けることもできます。アプリケーション カバレッジ情報を DTP のカバレッジ エクスプローラー (詳細は DTP ユーザーズ ガイドの「カバレッジ エクスプローラー」を参照) に表示し、アプリケーションがどの程度テストされたかや、テストの品質を知ることができます。 

前提条件

Java 1.8 - 17 の実行時カバレッジを収集できます。

Java JDK 8 でのバイトコードの改行の計算方法は、それより前のバージョンの Java と異なります。そのため、カバレッジの結果が変わる場合があります。

カバレッジ レポートにアプリケーションのソース コードに関する情報を含めるには、次のコンポーネントが必要です。

• Apache Maven、Gradle、または Ant ビルド システム

jtestcov ツールを使用するには、マシンに Java 11 以降がインストールされている必要があります。Oracle Java SE および OpenJDK がサポートされています。他のフリーやオープンソースの実装は、カバレッジ ツールの正常な動作を妨げる問題の原因になる可能性があります。JAVA_HOME 変数を設定し、システムの PATH に追加することを推奨します。jtestcov の使用方法については、「カバレッジ レポートの作成と DTP へのデータのアップロード」および「jtestcov のコマンド ライン オプション」を参照してください。

プロセスの概要

Jtest には、カバレッジ エージェントというコンポーネントが付属しています。カバレッジ エージェントは、テスト対象アプリケーション (AUT) にアタッチされ、AUT の実行されたコードをモニターします。AUT にカバレッジ エージェントをアタッチすると、REST API が公開され、テストおよびテスト セッションの開始および終了をマークできるようになります。 

カバーされるコード行に関するメタデータ (静的カバレッジ データ) は、アプリケーションのビルド プロセスの一環として特別なテスト コンフィギュレーションを実行するか、アプリケーションのバイナリをスキャンすることによって収集されます。テスト実行時には、カバレッジ エージェントとのやりとりが動的カバレッジ マップに書き込まれます。このマップには、実行されたコード行を示すマーカーが記録されます。  

Jtest は、この動的カバレッジ マップと静的カバレッジ データを処理します。カバレッジ情報を保存した coverage.xml が生成され、DTP に送信されます。DTP は、カバレッジ データを受信すると、カバレッジ イメージにロードします。カバレッジ イメージは、同じビルド ID を持つ複数の実行のカバレッジ データを集約することを可能にする特別なタグです。カバレッジ イメージにより、カバレッジ情報と特定のテストを関連付けることが可能になります。 

また、Jtest は実行時カバレッジおよび実行されたクラスに関する一般的な情報だけが含まれるアプリケーション カバレッジを収集することもできます。これには、カバーされた行以外のクラス構造の詳細は含まれません。簡略化されたレポートが DTP に送信され、DTP 上の既存のカバレッジ データに付加されます。クラス構造に関する情報 (静的カバレッジ データ) がすでに DTP に存在する場合、カバレッジ データを参照できます。 

テスト実行ツールの結果 (SOAtest のテスト、手動テストなど) も report.xml という形で DTP に送信されます。カバレッジ データ ファイルとレポートのビルド ID が一致すると、DTP はそれらのデータを関連付け、カバレッジ情報に表示します。 

カバレッジ レポートを作成し、DTP にアップロードするには、jtestcov または jtestcli を使用します。jtestcov は、カバレッジ専用のツールであり、カバレッジ レポートの生成に関してより多くのオプションがあります。「カバレッジ レポートの作成と DTP へのデータのアップロード」を参照してください。jtestcov.jar ファイルは <INSTALL_DIR>/integration ディレクトリにあります。jtestcov はスタンドアロン ツールであり、Jtest のインストール ディレクトリ外にコピーして単独で使用できます。そのため、テスト フローとの統合が容易です。jtestcov コマンド ライン オプションの詳細は、「jtestcov のコマンド ライン オプション」を参照してください。

カバレッジ収集のためのテスト対象アプリケーション (AUT) の構成

AUT の準備には、以下の手順が含まれます。

1. 任意: 事前設定済みのカバレッジ エージェント構成および静的カバレッジ ファイルを含むモニター パッケージを生成します。静的カバレッジ ファイルには、ユーザー クラス、メソッド、行などの情報が記録されます。「モニター パッケージの生成」を参照してください。
2. 実行時カバレッジを収集できるようカバレッジ エージェントを設定します。「カバレッジ エージェントの構成」を参照してください。
3. AUT にカバレッジ エージェントをアタッチします。「テスト対象アプリケーション (AUT) へのカバレッジ エージェントのアタッチ」を参照してください。

モニター パッケージの生成

モニター パッケージは、ビルド プロセス中に Jtest Maven、Gradle または Ant プラグインによって生成されます。カバレッジとAUTのソース コードが正しく照合されるよう、AUT のビルドに使用したのと同じビルド システムと Java のバージョンを使用してパッケージを生成してください。 

このパッケージには以下が含まれます。

• static_coverage.xml - 静的カバレッジ情報が保存されています。
• agent.jar - Jtest Java カバレッジ エージェントの jar アーカイブ。このファイルは、<INSTALL_DIR>/integration/coverage ディレクトリからコピーされます。
• agent.properties - エージェントの設定ファイルです。ビルド プロセス実行中に生成されたスコープ パラメーターや、他の属性が保存されています。
• agent.sh/agent.bat - エージェントを AUT プロセスにアタッチするために必要な Jtest Java エージェントの VM 引数を生成するスクリプトです。
• opentelemetry-javaagent.jar および jtest-otel-ext.jar - マルチユーザー カバレッジ モードで使用されます。元の OpenTelemetry Java エージェントとそれに対応する Jtest 拡張です。この拡張は、収集されたカバレッジを特定のユーザーに割り当てるのに必要なデータを収集します。これらのファイルは、<INSTALL_DIR>/integration/coverage ディレクトリからコピーされます。

パッケージは、ソース コードがあるビルド マシン上で生成される必要があります。生成された静的カバレッジ ファイルは、コードが変更されるまで使用できます。

パッケージを生成するには、AUT のメイン ディレクトリで、次のコマンドを実行します。

Maven

mvn package jtest:monitor

Gradle

gradle assemble jtest-monitor -I [INSTALL]/integration/gradle/init.gradle

Ant

ant -lib [INSTALL]/integration/ant/jtest-ant-plugin.jar -listener com.parasoft.Listener jtest-monitor

<target name="jtest-monitor" depends="compile">
             <jtest:monitor/>
</target>

monitor.zip パッケージが生成され、ビルド出力ディレクトリに置かれます。その場所へのパスがコンソールに出力されます。 

カバレッジ エージェントの構成 

通常、アプリケーション サーバーには複数のアプリケーションがあります。さらに、共通サーバー クラスまたはアプリケーション ライブラリはインストゥルメントする必要がありません。Jtest がカバレッジを収集する必要があるのは、アプリケーションのソース コードだけです。すべてのクラスをインストゥルメントすると、時間がかかりすぎる場合があります。

サーバー上のアプリケーションは既にビルドされており、ソース コードからどのクラスが生成されたかに関する情報を収集することはできません。このため、Jtest エージェントのスコープを適切に設定することが非常に重要です。

カバレッジ エージェントは、以下の方法で設定できます。

• agent.properties ファイルを使用して
• AUT にカバレッジ エージェントをアタッチする際に -javaagent への引数を使用して。「テスト対象アプリケーション (AUT) へのカバレッジ エージェントのアタッチ」を参照してください。 

agent.properties および agent.jar ファイルは <INSTALL_DIR>/integration/coverage ディレクトリにあります。agent.properties ファイルのデフォルト プロパティを変更してカバレッジ エージェントを適切に設定できます。以下は、agent.properties ファイルを使ってカバレッジ エージェントを設定する例です。

jtest.agent.autostart=false
jtest.agent.serverEnabled=true
jtest.agent.includes=com/myapp/**
jtest.agent.runtimeData=[...]

monitor.zip パッケージを生成済みの場合、パッケージに含まれている agent.properties ファイルを使用できます。このファイルには、ビルド プロセス実行時に生成されたスコープ パラメーターやその他の属性がすでに含まれています。 

コマンド ラインで -javaagent にプロパティを追加するには、jtest.agent 接頭辞を削除して名前を変更する必要があります。例:

-javaagent:"[path to agent dir]\agent.jar"=settings="[path to agent properties file]\agent.properties",autostart=true

以下の表は、カバレッジ エージェントを設定するために使用できる全プロパティの一覧です。

テスト対象アプリケーション (AUT) へのカバレッジ エージェントのアタッチ 

1. 任意: monitor.zip パッケージを使用したい場合:
   1. パッケージの内容をサーバー マシンに展開します。

   2. gent.sh/agent.bat スクリプトを実行して Jtest Java エージェントの VM 引数を生成します。スクリプトは、コンソールに -javaagent VM 引数を出力します。

2. -javaagent フラグを使用してエージェントを AUT にアタッチします。結果は runtime_coverage サブ ディレクトリに出力されます。 

   Jtest Agent VM argument:
   -javaagent:"[path to agent dir]\agent.jar"=settings="[path to agent properties file]\agent.properties",runtimeData="[path to runtime coverage folder]"

   -javaagent を使用したカバレッジ エージェントの構成については「カバレッジ エージェントの構成」を参照してください。

3. アプリケーション サーバーの起動スクリプトに -javaagent フラグを追加してエージェントを AUT にアタッチします。AUT にカバレッジ エージェントをアタッチすると、エージェントを制御するための REST API が公開されます。 
4. AUT を再起動します (「Web アプリケーション カバレッジのチュートリアル」の手順 5, 3 を参照)。 
5. ブラウザーに次の URL を入力して、カバレッジ エージェントが設定されていることを確認します。
   [application_host]:8050/status/
   アプリケーションが適切に構成されている場合、API は次のデータを返します。
   

HTTPS 経由での Coverage Agent への接続

デフォルトでは、カバレッジ エージェントは HTTP プロトコル経由で利用できます。HTTPS 経由で接続するには、Jtest Agent VM 引数に次のオプションを追加し、カバレッジ エージェントを設定する必要があります (「テスト対象アプリケーション (AUT) へのカバレッジ エージェントのアタッチ」を参照)。

• useSSL=true

• certificateStorePath=[キーストア ファイルへのパス]

• certificateStorePassword=[キーストア ファイルのパスワード]

• certificateStoreType=[キーストア ファイルのフォーマット]

• certificateKeyPassword=[SSL 証明書へのパスワード]

アプリケーション サーバーの起動スクリプトに追加される Jtest Agent VM 引数は次のようになります。

-javaagent:"[path to agent dir]\agent.jar"=settings="[path to agent properties file]\agent.properties",runtimeData="[path to runtime coverage folder]",useSSL=true,certificateStorePath="F:\certificates\keystore.jks",certificateStorePassword=4!ij?ffQMk,certificateStoreType="JKS",certificateKeyPassword=dhW!34

こうすると、カバレッジ エージェントはテスト対象アプリケーション用に設定された SSL 証明書を認識できるようになります。

テストを実行してランタイム カバレッジを収集する

実行時カバレッジを収集するには、次の方法があります。

• SOAtest を使用して機能テストを実行します。SOAtest はテスト実行中に実行時カバレッジを収集し、データを DTP に送信します。テスト セッション実行の詳細については、SOAtest ユーザー ガイドを参照してください。
• アプリケーションにカバレッジ エージェントをアタッチしてテストを実行します。実行時カバレッジ ディレクトリにカバレッジが収集されます。次に、実行時カバレッジと静的カバレッジををマージし、マージされたデータを DTP にアップロードします。詳細は「カバレッジ レポートの作成と DTP へのデータのアップロード」を参照してください。

DTP への結果のアップロード

実行済みのテストの結果を DTP にアップロードするには、次の操作を行います。

1. DTP のインターフェイスで [Report Center] に移動します。
2. 歯車のアイコンをクリックして [Report Center 設定] > [その他の設定] > [Report Center の管理] > [ツール] > [Data Collector アップロード フォーム] をクリックします (管理者権限が必要です)。
3. [ファイルの選択] をクリックし、report.xml ファイルを選択します。
4. [アップロード] ボタンをクリックし、ファイルを DTP にアップロードします。

SOAtest を使用する場合、テスト実行時にテスト結果が自動的に DTP に送信されます。https://docs.parasoft.com にある SOAtest ユーザー ガイドの「アプリケーション カバレッジ」 セクションを参照してください。

カバレッジ レポートの作成と DTP へのデータのアップロード

jtestcov または jtestcli コマンドを使用してカバレッジ レポートを作成し、DTP にデータをアップロードできます。jtestcov コマンド ライン オプションの詳細は、「jtestcov のコマンド ライン オプション」を参照してください。

3 つのタイプのカバレッジ レポートを生成できます。

1. 静的カバレッジおよび実行時カバレッジ レポート: マージされた静的カバレッジ (ソース コード情報を含む) および実行時カバレッジが含まれています。このレポートを作成するには、-runtimeCoverage および -staticCoverage スイッチを指定して jtestcli を実行するか、-runtime および -static をスイッチを指定して jtestcov を実行します。
2. アプリケーション カバレッジ レポート: アプリケーションのバイナリおよび実行時カバレッジをスキャンすることで生成される静的カバレッジ レポートです。このレポートを作成するには、-app および -runtime スイッチを指定して jtestcov を実行します。
3. 実行時カバレッジ レポート: 実行時カバレッジおよび実行されたクラスに関する一般的な情報だけが含まれる簡易的なアプリレポートです。カバーされた行以外のクラス構造の詳細は含まれません。既存のアプリケーションまたは静的カバレッジベースのデータが DTP に存在する場合、このレポートを参照できます。このレポートを作成するには、-runtime スイッチを指定して jtestcov を実行します。

カバレッジ レポートを作成し、DTP にデータをアップロードするには、次の操作を行います。

1. Jtest で DTP、スコープ、作成者が適切に設定されていることを確認します。「DTP への接続」、「DTP への結果の送信とソース コードのパブリッシュ」、「設定」を参照してください。
2. 適切にカバレッジ データをマージするには、jtestcov.properties ファイル (<INSTALL_DIR>/integration/coverage にあります) または jtestcli.properties ファイルで以下の設定を行います。
   - report.coverage.images - DTP でカバレッジ イメージを作成するために使用するタグのセットを指定します。カバレッジ イメージは、同じビルド ID を持つ複数の実行のカバレッジ データを集約する際に一意の識別子となります。DTP は、1 レポートにつき最大 3 つまでのカバレッジ イメージをサポートします。
   - session.tag - 同じビルドの個々のテスト実行を区別する一意の識別子を指定します。
   - build.id - 結果にラベル付けするためのビルド識別子を指定します。ビルドごとに固有の値を使用することも、特定のビルドで実行される複数のテストセッションで同じ値を使用することもできます。
3. jtestcli を使用する場合、実行時カバレッジ ファイルおよび静的カバレッジ ファイルを同じマシンにコピーし、次のスイッチを指定して jtestcli を実行します。
   
   • -runtimeCoverage: カバレッジ エージェントを使用して収集された実行時カバレッジ データへのパスを指定します。単一のテスト セッションのカバレッジ情報を保存した個々の .data ファイルへのパスを指定することも、複数のテスト セッションの .data ファイルを含むフォルダーへのパスを指定することもできます。
   • -staticCoverage: 静的カバレッジ ファイルへのパスを指定します (「モニター パッケージの生成」を参照)。
   • -config: カバレッジ データをマージするために実行する必要のある Calculate Application Coverage テスト コンフィギュレーションの URL を指定します。

   • -publish: マージされたカバレッジを DTP に送信します。

     jtestcli -staticcoverage [path to static_coverage.xml file] -runtimecoverage [path/dir]
     -config "builtin://Calculate Application Coverage" -publish

     これによって、coverage.xml ファイルに実行時カバレッジ データを書き込みできるよう、静的カバレッジ データだけでなく、テスト実行時に生成される実行時データ カバレッジにも Jtest がアクセスできるようになります。

4. jtestcov を使用する場合、以下のスイッチを指定して jtestcov を実行します。
   • -app: テスト対象アプリケーションのディレクトリまたはアーカイブ ファイルへのパスを指定します。
   • -runtime: カバレッジ エージェントを使用して収集された実行時カバレッジ データへのパスを指定します。単一のテスト セッションのカバレッジ情報を保存した個々の .data ファイルへのパスを指定することも、複数のテスト セッションの .data ファイルを含むフォルダーへのパスを指定することもできます。
   • -static: 静的カバレッジ ファイルへのパスを指定します (「モニター パッケージの生成」を参照)。

   • -publish: マージされたカバレッジを DTP に送信します。

     例 1: 実行時データおよびモニターからの静的カバレッジに基づいてレポートを生成する

     java -jar jtestcov.jar -static [path to static_coverage.xml file] -runtime [path/dir]
     -publish -settings [path to jtestcov.properties]

     例 2: 実行時データおよびアプリケーション バイナリからのカバレッジに基づいてレポートを生成する

     java -jar jtestcov.jar -app [path/dir] -runtime [path/dir] -publish
     -settings [path to jtestcov.properties]

      例 3: 実行時データに基づいてレポートを生成する

     java -jar jtestcov.jar -runtime [path/dir] -publish -settings [path to jtestcov.properties]

5. 以前に生成された実行時カバレッジ レポートをマージするには、jtestcov merge コマンドを実行します。2 つ以上のレポートをマージするには、次のコマンドを実行します。

   java -jar jtestcov.jar merge -coverage <REPORT_FILE> -coverage <REPORT_FILE> 
   [-coverage <REPORT_FILE>] [-report <REPORT_DIR>] [-excludeunmatchedruntime]

   • -coverage <REPORT_FILE>: マージして DTP にパブリッシュする 1 つ以上の入力カバレッジ レポートを指定します。
   • -report <REPORT_DIR>: (任意) 指定されたフォルダーに xml カバレッジ レポートを生成します。デフォルトでは、レポートは .coverage/reports フォルダーに保存されます。

SOAtest を使用する場合、テスト実行時に静的カバレッジおよび実行時カバレッジ データがマージされ、DTP に送信されます。https://docs.parasoft.com にある SOAtest ユーザー ガイドの「アプリケーション カバレッジ」 セクションを参照してください。

DTP でのカバレッジの参照

DTP のカバレッジ エクスプローラーを使用して、テスト実行時のアプリケーション カバレッジを参照できます。カバレッジ情報の参照についての詳細は、https://docs.parasoft.com にある DTP ユーザー ガイドを参照してください。

既知の制限事項

• 1 つの Web アプリケーションに複数のユーザーが同時にアクセスした場合、複数のユーザーのカバレッジデータが混在する場合があります。個々のユーザーに正しくカバレッジが関連付けられるようにするには、マルチユーザー モードを有効にします (「カバレッジ エージェントの構成」を参照)。
• マルチユーザー モードでは、同じ Web アプリケーションにアクセスしている他のユーザーの余分なカバレッジ情報が、「デフォルト」ユーザー (ID が指定されていないユーザー) に集約される場合があります。
• マルチユーザー モードでは、マルチスレッド アプリケーションで収集されたカバレッジが個別のユーザーに割り当てられない場合があります。これには、スレッド間のコンテキスト共有に関する OpenTelemetry の制限が関係しています。
• マルチユーザー モードでは、Jacoco エンジンを使用したカバレッジの収集はサポートされていません。
• Web アプリケーションの初期化から収集されたカバレッジ データは、特定のユーザーではなく「デフォルト」ユーザーに割り当てられます。

jtestcov のコマンド ライン オプション

このセクションは、jtestcov のコマンド ライン オプションの一覧です。

coverage

デフォルトのコマンドです。アプリケーションおよび実行時カバレッジ データをスキャンしてカバレッジ レポートを生成します。レポートを生成するには、次のコマンドを実行します。

java -jar jtestcov.jar coverage [-app <APP_LOCATION> | -static <BASE_COVERAGE_REPORT_FILE>] 
[-runtime <RUNTIME_COVERAGE_LOCATION>] [-report <REPORT_DIR>] [-deleteruntime] [-excludeunmatchedruntime]

-app <APP_LOCATION>

テスト対象アプリケーション (AUT) のディレクトリまたはアーカイブ ファイル (war、ear、jar、zip) の場所を指定します。

-static <BASE_COVERAGE_REPORT_FILE>

AUT のカバレッジ ベースを含む XML カバレッジ レポート ファイルを指定します。

-runtime <RUNTIME_COVERAGE_LOCATION>

AUT に対してテストを実行したときに生成された実行時カバレッジ ディレクトリの場所を指定します。

-report <REPORT_DIR>

指定されたフォルダーに XML カバレッジ レポートを生成します。任意パラメーターです。デフォルトでは、レポートは .coverage/reports フォルダーに保存されます。

-deleteruntime

カバレッジ XML レポートの生成に使用した実行時カバレッジ データ ファイルを削除します。
このパラメーターが指定されている場合、レポート作成後に実行時カバレッジ データ ファイルが削除されます。

-excludeunmatchedruntime

カバレッジ ベースに含まれるクラスに一致しない実行時カバレッジ データを処理から除外します。
このパラメーターが指定されている場合、一致しない実行時カバレッジ データは最終的なカバレッジ レポートから除かれます。

impacted

アプリケーションをスキャンし、ベースライン カバレッジ レポートを解析して再実行が必要なテストを検出します。影響を受けるテストの LST ファイルを生成するには、次のコマンドを実行します。 

java -jar jtestcov.jar impacted -app <APP_LOCATION> 
-baseline <BASELINE_COVERAGE_REPORT FILE> [-report <LST_FILE_DIR>]

-app <APP_LOCATION>

テスト対象アプリケーション (AUT) のディレクトリまたはアーカイブ ファイル (war、ear、jar、zip) の場所を指定します。

-baseline <BASELINE_COVERAGE_REPORT_FILE>

ベースラインとして使用する XML カバレッジ レポートを指定します。

-report <LST_FILE_DIR>

指定された場所に LST ファイルを生成します。LST ファイルがすでに存在する場合、上書きされます。任意パラメーターです。デフォルトでは、LST ファイルは .coverage/lsts フォルダーに保存されます。

merge

以前に生成された実行時カバレッジ レポートをマージします。2 つ以上のレポートをマージするには、次のコマンドを実行します。

java -jar jtestcov.jar merge -coverage <REPORT_FILE> -coverage <REPORT_FILE> 
[-coverage <REPORT_FILE>] [-report <REPORT_DIR>] [-excludeunmatchedruntime]

-coverage <REPORT_FILE>

マージして DTP にパブリッシュする 1 つ以上のカバレッジ XML レポートを指定します。

-report <REPORT_DIR>

指定されたフォルダーに XML カバレッジ レポートを生成します。任意パラメーターです。デフォルトでは、レポートは .coverage/reports フォルダーに保存されます。

help

jtestcov ヘルプを表示します。

その他の引数

-include <PATTERN>
-exclude <PATTERN>

AUT のスキャン時に含める/除外する要素のパターンを指定します。任意パラメーターです。デフォルトでは、すべての要素が対象になります。

-publish

生成されたレポートを DTP Server にアップロードします。(設定パターン: report.dtp.publish=true)

-settings <SETTINGS_FILE>

ファイルからカスタム設定を読み取ります。<SETTINGS_FILE> は、<KEY=VALUE> 形式のエントリを含む既存の設定ファイル (.properties) である必要があります。

-property

カスタム設定エントリを指定します。-property を複数回使用できます (複数のエントリに同じキーが含まれている場合、最初に指定されたエントリが後のすべてのエントリを上書きします)。

-showdetails

出力の冗長性を上げます。
(設定パターン: console.verbosity.level=high)

jtestcov 終了コード

プロセスは、次の終了コードで終了する場合があります。