GitLabによるコードカバレッジの可視化

GitLabのような継続的インテグレーション(CI)/継続的開発(CD)ツールは、コードカバレッジの結果を後処理する機能を提供しています。たとえば、GitLab CI/CDを使用すると、お気に入りのテストツールやカバレッジ解析ツールのテストカバレッジ情報を収集し、マージリクエスト（MR）のファイル差分ビュー内で可視化することができます。これにより、どの行がテストでカバーされているのか、MRをマージする前にどの行がまだカバレッジが必要なのかを確認することができます。GitLabでは、コードカバレッジ解析レポートを作成するための入力として、Coberturaフォーマットが必要とします。

Coberturaレポートは、テストケースでカバーされているコードの割合に関する情報を含む.xmlファイルです。これはテストカバレッジが不足しているコードの部分を見つけることに役立ちます。このフォーマットは元々Java用に開発されましたが、他言語の多くのカバレッジ解析フレームワークには、下記のようなサポートを追加するためのプラグインがあります：

simplecov-cobertura (Ruby)

gocover-cobertura (Golang)

他カバレッジ解析フレームワークでは、すぐに使用できるフォーマットをサポートしています。例えば：

Istanbul (JavaScript)

Coverage.py (Python)

Riviera-PROでは、ACDB(Aldec Code Coverage Data Base)ファイルを生成します。そのため、Riviera-PROのユーザは、GitLabのビジュアルカバレッジ解析機能を利用するために、ACDBレポートをCobertura xmlフォーマットに変換する必要があります。ACDBをCoberturaに変換するPythonスクリプトを用意しました。このアプリケーションノートでは、ACDBをCobertura形式に変換する方法に関する詳細情報を提供するために用意成されています。

ACDBをCobertura XMLに変換する方法

このアプリケーションノートを実行するには、GitLabで新しいプロジェクトを作成し、gitlab.ci.ymlファイルを作成する必要があります。GitLabとRiviera-PROを使用してプロジェクトを作成する方法については、別のアプリケーションノートで紹介しています。

GitLabはCI/CDのアーティファクトレポート機能を使用してカバレッジ情報を収集します。ワイルドカードパスを含め、1つ以上の収集するカバレッジレポートを指定できます。この変更は、.ymlファイルに適用する必要があります。カバレッジ解析が機能するためには、適切にフォーマットされたCobertura XMLレポートをartifacts:reports:coberturaに提供する必要があります。以下に、このプロジェクトの.ymlファイルの内容を示します。

stages:         #List of stages for jobs, and their order of execution 
   -build
build-job:      # This job runs in the build stage, which runs first. 
  stage: build
  tags:
  - ci
  artifacts:
  reports:
    cobertura: cobertura.xml
  script:
    - echo "Compiling the code..."
    - vsim -c -do sr c/runme_verilog.do
    - python3 ucdb2cobertura.py -i ucdb.xml -o cobertura.xml
    - echo "Compile complete."

ホストマシンのシェル環境を利用して "vsim "コマンドを呼び出し、"runme_verilog.do "ファイルを実行します。このプロジェクトでは、独自のrun.doファイルを使用することができます。以下のコードは、このアプリケーションノートで使用している.doファイルを示しています。

alib work
adel -all
alog -coverage sb -coverage_options count \
  src/verilog/board.v \
  src/verilog/tbscenario1.v src/verilog/tbscenario2.v \
  src/verilog/tbscenario3.v src/verilog/tbscenario4.v
asim -acdb scenario1
run -all 
acdb save -file cov/out1/out1.acdb
endsim
asim -acdb scenario2
run -all
acdb save -file cov/out2/out2.acdb
endsim
acdb merge -i cov/out1/out1.acdb -path /scenario1/UUT -i
cov/out2/out2.acdb -path /scenario2/UUT -o
cov/aggregate/aggregate.acdb
asim -acdb scenario3
run -all 
acdb save -file cov/out3/out3.acdb
endsim

acdb merge -i cov/out3/out3.acdb -path /scenario3/UUT -i 
cov/aggregate/aggregate.acdb -path / -o cov/aggregate/aggregate.acdb
asim -acdb scenario4
run -all
acdb save -file cov/out4/out4.acdb
endsim
acdb merge -i cov/out4/out4.acdb -path /scenario4/UUT -i
cov/aggregate/aggregate.acdb -path / -o cov/aggregate/aggregate.acdb
acdb2xml -i cov/aggregate/aggregate.acdb -o ucdb.xml
quit

.doファイルの実行後、Riviera-PROはGitLabリポジトリからプロジェクトのソースファイルを読み込み、コンパイルとシミュレーションを実行します。シミュレーションでは4つの異なるシナリオを実行し、.acdbレポートを保存します。その後に"acdb merge"コマンドで.acdbファイルをマージします。次に"acdb2xml"コマンドを使用して、acdbレポートを.xmlフォーマットに変換し、Pythonスクリプトで使用するucdb.xmlフォーマットの出力を生成します。

シミュレーションが完了すると、ucdb2cobertura.pyスクリプトは、ホストマシンにインストールされているpython3ツールを使用して実行を開始します。python3のパスをユーザー変数とシステム変数の両方で正しく設定し、このスクリプトを呼び出せるようにしておくことが重要です。何らかの理由でこのコマンドが認識されない場合は、インストールフォルダ内のexeファイルへのパスを使用する必要があります：

C:\path-to-python3-installation\python ucdb2cobertura.py -i ucdb.xml -o cobertura.xml

Pythonコンバータの仕組み

Pythonスクリプトは、Riviera-PROで生成されたucdb.xmlファイルを入力として取得します。出力としてcobertura.xmlフォーマットを生成するためにucdb.xmlファイルを解析します。下の画像は、ucdb2cobertura.pyスクリプトの一部を示しています。このスクリプトは無料で、アルデックのサポートチームに依頼することができます。

アルデックは、Pythonのソースファイルを公開しました。アルデックのGithubからダウンロードできます。

参考資料：