MATLAB

This extension enables you to build and test your MATLAB® project as part of your pipeline. For example, you can automatically identify any code issues in your project, run tests and generate test and coverage artifacts, and package your files into a toolbox.

To run your pipeline using this extension, install the extension to your Azure® DevOps organization. To install the extension, click the Get it free button at the top of this page. You can use the extension with self-hosted or Microsoft®-hosted agents:

To use a self-hosted agent, you must set up a computer with MATLAB as your self-hosted agent and register the agent with Azure Pipelines. The agent uses the topmost MATLAB version on the system path to execute your pipeline.
To use a Microsoft-hosted agent, you must include a task in your pipeline to install MATLAB on the agent. Currently, this task is available only for public projects. It does not install transformation products, such as MATLAB Coder™ and MATLAB Compiler™.

Usage Examples

When you author your pipeline in a file named azure-pipelines.yml in the root of your repository, the extension provides you with four different tasks:

To run a MATLAB build, use the Run MATLAB Build task.
To run MATLAB and Simulink® tests and generate artifacts, use the Run MATLAB Tests task.
To run a MATLAB script, function, or statement, use the Run MATLAB Command task.
To install MATLAB on a Microsoft-hosted agent, use the Install MATLAB task.

Run a MATLAB Build

Use the Run MATLAB Build task to run a build using the MATLAB build tool. You can use this task to run the MATLAB build tasks specified in a file named buildfile.m in the root of your repository. To use the Run MATLAB Build task, you need MATLAB R2022b or a later release.

For example, author a pipeline to run a task named mytask as well as all the tasks on which it depends.

pool: myPool
steps:
  - task: RunMATLABBuild@0
    inputs:
      tasks: mytask

Run Tests in MATLAB Project

Use the Run MATLAB Tests task to run tests authored using the MATLAB unit testing framework or Simulink Test™. You can use this task to generate various test and coverage artifacts. You can then publish the artifacts to Azure Pipelines.

For example, author a pipeline to run the tests in your MATLAB project automatically, and then generate a PDF test results report, a JUnit test results report, and a Cobertura code coverage report at specified locations on the build agent. Use tasks to publish the generated artifacts to Azure Pipelines once the test run is complete.

pool: myPool
steps:
  - task: RunMATLABTests@0
    inputs:
      testResultsPDF: test-results/results.pdf
      testResultsJUnit: test-results/results.xml
      codeCoverageCobertura: code-coverage/coverage.xml
  - task: PublishBuildArtifacts@1
    inputs:
      pathToPublish: test-results/results.pdf
  - task: PublishTestResults@2
    condition: succeededOrFailed()
    inputs:
      testResultsFiles: test-results/results.xml
  - task: PublishCodeCoverageResults@1
    inputs:
      codeCoverageTool: Cobertura
      summaryFileLocation: code-coverage/coverage.xml

You can access the artifacts in the pipeline summary window:

To download the PDF test results report, follow the published link.
To view the JUnit test results report, open the Tests tab.
To view the Cobertura code coverage report, open the Code Coverage tab.

Run MATLAB Script

Use the Run MATLAB Command task to run MATLAB scripts, functions, and statements. You can use this task to flexibly customize your test run or add a step in MATLAB to your pipeline.

For example, author a pipeline to run the commands in a file named myscript.m.

pool: myPool
steps:
  - task: RunMATLABCommand@0
    inputs:
      command: myscript

Specify MATLAB in Pipeline

When you use the Run MATLAB Build, Run MATLAB Tests, or Run MATLAB Command task in your pipeline, the self-hosted agent uses the topmost MATLAB version on the system path. The pipeline fails if the agent cannot find any version of MATLAB on the path.

You can prepend your preferred version of MATLAB to the PATH environment variable of the agent. For example, prepend MATLAB R2023a to the path and use it to run your script.

pool: myPool
steps:
  - powershell: Write-Host '##vso[task.prependpath]C:\Program Files\MATLAB\R2023a\bin'  # Windows agent
# - bash: echo '##vso[task.prependpath]/usr/local/MATLAB/R2023a/bin'  # Linux agent
  - task: RunMATLABCommand@0
    inputs:
      command: myscript

