はじめに

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

プロセスの概要

dotTEST には、アプリケーションのカバレッジ収集を可能にするカバレッジ エージェントというコンポーネントが付属しています。スタンドアロン アプリケーションのカバレッジは、カバレッジ エンジンの REST クライアント (agent_client.exe) を使用して、または使用せずに収集できます。Web アプリケーションのカバレッジを収集するには、REST クライアントを使用する必要があります。

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

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

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

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

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

カバレッジ エージェント使用の前提条件

モニター対象のアプリケーションが実行されるマシンに、dotTEST に付属している Visual C++ 再頒布可能パッケージがインストールされていることを確認してください。ウィザード (「インストール」を参照) を使用して dotTEST をインストールした場合、パッケージは自動的にインストールされます。ZIP ディストリビューションから dotTEST をインストールした場合、または別のマシンでカバレッジを収集する場合は、次のディレクトリにある実行モジュールを手動で実行してパッケージをインストールしてください。:<INSTALL_DIR>\bin\prerequisites

モニター対象のアプリケーションは、dotTEST と同じマシンにインストールされていても、他のマシンにインストールされていても構いません。

また、Web アプリケーションからカバレッジを収集するには、ISS の管理コンソールで LoadUserProfile オプションに true が設定されている必要があります。

dottestcov ツール使用の前提条件

dottestcov ツールは以下の OS で実行できます。

- .NET Runtime 6.0 がインストールされた Linux

- 「OS」にリストされたバージョンの Windows

dottestcov ツールを使用するには、マシンに Java 11 以降がインストールされている必要があります。Oracle Java SE および OpenJDK がサポートされています。他のフリーやオープンソースの実装は、カバレッジ ツールの正常な動作を妨げる問題の原因になる可能性があります。JAVA_HOME 変数を設定し、システムの PATH に追加することを推奨します。

また、マシンに適切な .NET フレームワークがインストールされていることを確認します。

• .NET Runtime 6.0 (Linux で dottestcov を使用する場合)
• .NET Framework 4.7.2 または .NET Runtime 6.0 (Windows で dottestcov を使用する場合)

カバレッジの収集

スタンドアロン アプリケーションのカバレッジ収集については、「スタンドアロン アプリケーションのアプリケーション カバレッジ」を参照してください。

Web アプリケーションのカバレッジ収集については、「Web アプリケーションのアプリケーション カバレッジ」を参照してください。

ソース コードの情報を含む静的カバレッジ ファイルの生成

静的カバレッジ (ソース コードの情報を含む) と実行時カバレッジがマージされたレポートを作成するには、静的カバレッジ ファイルの生成が必要です。

ソリューションに対して次のテスト コンフィギュレーションを実行して静的カバレッジ ファイルを生成します。

dottestcli.exe -config "builtin://Collect Static Coverage" -solution SOLUTION_PATH

dottestcli のコンソール出力に静的カバレッジ データが保存された場所が表示されます。例:

Saving static coverage information into: 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\[FILE].xml

この静的カバレッジ ファイルは、dottestcli および dottestcov を使用して実行時カバレッジ データとマージし、DTP に送信できます。 

ソース コードの情報を含まない静的カバレッジ ファイルの生成

次のコマンドを実行して静的カバレッジ ファイルを生成します。

dottestcov.bat -app [dir] 

-app は、テスト対象アプリケーションのディレクトリへのパスを指定します。

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

CAM とともに dotTEST を使用する場合

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

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

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

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

CAM とともに dotTEST を使用する場合、3 つのタイプのカバレッジ レポートを生成できます。

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

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

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

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

     dottestcli.exe -runtimeCoverage [path] -staticCoverage [path] -publish 

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

4. dottestcov を使用する場合、以下のスイッチを指定して dottestcov を実行します。
   • -app: テスト対象アプリケーションのディレクトリまたはアーカイブ ファイルへのパスを指定します。
   • -runtime: CAM でダウンロードする実行時カバレッジへのパスを指定します (詳細については DTP のマニュアルの「Coverage Agent Manager (CAM)」セクションを参照)。単一のテスト セッションのカバレッジ情報を保存した個々の .data ファイルへのパスを指定することも、複数のテスト セッションの .data ファイルを含むフォルダーへのパスを指定することもできます。
   • -static: 静的カバレッジ ファイルへのパスを指定します (「ソース コードの情報を含む静的カバレッジ ファイルの生成」を参照)。

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

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

     dottestcov.bat -static [path to static_coverage.xml file] -runtime [path/dir]
     -publish -settings [path to .properties]

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

     dottestcov.bat -app [dir] -runtime [path/dir] -publish -settings [path to .properties]

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

     dottestcov.bat -runtime [path/dir] -publish -settings [path to .properties]

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

   dottestcov.bat merge -coverage <REPORT_FILE> -coverage <REPORT_FILE> [-coverage <REPORT_FILE>] [-report <REPORT_DIR>]

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

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

dottestcli を使用してカバレッジ スコープのカスタマイズ

デフォルトでは、 アプリケーション全体のカバレッジが計測されます。カバレッジ収集のスコープを狭くするには、-solution、-resource、-include および/または -exclude オプションを使用して、アプリケーションの特定の部分へのパスを指定します (静的カバレッジの生成については「テスト スコープの設定」を参照)。結果として、静的カバレッジ収集のカスタマイズされたスコープを含むスコープ設定ファイルが生成されます。

スコープ設定ファイルの内容を変更する必要はありません。しかし、大規模なアプリケーションのカバレッジを収集する場合は、実行時カバレッジ (テスト対象アプリケーションの操作中に収集されるカバレッジ) 収集のスコープを微調整するとよいでしょう。実行時カバレッジの収集をカスタマイズするには、scope.instumentation.txt ファイルを開き、カバレッジ データを収集しないアセンブリをアセンブリのリストから削除します。

