継続的インテグレーションシステムワークフローにおけるメトリクスのしきい値違反の修正

この例では次を使用します。

この例では、メトリクスダッシュボードをオープンソースツールである GitLab^® および Jenkins^® と連携させ、継続的インテグレーションシステムワークフローでモデルのテストおよび調整を行う方法を説明します。継続的インテグレーションとは、開発者が作業中のすべてのプロジェクトファイルのコピーを共有メインラインにマージさせる手法です。このワークフローによって時間が節約され、バージョンコントロールの維持、およびテストの自動化および標準化を通して品質が向上されます。

この例では、Airframe サンプルプロジェクト openExample('simulink/AirframeProjectExample')、および提供しなければならない以下のファイルを参照します。

メトリクスのしきい値を指定し、メトリクスダッシュボードをカスタマイズする MATLAB^® スクリプト。
メトリクスデータを収集し、メトリクスのしきい値違反がないかをチェックする MATLAB ユニットテスト。

この例では、MATLAB ユニットテストを実行してメトリクスのしきい値違反があるかを判別するために、Jenkins の継続的インテグレーションサーバーを使用します。Jenkins ではテスト結果がアーカイブされ、これをダウンロードしてローカルで調査できます。GitLab はオンラインの Git™ リポジトリマネージャーで、Jenkins と連携するよう設定できます。次の図は、Simulink^® Check™、GitLab、および Jenkins が継続的インテグレーションワークフローにおいてどのように連携するかを示します。

Workflow for continuous integration with GitLab and Jenkins

プロジェクトの設定

Airframe サンプルプロジェクト openExample('simulink/AirframeProjectExample') のファイルに加えて、以下の追加ファイルを提供しなければなりません。

プロジェクトのメトリクスデータを収集し、モデルファイルにメトリクスのしきい値違反が含まれていないことをチェックする MATLAB ユニットテスト。MATLAB ユニットテストの詳細については、スクリプトベースのユニットテストを参照してください。
メトリクスのしきい値を指定し、メトリクスダッシュボードをカスタマイズする MATLAB スクリプト。メトリクスダッシュボードのカスタマイズ方法の詳細については、メトリクスダッシュボードのレイアウトおよび機能のカスタマイズを参照してください。
メトリクスのしきい値の定義、カスタムメトリクスファミリの設定、メトリクスダッシュボードのレイアウトのカスタマイズを行う構成 XML ファイルをアクティブにする setup.m ファイル。この例では、setup.m スクリプトには以下のコードが含まれています。
```
function setup
    % refresh Model Advisor customizations
    Advisor.Manager.refresh_customizations();
        
    % set metric configuration with thresholds
    configFile = fullfile(pwd, 'config', 'MyConfiguration.xml');
    slmetric.config.setActiveConfiguration(configFile);
    
    uiconf = fullfile(pwd, 'config', 'MyDashboardConfiguration.xml');
    slmetric.dashboard.setActiveConfiguration(uiconf);
end
```
[プロジェクト] タブで、[起動とシャットダウン] をクリックします。[起動ファイル] フィールドで、setup.m ファイルを指定します。
モデルアドバイザーチェックをカスタマイズするためにモデルアドバイザー構成ファイルをアクティブにする sl_customization.m ファイル。独自のモデルアドバイザー構成の作成方法の詳細については、準拠メトリクスの設定を参照してください。

Jenkins ビルド時に実行される run スクリプト。この例では、次のコードが run.m ファイルに記述されています。

% script executed during Jenkins build
function run(IN_CI)
     if (IN_CI)
        jenkins_workspace = getenv('WORKSPACE');
        cd(jenkins_workspace);
    end

    % open the sl project
    slproj = simulinkproject(pwd);
    
    % execute tests
    runUnitTest();
    
    slproj.close();
    
    if IN_CI
        exit
    end
end

アクティブなメトリクス構成を既定の構成にリセットする cleanup.m ファイル。この例では、次のコードが cleanup.m ファイルスクリプトに記述されています。
```
function cleanup    
    rmpath(fullfile(pwd, 'data'));
    Advisor.Manager.refresh_customizations();

    % reset active metric configuration to default
    slmetric.config.setActiveConfiguration('');
    slmetric.dashboard.setActiveConfiguration('');
end
```
[プロジェクト] タブで、[起動とシャットダウン] をクリックします。[シャットダウンファイル] フィールドで、cleanup.m ファイルを指定します。
派生したアーティファクトが GitLab にチェックインされていないことを検証する .gitignore ファイル。次のコードが .gitignore ファイルに記述されています。
```
work/**
reports/**
*.asv
*.autosave
```

GitLab の設定

プロジェクトのソース管理のための GitLab プロジェクトを作成します。詳細については、https://docs.gitlab.com/ee/index.htmlを参照してください。