Use MATLAB on Microsoft-Hosted Agent

Before you run MATLAB code or Simulink models on a Microsoft-hosted agent, first use the Install MATLAB task. The task installs your specified MATLAB release (R2020a or later) on a Linux® virtual machine. If you do not specify a release, the task installs the latest release of MATLAB.

For example, install MATLAB R2023a on a Microsoft-hosted agent, and then use the Run MATLAB Command task to run the commands in your script.

pool:
  vmImage: ubuntu-latest
steps:
  - task: InstallMATLAB@0
    inputs:
      release: R2023a
  - task: RunMATLABCommand@0
    inputs:
      command: myscript

Tasks

You can access the extension tasks and add them to your pipeline when you edit your pipeline in Azure DevOps.

tasks

Run MATLAB Build

Run a build using the MATLAB build tool. Starting in R2022b, you can use this task to run the MATLAB build tasks specified in a file named buildfile.m in the root of your repository. Specify the task in your pipeline YAML using the RunMATLABBuild key.

Argument	Description
`tasks`	(Optional) Space-separated list of MATLAB build tasks to run. If not specified, the task runs the default tasks in `buildfile.m` as well as all the tasks on which they depend. MATLAB exits with exit code 0 if the build runs successfully. Otherwise, MATLAB terminates with a nonzero exit code, which causes the pipeline to fail. Example: `tasks: test` Example: `tasks: compile test`
`startupOptions`	(Optional) MATLAB startup options. If you specify more than one option, use a space to separate them. For more information about startup options, see Commonly Used Startup Options. Using this argument to specify the `-batch` or `-r` option is not supported. Example: `startupOptions: -nojvm` Example: `startupOptions: -nojvm -logfile "output.log"

When you use this task, a file named buildfile.m must be in the project root directory. For more information about the build tool, see Create and Run Tasks Using Build Tool.

Run MATLAB Tests

Run the tests in a MATLAB project and generate artifacts. Specify the task in your pipeline YAML using the RunMATLABTests key.

By default, MATLAB includes any files in your project that have a Test label. If your pipeline does not use a MATLAB project, or if it uses a MATLAB release before R2019a, then MATLAB includes all tests in the root of your repository and in any of its subfolders.

The Run MATLAB Tests task lets you customize your tests using optional arguments. For example, you can add folders to the MATLAB search path, control which tests to run, and generate various artifacts.

Argument	Description
`sourceFolder`	(Optional) Location of the folder containing source code, relative to the project root folder. The specified folder and its subfolders are added to the top of the MATLAB search path. If you specify `sourceFolder` and then generate a code coverage report, MATLAB uses only the source code in the specified folder and its subfolders to generate the report. You can specify multiple folders using a colon-separated or semicolon-separated list. Example: `sourceFolder: source` Example: `sourceFolder: source/folderA; source/folderB`
`selectByFolder`	(Optional) Location of the folder used to select test suite elements, relative to the project root folder. To create a test suite, MATLAB uses only the tests in the specified folder and its subfolders. You can specify multiple folders using a colon-separated or semicolon-separated list. Example: `selectByFolder: test` Example: `selectByFolder: test/folderA; test/folderB`
`selectByTag`	(Optional) Test tag used to select test suite elements. To create a test suite, MATLAB uses only the test elements with the specified tag. Example: `selectByTag: Unit`
`strict`	(Optional) Whether to apply strict checks when running tests, specified as `false` or `true`. By default, the value is `false`. If you specify a value of `true`, the task generates a qualification failure whenever a test issues a warning.
`useParallel`	(Optional) Whether to run tests in parallel on a self-hosted agent, specified as `false` or `true`. By default, the value is `false` and tests run in serial. If the test runner configuration is suited for parallelization, you can specify a value of `true` to run tests in parallel. This argument requires a Parallel Computing Toolbox™ license and is supported only on self-hosted agents.
`outputDetail`	(Optional) Amount of event detail displayed for the test run, specified as `none`, `terse`, `concise`, `detailed`, or `verbose`. By default, the task displays failing and logged events at the `detailed` level and test run progress at the `concise` level.
`loggingLevel`	(Optional) Maximum verbosity level for logged diagnostics included for the test run, specified as `none`, `terse`, `concise`, `detailed`, or `verbose`. By default, the task includes diagnostics logged at the `terse` level.
`testResultsPDF`	(Optional) Path to write the test results report in PDF format. On macOS platforms, this argument is supported in MATLAB R2020b and later. Example: `testResultsPDF: test-results/results.pdf`
`testResultsJUnit`	(Optional) Path to write the test results report in JUnit XML format. Example: `testResultsJUnit: test-results/results.xml`
`testResultsSimulinkTest`	(Optional) Path to export Simulink Test Manager results in MLDATX format. This argument requires a Simulink Test license and is supported in MATLAB R2019a and later. Example: `testResultsSimulinkTest: test-results/results.mldatx`
`codeCoverageCobertura`	(Optional) Path to write the code coverage report in Cobertura XML format. Example: `codeCoverageCobertura: code-coverage/coverage.xml`
`modelCoverageCobertura`	(Optional) Path to write the model coverage report in Cobertura XML format. This argument requires a Simulink Coverage™ license and is supported in MATLAB R2018b and later. Example: `modelCoverageCobertura: model-coverage/coverage.xml`
`startupOptions`	(Optional) MATLAB startup options. If you specify more than one option, use a space to separate them. For more information about startup options, see Commonly Used Startup Options. Using this argument to specify the `-batch` or `-r` option is not supported. Example: `startupOptions: -nojvm` Example: `startupOptions: -nojvm -logfile "output.log"

