Action for Running MATLAB Tests

The Run MATLAB Tests action enables you to run MATLAB® and Simulink® tests and generate test and coverage artifacts on a self-hosted or GitHub®-hosted runner:

• To use a self-hosted runner, you must set up a computer with MATLAB as your self-hosted runner and register the runner with GitHub Actions. The runner uses the topmost MATLAB release on the system path to execute your workflow.
• To use a GitHub-hosted runner, you must include the Setup MATLAB action in your workflow to set up your preferred MATLAB release (R2021a or later) on the runner.

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 Tests in MATLAB Project

On a self-hosted runner, run the tests in your MATLAB project. To run the tests, specify the Run MATLAB Tests action in your workflow.

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

Generate Test and Coverage Artifacts

Using the latest release of MATLAB on a GitHub-hosted runner, run the tests in your MATLAB project and generate test results in JUnit-style XML format and code coverage results in Cobertura XML format. To set up the latest release of MATLAB on the runner, specify the Setup MATLAB action in your workflow. To run the tests and generate the artifacts, specify the Run MATLAB Tests action.

name: Generate Test and Coverage Artifacts
on: [push]
jobs:
  my-job:
    name: Run MATLAB Tests
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2
      - name: Run tests
        uses: matlab-actions/run-tests@v2
        with:
          test-results-junit: test-results/results.xml
          code-coverage-cobertura: code-coverage/coverage.xml

Run Tests in Parallel

Run your MATLAB and Simulink tests in parallel (requires Parallel Computing Toolbox™) using the latest release of the required products on a GitHub-hosted runner. To set up the latest release of MATLAB, Simulink, Simulink Test, and Parallel Computing Toolbox on the runner, specify the Setup MATLAB action with its products input in your workflow. To run the tests in parallel, specify the Run MATLAB Tests action with its use-parallel input specified as true.

name: Run Tests in Parallel
on: [push]
jobs:
  my-job:
    name: Run MATLAB and Simulink Tests
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Set up products
        uses: matlab-actions/setup-matlab@v2
        with:
          products: >
            Simulink
            Simulink_Test
            Parallel_Computing_Toolbox
      - name: Run tests
        uses: matlab-actions/run-tests@v2
        with:
          use-parallel: true

Use MATLAB Batch Licensing Token

On a GitHub-hosted runner, you need a MATLAB batch licensing token if your project is private or if your workflow includes transformation products, such as MATLAB Coder™ and MATLAB Compiler™. Batch licensing tokens are strings that enable MATLAB to start in noninteractive environments. You can request a token by submitting the MATLAB Batch Licensing Pilot form.

To use a MATLAB batch licensing token:

1. Set the token as a secret. For more information about secrets, see Using secrets in GitHub Actions.
2. Map the secret to an environment variable named MLM_LICENSE_TOKEN in your workflow.

For example, use the latest release of MATLAB on a GitHub-hosted runner to run the tests in your private project. To set up the latest release of MATLAB on the runner, specify the Setup MATLAB action in your workflow. To run the tests, specify the Run MATLAB Tests action. In this example, MyToken is the name of the secret that holds the batch licensing token.

name: Use MATLAB Batch Licensing Token
on: [push]
env:
  MLM_LICENSE_TOKEN: ${{ secrets.MyToken }}
jobs:
  my-job:
    name: Run MATLAB Tests in Private Project
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2
      - name: Run tests
        uses: matlab-actions/run-tests@v2

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@v2.

By default, the action 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 the action includes all tests in the root of your repository and in any of its subfolders. The action fails if any of the included tests fail.

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

Notes

• By default, when you use the Run MATLAB Tests action, the root of your repository serves as the MATLAB startup folder. To run your tests using a different folder, specify the -sd startup option in the action.
• In MATLAB R2019a and later, the Run MATLAB Tests action uses 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 action.
• 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 Builds
• Action for Running MATLAB Commands
• Action for Setting Up MATLAB
• Continuous Integration with MATLAB and Simulink

Contact Us

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