はじめに

dotTEST を使用すると、スタンドアロンまたは Web アプリケーションに対して手動または自動での機能テストを実行しながらマネージド コードのカバレッジ データをモニターおよび収集できます。

典型的なワークフローでは、dotTEST は IIS サーバーにデプロイされた Web アプリケーションのカバレッジを収集します。IIS サーバー上にデプロイされた実行中の Web アプリケーション サーバーで手動または自動での機能テストを実行し、マネージド コードのカバレッジ データを収集できます。.NET Web アプリケーションがサポートされています。別の方法として、デスクトップ アプリケーションとしてアプリケーションを実行することもできます (たとえば dotnet.exe を使用したり、.NET アプリケーションであればアプリケーション実行ファイルを使用したりして)。

専用の dotTEST アプリケーション カバレッジ UI またはコマンド ラインを使用してカバレッジを収集できます。カバレッジ データおよびテスト結果を DTP サーバーにレポートし、データをマージして関連付けることができます。アプリケーション カバレッジ情報を DTP のカバレッジ エクスプローラーに表示し、アプリケーションがどの程度テストされたかや、テストの品質を知ることができます。詳細については、DTP ユーザー ガイドの「カバレッジ エクスプローラー」を参照してください。

プロセスの概要

dotTEST には、カバレッジ エンジン (agent_client.exe) の REST クライアント API を使用してアプリケーションのカバレッジ収集を可能にするカバレッジ エージェントというコンポーネントが付属しています。カバレッジ エージェントを利用すると、スタンドアロン アプリケーションおよび Web アプリケーションの実行中にマネージド コードのカバレッジ情報を収集できます。agent_client.exe を実行すると UI が起動します。あるいは、コマンドライン オプションを使用して情報を指定することもできます。

dotTEST では、ローカル カバレッジ レポートを生成して DTP に結果をアップロードできます。

agent_client.exe ツールの機能を利用すると、テスト対象アプリケーションのエントリ ポイントおよび dotnet.exe へのパスを指定することで、 .NET Web アプリケーションのカバレッジを収集できます。

dotTEST カバレッジ エージェントは、テスト対象アプリケーション (AUT) にアタッチされ、AUT の実行されたコードをモニターします。AUT にカバレッジ エージェントをアタッチすると、REST API が公開され、テストおよびテスト セッションの開始および終了をマークできるようになります。テスト実行時には、カバレッジ エージェントとのやりとりが動的カバレッジ マップに書き込まれます。このマップには、実行されたコード行を示すマーカーが記録されます。

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

.cs または .vb 以外のファイルに対しては、動的カバレッジはレポートされません。

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

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

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

カバレッジ レポートを作成し、DTP にアップロードするには、dottestcov または dottestcli を使用します。dottesctcov は、カバレッジ専用のツールであり、カバレッジ レポートの生成に関してより多くのオプションがあります。「カバレッジ レポートの作成と DTP へのデータのアップロード」を参照してください。dottestcov.bat ファイルは、<INSTALL_DIR>\integration\coverage\dottestcov ディレクトリにあります。

Agent_client.exe および dottestcov は dotTEST のインストール ディレクトリの外にコピーして、独立して使用できるスタンドアロン ツールです。 そのため、テスト フローとの統合が容易です。エージェント クライアント コマンド ライン オプションの詳細は、「エージェント クライアントのコマンド ライン オプション」を参照してください。dottestcov コマンド ライン オプションの詳細は、「dottestcov のコマンド ライン オプション」を参照してください。

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

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

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

ソース管理システムを使用する場合、適切にソース管理システムを設定します。「ソース管理システムの設定」を参照してください。

また、IIS サーバーにデプロイされた Web アプリケーションの場合は次の条件があります。

dottestcov ツール使用の前提条件

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

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

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

UI を使用したカバレッジ収集のワークフロー

IIS Web アプリケーションのカバレッジ収集