Note: To customize the pretest state of the system, you can specify startup code that automatically executes before your tests run. For information on how to specify startup or shutdown files in a MATLAB project, see Automate Startup and Shutdown Tasks. If your pipeline does not use a MATLAB project, specify the commands you want executed at startup in a startup.m file instead, and save the file to the root of your repository. See startup for more information.

Run MATLAB Command

Execute a MATLAB script, function, or statement. Specify the task in your pipeline YAML using the RunMATLABCommand key.

Argument Description

command (Required) Script, function, or statement to execute. If the value of command is the name of a MATLAB script or function, do not specify the file extension. If you specify more than one script, function, or statement, use a comma or semicolon to separate them.
MATLAB exits with exit code 0 if the specified script, function, or statement executes successfully without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the pipeline to fail. To fail the pipeline in certain conditions, use the assert or error function.
Example: command: myscript
Example: command: results = runtests, assertSuccess(results);

startupOptions (Optional) MATLAB startup options. If you specify more than one option, use a space to separate them. For more information about startup options, see Commonly Used Startup Options.
Using this argument to specify the -batch or -r option is not supported.
Example: startupOptions: -nojvm
Example: startupOptions: -nojvm -logfile "output.log"

When you use this task, all of the required files must be on the MATLAB search path. If your script or function is not in the root of your repository, you can use the addpath, cd, or run function to put it on the path. For example, to run myscript.m in a folder named myfolder located in the root of the repository, you can specify command like this:

command: addpath("myfolder"), myscript

Install MATLAB

Install the specified MATLAB release on a Linux agent in the cloud. Specify the task in your pipeline YAML using the InstallMATLAB key.

Argument	Description
`release`	(Optional) MATLAB release to install. You can specify R2020a or a later release. If you do not specify `release`, the task installs the latest release of MATLAB. Example: `release: R2023a`

Currently, this task is available only for public projects. It does not install transformation products, such as MATLAB Coder and MATLAB Compiler.

Notes

The Run MATLAB Build task uses the -batch option to invoke the buildtool command. In addition, in MATLAB R2019a and later, the Run MATLAB Tests and Run MATLAB Command tasks use the -batch option to start MATLAB noninteractively. Preferences do not persist across different MATLAB sessions launched with the -batch option. To run code that requires the same preferences, use a single task.

Contact Us

If you have any questions or suggestions, please contact MathWorks® at continuous-integration@mathworks.com.

MathWorks