修复持续集成系统工作流中的度量阈值违规问题

此示例使用:

本示例展示了如何使用开源工具 GitLab^® 和 Jenkins^® 来使用度量仪表板，在持续集成系统工作流程中测试和改进您的模型。持续集成是将所有开发人员的工程文件工作副本合并到共享主线中的做法。该工作流程通过维护版本控制以及自动化和标准化测试，节省时间并提高质量。

本示例参考了 Airframe 示例工程 openExample('simulink/AirframeProjectExample')，您必须提供以下文件：

一个用于指定度量阈值并自定义度量仪表板的 MATLAB^® 脚本。
一个 MATLAB 单元测试，用于收集度量数据并检查是否存在度量阈值违规。

本示例使用 Jenkins 持续集成服务器运行 MATLAB 单元测试，以确定是否存在度量阈值违规。Jenkins 会将测试结果存档，供您下载并在本地进行分析。GitLab 是一个在线 Git™ 代码库管理器，您可以将其配置为与 Jenkins 协同工作。此图显示了 Simulink^® Check™、GitLab 和 Jenkins 在持续集成工作流中如何协同工作。

Workflow for continuous integration with GitLab and Jenkins

或者，您可以使用 CI/CD Automation for Simulink Check 支持包，在构建和验证过程中自动收集度量。有关详细信息，请参阅使用过程顾问自动执行和运行任务。

工程设置

除了 Airframe 示例工程 openExample('simulink/AirframeProjectExample') 中的文件外，您还必须提供以下附加文件：

一个 MATLAB 单元测试，用于收集工程的度量数据，并检查模型文件是否包含度量阈值违规。有关 MATLAB 单元测试的更多信息，请参阅基于脚本的单元测试。
一个用于指定度量阈值并自定义度量仪表板的 MATLAB 脚本。有关如何自定义度量仪表板的更多信息，请参阅自定义度量盘布局和功能。
一个 setup.m 文件，用于激活定义度量阈值、设置自定义度量系列和自定义度量仪表板布局的配置 XML 文件。在这个示例中，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 文件添加为工程的启动文件。在工程选项卡的环境部分中，点击设置。然后，在任务自动化部分的启动文件窗格中，点击添加，然后在浏览器中选择 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 文件添加为工程的关闭文件。在工程选项卡的环境部分中，点击设置。然后，在任务自动化部分的关闭文件窗格中，点击添加，然后在浏览器中选择 cleanup.m 文件。工程关闭时，关闭文件会自动运行。
.gitignore 文件用于验证派生工件是否未检入 GitLab。这段代码位于 .gitignore 文件中：
```
work/**
reports/**
*.asv
*.autosave
```

GitLab 设置

创建一个名为 GitLab 的工程，用于对工程进行源代码控制。有关详细信息，请参阅 GitLab 文档。

安装 Git 客户端。
建立分支工作流程。使用 GitLab，从主分支创建一个临时分支，用于实现对模型文件的更改。集成工程师可以使用 Jenkins 测试结果来决定是否将临时分支合并到主分支中。有关详细信息，请参阅：
Git 分支工作流。
在左侧边栏的设置 > 仓库下，通过强制要求开发人员在将更改合并到主分支时使用合并请求来保护主分支。
在设置下的集成页面上，添加一个 webhook 到您的 Jenkins 工程的 URL。此 webhook 会触发 Jenkins 服务器上的构建作业。

Jenkins 设置

安装 GitLab 和 TAP 插件。MATLAB 单元测试使用 TAP 插件将结果流式传输到 .tap 文件。为了实现从 MATLAB 到 Jenkins 作业的测试状态通信，Jenkins 导入了 .tap 文件。

创建一个 Jenkins 工程。请指定以下配置：

在您的 Jenkins 工程中，点击配置。
在常规选项卡上，指定工程名称。
在源代码管理选项卡的仓库 URL 字段中，指定您的 GitLab 仓库的 URL。
在构建触发器选项卡上，选择当更改推送到 GitLab 时构建。
在构建环境部分，选择使用 MATLAB 版本，并指定 MATLAB 根，例如 C:\Program Files\MATLAB\R2022a。
在编译部分，执行 MATLAB 来调用 run 脚本。run 脚本打开工程并运行所有单元测试。本示例中的工程代码如下：
```
matlab -nodisplay -r...
 "cd /var/lib/jenkins/workspace/'18b Metrics CI Demo'; run(true)"
```
有关详细信息，请参阅Reduce Test Runtime on CI Servers。
在编译后操作选项卡中，配置 TAP 插件以将 TAP 结果发布到 Jenkins。在测试结果字段中，指定 reports/*.tap。对于要存档的文件，请指定 reports/**,work/**。
TAP 插件会在作业的扩展结果中显示 MATLAB 单元测试的详细信息。Jenkins 归档基础架构保存在 Jenkins 构建过程中生成的衍生工件。

持续集成工作流程

设置好工程 Jenkins 和 GitLab 后，请按照持续集成工作流程进行操作。

第一阶段：功能开发

创建 GitLab 仓库的本地克隆。请参阅在 MATLAB 中克隆 Git 存储库。
在 Simulink 中，导航到本地 GitLab 存储库。
创建功能分支并获取和检出文件。请参阅Create, Manage, and Merge Git Branches和Push to Git Remote。
对工程文件进行必要的修改。
在仿真数据检查器中仿真模型并验证输出结果。
运行 MATLAB 单元测试。有关详细信息，请参阅runtests。
将修改后的模型添加到特性分支并提交。请参阅 Review and Commit Modified Files to Git。
将更改推送至 GitLab 存储库。请参阅 Push to Git Remote。
在 GitLab 中，创建一个合并请求。选择功能分支作为源分支，目标分支作为主分支。点击比较分支并继续。
如果该功能尚未完全实现，请在合并请求的开头添加 WIP: 字样，将合并请求标记为正在进行中的工作。如果合并请求未标记为 WIP:，则会在创建后立即触发构建。
点击创建合并请求。

第二阶段：通过持续集成进行资格认证

如果合并请求的开头没有 WIP: 字样，则推送命令会触发 Jenkins 构建。在本示例的 Jenkins 设置部分中，您配置了 Jenkins，以便在将更改推送到 GitLab 时执行构建。要删除字母，点击解析 WIP 状态。
导航至 Jenkins 工程。在构建历史记录中，您可以查看构建状态。
点击“构建”。
点击 Tap 测试结果。
在这个示例中，MetricThresholdGateway.m 单元测试有三个度量未通过，因为这些度量未达到阈值。要分析这些数据，您必须将数据下载到本地。

第三阶段：在本地调查质量问题

将存档结果下载到本地 Git 存储库工作区。
解压缩下载的文件。将 reports/ 和 work/ 文件夹复制到本地存储库中的相应文件夹中。
要查看结果，请打开工程和度量仪表板。
为了解决测试失败问题，请对模型进行必要的更新。将更改推送到 GitLab 中的特性分支。
集成工程师可以使用 Jenkins 测试结果来决定何时可以将临时分支合并到主分支中。

另请参阅

slmetric.config.setActiveConfiguration | slmetric.dashboard.setActiveConfiguration

主题

外部网站

https://www.mathworks.com/company/newsletters/articles/continuous-integration-for-verification-of-simulink-models.html