設定済みの IIS サーバー上にホストされたすべての Web アプリケーションのカバレッジを収集する場合、次の操作を行います。 

  1. dotTEST アプリケーション カバレッジ UI を起動するには、コンソールで次のコマンド ラインを使用し、エージェント クライアントを実行します。
    agent_client.exe
  2. [IIS Web アプリケーション] を選択し、[次へ] をクリックします。
  3. (任意) 次のオプションを設定します。
  4. [次へ] をクリックします。IIS サーバーにホストされたすべてのアプリケーションのカバレッジが収集されます。
  5. (任意): 指定されたアプリケーションでテストを実行し、カバレッジを参照します。[アプリケーションの開始] をクリックし、指定されたアプリケーションを実行し、テストを実施します。
  6. [カバレッジ エージェントの停止] をクリックし、すべてのアプリケーションからのカバレッジ収集を停止します。
  7. [終了] をクリックしてアプリケーション カバレッジ UI を閉じるか、[新規セッション] をクリックして新しいカバレッジ収集セッションを開始します。

スタンドアロン アプリケーションおよび Web アプリケーションのカバレッジ収集

特定のスタンドアロン アプリケーションまたは Web アプリケーションのカバレッジを収集するには、次の操作を行います。 

  1. dotTEST アプリケーション カバレッジ UI を起動するには、コンソールで次のコマンド ラインを使用し、エージェント クライアントを実行します。
    agent_client.exe
  2. [デスクトップ アプリケーション] を選択し、[次へ] をクリックします。
  3. 次のオプションを設定します。
  4. [次へ] をクリックします。指定したアプリケーションが実行され、カバレッジが収集されます。アプリケーションでテストを実施します。
  5. [カバレッジ エージェントの停止] をクリックし、アプリケーションからのカバレッジ収集を停止します。
  6. [終了] をクリックしてアプリケーション カバレッジ UI を閉じるか、[新規セッション] をクリックして新しいカバレッジ収集セッションを開始します。

コマンド ライン を使用したカバレッジ収集のワークフロー

CLI を使用してカバレッジを収集するには、次の操作を行います。

  1. (任意) ソース コードの情報を含む静的カバレッジ ファイルを生成します。静的カバレッジ ファイルには、ユーザー クラス、メソッド、行などの情報が記録されます。詳細は「ソース コードの情報を含む静的カバレッジ ファイルの生成」で説明されています。
  2. AUT にカバレッジ エージェントをアタッチします。「テスト対象アプリケーション (AUT) へのカバレッジ エージェントのアタッチ」を参照してください。
  3. CLI を使用してカバレッジを収集するか、テストを実行してカバレッジを収集します。詳細については「UI を使用したカバレッジの収集」または「テストを実行して実行時カバレッジを収集する」を参照してください。
  4. カバレッジ収集を終了します。詳細については「実行時カバレッジ データ収集の停止」を参照してください。

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

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

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

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 は、テスト対象アプリケーションのディレクトリへのパスを指定します。

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

  1. IIS がインストールされ、アプリケーションがデプロイされているマシンに <INSTALLATION_DIR>\integration\coverage\agent ディレクトリをコピーします。
    エージェントをホーム ディレクトリ (%USERPROFILE% ディレクトリ) にデプロイすることは、We ベースのアプリケーションからのカバレッジ収集を妨げる可能性があるため、推奨されません。
  2. 管理者としてコンソールを実行します。

  3. このマシンで Agent Client ツールを実行し、IIS 内での実行時カバレッジ収集を有効にします。

    agent_client.exe

    Agent Client に追加のオプション指定が必要な場合があります。「エージェント クライアントのコマンド ライン オプション」を参照してください。

    Agent Client は Web サーバー (IIS) の環境を初期化し、サービスのように振る舞い、ユーザーがテストを実行してカバレッジを収集することを可能にします。次のメッセージが表示されている間、サービスが待機し、コマンドを受け付けます。  

    Write 'exit' and hit Enter to close agent_client

    テスト対象 Web サイトまたはアプリケーションがまだロードされていないときでも、セッションおよびテストを開始できることに注意してください。

  4. このマシンのファイアウォールの設定で、ポート 8050 (カバレッジ エージェントのデフォルトのポート) での HTTP トラフィックが許可されていることを確認します。デフォルトのポートを使用できない場合は、カバレッジ エージェントのポート番号を変更できます。
  5. Web サイトまたは Web アプリケーションを開きます。

  6. 次のアドレスに移動し、カバレッジ エージェントのステータスを確認します。 http://host:8050/status
    次のレスポンスが返されるはずです。

    {"session":null,"test":null}

HTTPS 経由での Coverage Agent への接続