カバレッジ エージェント REST クライアントでカバレッジ スコープをカスタマイズする

1. コマンド ラインにリソースへのパスを追加します (「ソース コードの情報を含む静的カバレッジ ファイルの生成」を参照)。例:

   dottestcli.exe -config "builtin://Collect Static Coverage" 
   -solution "C:\Devel\FooSolution\FooSolution.sln" 
   -resource "FooSolution/QuxProject" 
   -include "C:\Devel\FooSolution\src\QuxProject\**\*.cs" 
   -exclude "C:\Devel\FooSolution\src\QuxProject\**\tests\**\*.cs"

   静的カバレッジが生成され、スコープ設定ファイルにスコープ情報が保存されます。コンソール出力にはスコープ コンフィギュレーション ファイルの場所が表示されます。例:

   Saving static coverage scope configuration into: 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\scope.instrumentation.txt'

2. スタンドアロン アプリケーションの場合:
   1. runCamAgent.bat スクリプトを開きます (「Coverage Agent REST Client を使用したカバレッジの収集」を参照)。

   2. -Scope オプションを使用してスコープ設定ファイルへのパスをスクリプトに追加します。

      -scope 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\scope.instrumentation.txt

3. Web アプリケーションの場合: -scope オプションを使用してスコープ設定ファイルへのパスを Agent Client ツールに渡します (「テスト対象アプリケーション (AUT) へのカバレッジ エージェントのアタッチ」を参照)。

   agent_client.exe -scope 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\scope.instrumentation.txt'

カバレッジ エージェント REST クライアントを使用せずにカバレッジ スコープをカスタマイズする

カバレッジ エージェント REST クライアントなしでカバレッジ収集スコープをカスタマイズするには、アプリケーションを操作する前に手動で静的カバレッジを生成する必要があります。

1. Collect Static Coverage ビルトイン テスト コンフィギュレーションを実行して静的カバレッジ ファイルを生成し、-solution、-resource、-include および/または -exclude オプションを使用して、アプリケーションの特定の部分へのパスを指定します (詳細については「テスト スコープの設定」を参照)。コマンドは次のようになります。

   dottestcli.exe -config "builtin://Collect Static Coverage" 
   -solution "C:\Devel\FooSolution\FooSolution.sln" 
   -resource "FooSolution/QuxProject" 
   -include "C:\Devel\FooSolution\src\QuxProject\**\*.cs" 
   -exclude "C:\Devel\FooSolution\src\QuxProject\**\tests\**\*.cs"

   静的カバレッジが生成され、スコープ設定ファイルにスコープ情報が保存されます。コンソール出力にはスコープ コンフィギュレーション ファイルの場所が表示されます。例:

   Saving static coverage scope configuration into: 'C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\scope.instrumentation.txt'

2. monitorCoverage.bat スクリプトを開き、PARASOFT_PROFILING_ASM_LIST_PATH 環境変数がスコープ設定ファイルの場所を指すように設定します。例：

   SET PARASOFT_PROFILING_ASM_LIST_PATH=C:\Users\[USER]\Documents\Parasoft\dotTEST\Coverage\Static\scope.instrumentation.txt

3. monitorCoverage.bat スクリプトを実行してアプリケーションを実行します。
4. アプリケーションを操作してテストを実行した後、アプリケーションを終了します。

5. カバレッジ レポートを作成し、DTP にデータをアップロードするには、dottestcli または dottestcov を実行します。「カバレッジ レポートの作成と DTP へのデータのアップロード」の手順 3 および 4 を参照してください。

dottestcov を使用したカバレッジ スコープのカスタマイズ

デフォルトでは、 アプリケーション全体のカバレッジが計測されます。カバレッジ収集のスコープを狭くするには、次の操作を行います。

dottestcov.bat 
-include "C:\Devel\FooSolution\src\QuxProject\**\*.cs" 
-exclude "C:\Devel\FooSolution\src\QuxProject\**\tests\**\*.cs"
-app [dir] -runtime [path/dir] -publish -settings [path to .properties]

DTP でのカバレッジの参照

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

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

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

coverage

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

dottestcov.bat coverage [-app <APP_LOCATION> | -static <BASE_COVERAGE_REPORT_FILE>]
-runtime <RUNTIME_COVERAGE_LOCATION> [-report <REPORT_DIR>] [-deleteruntime]

-app <APP_LOCATION>

テスト対象アプリケーション (AUT) のディレクトリの場所を指定します。

-static <BASE_COVERAGE_REPORT_FILE>

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

-runtime <RUNTIME_COVERAGE_LOCATION>

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

-report <REPORT_DIR>

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

-deleteruntime

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

impacted

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

dottestcov.bat impacted -app <APP_LOCATION>
-baseline <BASELINE_COVERAGE_REPORT FILE> [-report <LST_FILE_DIR>]

-app <APP_LOCATION>

テスト対象アプリケーション (AUT) のディレクトリの場所を指定します。

-baseline <BASELINE_COVERAGE_REPORT_FILE>

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

-report <LST_FILE_DIR>

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

merge

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

dottestcov.bat merge -coverage <REPORT_FILE> -coverage <REPORT_FILE>
[-coverage <REPORT_FILE>] [-report <REPORT_DIR>]

-coverage <REPORT_FILE>

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

-report <REPORT_DIR>

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

help

dottestcov ヘルプを表示します。

その他の引数

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

dottestcov 終了コード

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