Action for Running MATLAB Tests

The Run MATLAB Tests GitHub® action enables you to run MATLAB® and Simulink® tests and generate artifacts such as JUnit test results and Cobertura code coverage reports. You can run tests and generate artifacts on a self-hosted or GitHub-hosted runner:

• To use a self-hosted runner, you must set up a computer with MATLAB (R2013b or later) as your runner. The action uses the topmost MATLAB version on the runner's system path.

• To use a GitHub-hosted runner, you must include the Set Up MATLAB action in your workflow to install MATLAB on the runner. Currently, this action is available only for public projects. It does not install transformation products, such as MATLAB Coder™ and MATLAB Compiler™.

Usage Examples

Use the Run MATLAB Tests action to automatically run tests authored using the MATLAB Unit Testing Framework or Simulink Test™. You can use this action with optional inputs to generate various test and coverage artifacts.

Run MATLAB Tests on Self-Hosted Runner

Use a self-hosted runner to automatically run the the tests in your MATLAB project.

name: Run MATLAB Tests on Self-Hosted Runner
on: [push]
jobs:
  my-job:
    name: Run MATLAB Tests
    runs-on: self-hosted
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Run tests
        uses: matlab-actions/run-tests@v0

Generate Test Artifacts on GitHub-Hosted Runner

Before you run tests and generate artifacts on a GitHub-hosted runner, first use the Set Up MATLAB action. The action installs your specified MATLAB release (R2020a or later) on a Linux® virtual machine. If you do not specify a release, the action installs the latest release of MATLAB.

For example, install the latest release of MATLAB on a GitHub-hosted runner, and then use the Run MATLAB Tests action to run the tests in your MATLAB project and generate a JUnit test results report and a Cobertura code coverage report.

name: Generate Test Artifacts on GitHub-Hosted Runner
on: [push]
jobs:
  my-job:
    name: Run MATLAB Tests and Generate Artifacts
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Install MATLAB
        uses: matlab-actions/setup-matlab@v0
      - name: Run tests and generate artifacts
        uses: matlab-actions/run-tests@v0
        with:
          test-results-junit: test-results/results.xml
          code-coverage-cobertura: code-coverage/coverage.xml

Run MATLAB Tests

When you define your workflow in the .github/workflows directory of your repository, specify the Run MATLAB Tests action as matlab-actions/run-tests@v0.

By default, MATLAB includes any files in your project that have a Test label. If your workflow 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 or in any of its subfolders.

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

Input	Description
source-folder	(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 source-folder and then generate a 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: source Example: source/folderA; source/folderB
select-by-folder	(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: test Example: test/folderA; test/folderB
select-by-tag	(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: Unit
test-results-pdf	(Optional) Path to write test results report in PDF format. Currently, this input is not supported on macOS platforms. Example: test-results/results.pdf
test-results-junit	(Optional) Path to write test results report in JUnit XML format. Example: test-results/results.xml
test-results-simulink-test	(Optional) Path to export Simulink Test Manager results in MLDATX format. This input requires a Simulink Test license, and is supported in MATLAB R2019a and later. Example: test-results/results.mldatx
code-coverage-cobertura	(Optional) Path to write code coverage report in Cobertura XML format. Example: code-coverage/coverage.xml
model-coverage-cobertura	(Optional) Path to write model coverage report in Cobertura XML format. This input requires a Simulink Coverage™ license, and is supported in MATLAB R2018b and later. Example: model-coverage/coverage.xml

Notes

When you use the Run MATLAB Tests action, you execute third-party code that is licensed under separate terms.

See Also

• Action for Running MATLAB Commands
• Action for Installing MATLAB on GitHub-Hosted Runner
• Continuous Integration with MATLAB and Simulink

Contact Us

If you have any questions or suggestions, please contact MathWorks® at [email protected].