デフォルトでは、カバレッジ エージェントは HTTP プロトコル経由で利用できます。HTTPS 経由で接続するには、カバレッジ エージェントが使用するポートに SSL証明書をバインドする必要があります。それには、以下のいずれかの操作を行います。

自己署名証明書を使用するには、-skipvalidation オプションを追加する必要があります。

PFX または PKCS12 フォーマットの SSL 証明書を利用できます。

SSL 証明書の削除

デフォルトでは、Agent Client はカバレッジ エージェント用に設定された証明書を自動的に処理します。手動で証明書を削除するには、Certmgr.exe ツールを起動し、Personal> Certificates に格納された証明書を削除します。

-unregister スイッチを指定して Agent Client でカバレッジ サービス ポートの登録を解除する場合、-useSsl および -removeCertificate スイッチを追加して SSL 証明書を削除する必要があります。

agent_client.exe -unregister -port 8050 -useSsl -removeCertificate

こうすると、ポート番号から SSL 証明書が削除されます。これで、ストレージから手動で証明書を削除できるようになりました。

CLI を使用したカバレッジの収集

CLI を使用してカバレッジを収集するには、専用のオプションとともに agent_client.exe を実行して、アプリケーション カバレッジの収集に必要な情報を指定します。

IIS アプリケーションの場合: 

agent_client.exe -port 8050

デスクトップ アプリケーションの場合:

agent_client.exe -app [path] -workingDir [path] -appArgs [arguments]

複数ユーザーからのカバレッジ収集

1 つの Web アプリケーションに同時にアクセスする複数のユーザーのカバレッジ情報を収集できます。それには、-multiuser スイッチを指定して Agent Client を起動します。

agent_client.exe -multiuser

Agent Client のアイドル タイムアウト値の変更

デフォルトでは、Agent Client のアプリケーション プール プロセスは 20 分のアイドル タイムが経過するとシャットダウンしますが、このことがテスト セッションに悪影響を与える可能性があります。デフォルトのアイドル タイム値を変更し、シャットダウンを防ぐことによって、アプリケーションを操作するユーザーがテスト セッション中に予期しないサーバーの停止および再起動に遭遇しないようにできます。

  1. Internet Information Services (IIS) Manager を開始します。
  2. Application Pools ノードを開きます。
  3. Web アプリケーションが使用するプールを選択します。
  4. [Actions] パネルの [Advanced Settings] をクリックします。
  5. [Process Model ] セクションで [Idle Time-out (minutes)] の設定をテストに適した値に変更します。

テストを実行して実行時カバレッジを収集する

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

実行時カバレッジ データ収集の停止

実行時カバレッジ データの収集を停止するには、以下のいずれかの操作を行います。

  1. コンソールに次のメッセージが表示されている状態で exit と入力し、エージェント クライアントを停止します。

    Write 'exit' and hit Enter to close agent_client

  2. ブラウザーに次の URL を入力することで、サービスにリクエストを送信します: http://host:port/shutdown

すべてのセッションが終了している場合にだけエージェント クライアントが停止します。サービスを停止すると、アプリケーション カバレッジが収集されなくなるため、カバレッジを収集するテストが実行されている間は、常にエージェント クライアントを実行しておくことが重要です。

エージェント クライアントの終了時にエラーが発生し、Web サーバー環境のクリーンアップが行われなかった場合、-uninitialize パラメーターを指定してエージェント クライアントを実行することで、元の Web サーバー環境および設定を復元してください。 

agent_client.exe -uninitialize

既知の制限事項

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 へのデータのアップロード

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

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

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

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

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

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

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

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

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

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

IIS でコンパイルされた Web プロジェクトでは、アプリケーション カバレッジ スコープ ファイルを使用できません。これは、IIS コンパイルのターゲット アセンブリの名前が事前に決まっていないからです。カバレッジの収集が開始される前に、IIS によってロードされるアセンブリの名前がわかる場合は、スコープ ファイルを使用できます。

カバレッジ収集のスコープを狭くするには:次の操作を行います。

  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. -scope オプションを使用してスコープ設定ファイルへのパスをスクリプトに追加します (「テスト対象アプリケーション (AUT) へのカバレッジ エージェントのアタッチ」を参照)。

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

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

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

dottestcov.bat 
-include "MyAssembly.dll/*"
-exclude "MyAssembly.dll/packageA.*"
-app [dir] -runtime [path/dir] -publish -settings [path to .properties]

DTP でのカバレッジの参照

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