Git クライアントをインストールします。
分岐ワークローを設定します。GitLab で、メインブランチから、モデルファイルに変更を実装するための一時的なブランチを作成します。統合担当のエンジニアは Jenkins のテスト結果を使用して、一時的なブランチをメインブランチにマージすべきかを判断できます。詳細については、以下を参照してください。
https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows.
左側のサイドバーの [Settings]、[Repository] で、開発者がメインブランチに変更をマージする際にマージ要求の使用を強制することで、メインブランチを保護します。
[Integrations] ページの [Settings] で、Jenkins プロジェクトの URL に Web フックを追加します。この Web フックは、Jenkins サーバー上のビルドジョブをトリガーします。

Jenkins の設定

GitLab および TAP プラグインをインストールします。MATLAB ユニットテストは TAP プラグインを使用して結果を .tap ファイルにストリーミングします。Jenkins は .tap ファイルをインポートすることで、MATLAB から Jenkins ジョブへのテスト状態の通信を可能にします。

Jenkins プロジェクトを作成します。次の設定を指定します。

Jenkins プロジェクトで [Configure] をクリックします。
[General] タブで、プロジェクト名を指定します。
[Source Code Management] タブの [Repository URL] フィールドで、GitLab リポジトリの URL を指定します。
[Build Triggers] タブで、[Build when a change is pushed to GitLab] を選択します。
[Build Environment] セクションで、[Use MATLAB Version] を選択し、[MATLAB root] を指定します (例: C:\Program Files\MATLAB\R2022a)。
[Build] セクションで MATLAB を実行し、run スクリプトを呼び出します。run スクリプトによりプロジェクトが開き、すべてのユニットテストが実行されます。この例のプロジェクトでは、コードは次のとおりです。
```
matlab -nodisplay -r...
 "cd /var/lib/jenkins/workspace/'18b Metrics CI Demo'; run(true)"
```
詳細については、MATLAB プロジェクトと Jenkins を使用した継続的インテグレーションを参照してください。
[Post-build Actions] タブで、TAP 形式の結果が Jenkins にパブリッシュされるよう TAP プラグインを設定します。[Test Results] フィールドで reports/*.tap を指定します。[Files to archive] で reports/**,work/** を指定します。
TAP プラグインは、ジョブの結果を拡張して MATLAB ユニットテストからの詳細を表示します。Jenkins のアーカイブインフラストラクチャによって、Jenkins のビルド時に生成された派生アーティファクトが保存されます。

継続的インテグレーションワークフロー

プロジェクト、Jenkins、および GitLab の設定後、継続的インテグレーションワークフローに従います。

段階 1: 機能の開発

GitLab リポジトリのクローンをローカルに作成します。SVN リポジトリからのチェックアウトを参照してください。
Simulink で、ローカルの GitLab リポジトリに移動します。
機能ブランチを作成し、ファイルをフェッチし、チェックアウトします。Git でのブランチとファイルのマージとGit でのファイルのプル、プッシュおよびフェッチを参照してください。
プロジェクトファイルに必要な変更を加えます。
モデルをシミュレートし、シミュレーションデータインスペクターで出力を検証します。
MATLAB ユニットテストを実行します。詳細については、runtestsを参照してください。
変更したモデルを機能ブランチに追加およびコミットします。Git でのブランチとファイルのマージとGit でのファイルのプル、プッシュおよびフェッチを参照してください。
GitLab リポジトリに変更をプッシュします。Git でのブランチとファイルのマージとGit でのファイルのプル、プッシュおよびフェッチを参照してください。
GitLab で、マージ要求を作成します。ソースブランチとして機能ブランチを、メインブランチとしてターゲットブランチを選択します。[Compare branches and continue] をクリックします。
機能が完全に実装されていない場合、要求の先頭に WIP: という文字を追加して、マージ要求を作成中としてマークします。マージ要求が WIP: とマークされていない場合、作成後のビルドが直ちにトリガーされます。
[Create merge request] をクリックします。

段階 2: 継続的インテグレーションを使用した検定

WIP: という文字がマージ要求の先頭にない場合、プッシュコマンドによって Jenkins ビルドがトリガーされます。この例の Jenkins の設定の部分で、GitLab に変更をプッシュしたときにビルドを実行するよう Jenkins の設定を行いました。文字を削除するには、[Resolve WIP status] をクリックします。
Jenkins プロジェクトに移動します。[Build History] でビルドステータスを参照できます。
ビルドをクリックします。
[Tap Test Results] をクリックします。
この例では、MetricThresholdGateway.m ユニットテストは、3 つのメトリクスのしきい値を満たさなかったためにパスしませんでした。このデータを調査するには、データをローカルにダウンロードしなければなりません。