Continuous Integration Using MATLAB Projects and Jenkins

This example shows how to set up a MATLAB^® project for continuous integration and run a suite of MATLAB unit tests with Jenkins^®.

Configure a freestyle Jenkins project to access a MATLAB project hosted in a remote repository.
Add a build step to the Jenkins project to run all project tests.
Add a build step to the Jenkins project to run tests impacted by the latest change.
Add a post-build step to archive and reuse the dependency analysis cache file to reduce test suite runtime when qualifying a change.
Build the project and examine the test results.

Note

You can use different continuous integration (CI) platforms such as Azure^® DevOps, Bamboo^®, and GitHub^® Actions to run MATLAB code and Simulink^® models as part of your automated workflow. For a list of supported CI platforms, see Continuous Integration with MATLAB on CI Platforms.

Prerequisites

Before you start:

Install Jenkins. See https://www.jenkins.io/doc/book/installing/.
Install the MATLAB plugin for Jenkins:
1. From within Jenkins, on the Manage Jenkins page, click Manage Plugins.
2. On the Available tab, search for "MATLAB".
3. Download and install the plugin.
For more information, see Plugin Configuration Guide (GitHub).
Put your MATLAB project under Git™ source control and share on GitHub:
1. With the project loaded, on the Project tab, select Share > GitHub.
2. Enter your GitHub user name and personal access token, and edit the name for the new repository. Click Create.
Your MATLAB project is publicly available on GitHub. You can make your repository private by changing the settings in your GitHub account.

Set Up MATLAB Project for Continuous Integration in Jenkins

Create a new Jenkins project:

In the Jenkins interface, in the left pane, click New Item.
Enter a name for your Jenkins project, select Freestyle project, and click OK.

Configure your Jenkins project. In the left pane, click Configure.

In the Source Code Management section, specify the Repository URL that hosts your MATLAB project. For example, https://github.com/username/Airframe-Example.git.
In the Build Triggers section, you can specify when and how frequently you want to run builds. For example, to build your project after every GitHub push notification, select GitHub hook trigger for GITScm polling.
In the Build Environment section, select Use MATLAB Version and specify the MATLAB root, for example, C:\Program Files\MATLAB\R2022a.
To specify the test suite you want to run, in the Build section, select Add Build Step > Run MATLAB Tests. To run all tests stored in a specific folder, select By folder name and specify the test folder name. For example, tests. By default, Run MATLAB Tests runs all test files in the MATLAB project.
Alternatively, use the Run MATLAB Command step to run all tests using the MATLAB project label. In the Build section, select Add Build Step > Run MATLAB Command. In the Command field, enter this script.
```
proj = openProject("ProjectAirframeExample.prj");
testFiles = findFiles(proj,Label="Test");
runtests(testFiles)
```
To save the Jenkins project configuration, click Save.
To build your project and run all tests, click Build Now. Jenkins triggers a build, assigns it a number under Build History, and runs the build. If the build is successful, a blue circle icon appears next to the build number. If the build fails, a red circle icon appears. For more information, see Run MATLAB Tests on Jenkins Server (GitHub).

Reduce Test Runtime Using Dependency Cache and Impact Analysis

You can share the dependency cache file to reduce qualification time on local machines and CI servers. Using a prepopulated dependency cache file, you can perform an incremental impact analysis and run only the tests impacted by a change.

Set MATLAB Project Dependency Cache File

To set the project dependency cache file, in MATLAB, on the Project tab, in the Environment section, click Details. In Dependency cache file, browse to and specify a GraphML file. If the cache file does not exist, the project creates it for you when you run a dependency analysis.

Alternatively, you can create and set the project dependency cache programmatically.

proj = currentProject;
proj.DependencyCacheFile = "work/dependencyanalysis/projectcache.graphml";

Commit and push the change to make it available on GitHub and Jenkins. On the Project tab, in the Source Control section, click Commit, then click Push.

Generate and Archive Dependency Cache File on Jenkins

To configure your Jenkins project to generate and archive the dependency analysis cache file, on your Jenkins project configuration page:

Add a new build step. In the Build section, select Add Build Step > Run MATLAB Command. In the Command field, enter this script.
```
proj = openProject("ProjectAirframeExample.prj");
updateDependencies(proj);
```
This script launches MATLAB, loads your MATLAB project, runs a dependency analysis, and caches the results in the dependency cache file.
In the Post-build Actions section, under Archive the artifacts, in the Files to archive field, enter: work/dependencyanalysis/*.graphml. After the build, Jenkins copies the GraphML file from the Jenkins workspace to the build archive location.

Share Cache for Faster Dependency Analysis on Local Machines

If you configured Jenkins to perform frequent builds, team members can sync their working copy based on the last successful build. Team members check out the design changes from Git, retrieve the associated dependency cache file from the build archive area, and place the GraphML file in the specified location.

On a local machine, MATLAB projects use the prepopulated dependency cache file to run an incremental dependency analysis. This action saves time for workflows running a dependency analysis in the background, such as automatic renaming, sharing a project, and performing an impact analysis.

Run Impacted Tests and Reduce Qualification Runtime on CI Servers

On a CI server, for large projects, you can use the prepopulated dependency cache to perform an incremental impact analysis. You can configure your project build to run only impacted tests and significantly reduce runtime when qualifying a code change.

To configure your Jenkins project to only run tests impacted by the last change, in the Build section, select Add Build Step > Run MATLAB Command. In the Command field, enter this script.

proj = openProject("ProjectAirframeExample.prj");
[status,modifiedFiles] = system("git diff --name-only HEAD~1..HEAD :!resources");
updateDependencies(proj);
modifiedFiles = split(modifiedFiles);
modifiedFiles = modifiedFiles(1:(end-1))';
impactedFiles = listImpactedFiles(proj,modifiedFiles);
testFiles = findFiles(proj,Label="Test");
impactedTests = intersect(testFiles,impactedFiles);
 
runtests(impactedTests)

This script launches MATLAB, loads your MATLAB project, retrieves the list of files that changed in the last commit, runs an impact analysis to determine the subset of tests you need to run to qualify the change, and runs the list of impacted tests.

Enhance Workflow

You can apply several additional steps to improve the workflow and make building and qualifying the project faster.

Similar to the GraphML file, you also can generate and archive SLXC files to reuse and reduce simulation time. For more information, see Share Simulink Cache Files for Faster Simulation.
To easily manage SLXC and GraphML files from multiple Jenkins builds, you can use a database or a repository management tool such as JFrog Artifactory. For more information, see https://jfrog.com/help/r/get-started-with-the-jfrog-platform/jfrog-artifactory.
You can set up a script to automatically retrieve the associated dependency cache file and place a copy in your working copy.