The Run MATLAB Tests action enables you to run MATLAB® and Simulink® tests and generate test and coverage artifacts on a GitHub®-hosted or self-hosted runner:
- To use a GitHub-hosted runner, include the Setup MATLAB action in your workflow to set up your preferred MATLAB release (R2021a or later) on the runner.
- To use a self-hosted runner, set up a computer with MATLAB on its path and register the runner with GitHub Actions. (On self-hosted UNIX® runners, you can also use the Setup MATLAB action instead of having MATLAB already installed.) The runner uses the topmost MATLAB release on the system path to execute your workflow.
Use the Run MATLAB Tests action to automatically run tests authored using the MATLAB unit testing framework or Simulink Test™. To use the action, you need MATLAB R2013b or a later release. Some of the optional action inputs require newer MATLAB releases or additional toolboxes.
On a self-hosted runner that has MATLAB installed, 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@v2Using 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.xmlRun 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: trueWhen you define a workflow using the Setup MATLAB action, you need a MATLAB batch licensing token if your project is private or if your workflow uses 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:
- Set the token as a secret. For more information about secrets, see Using secrets in GitHub Actions.
- Map the secret to an environment variable named
MLM_LICENSE_TOKENin 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@v2When 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.
| Input | Description |
|---|---|
source-folder | (Optional) Location of the folder containing source code, specified as a path 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 Example: |
select-by-folder | (Optional) Location of the folder used to select test suite elements, specified as a path relative to the project root folder. To create a test suite, the action 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: |
select-by-tag | (Optional) Test tag used to select test suite elements. To create a test suite, the action uses only the test elements with the specified tag. Example: |
strict | (Optional) Option to apply strict checks when running tests, specified as Example: |
use-parallel | (Optional) Option to run tests in parallel, specified as Example: |
output-detail | (Optional) Amount of event detail displayed for the test run, specified as output-detail: verbose |
logging-level | (Optional) Maximum verbosity level for logged diagnostics included for the test run, specified as logging-level: detailed |
test-results-html | (Optional) Location to write the test results in HTML format, specified as a folder path relative to the project root folder. Example: |
test-results-pdf | (Optional) Location to write the test results in PDF format, specified as a file path relative to the project root folder. On macOS platforms, this input is supported in MATLAB R2020b and later. Example: |
test-results-junit | (Optional) Location to write the test results in JUnit-style XML format, specified as a file path relative to the project root folder. Example: |
test-results-simulink-test | (Optional) Location to export Simulink Test Manager results in MLDATX format, specified as a file path relative to the project root folder. This input requires a Simulink Test license and is supported in MATLAB R2019a and later. Example: |
code-coverage-html | (Optional) Location to write the code coverage results in HTML format, specified as a folder path relative to the project root folder. Example: |
code-coverage-cobertura | (Optional) Location to write the code coverage results in Cobertura XML format, specified as a file path relative to the project root folder. Example: |
model-coverage-html | (Optional) Location to write the model coverage results in HTML format, specified as a folder path relative to the project root folder. This input requires a Simulink Coverage™ license and is supported in MATLAB R2018b and later. Example: |
model-coverage-cobertura | (Optional) Location to write the model coverage results in Cobertura XML format, specified as a file path relative to the project root folder. This input requires a Simulink Coverage license and is supported in MATLAB R2018b and later. Example: |
startup-options | (Optional) MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see Commonly Used Startup Options. Using this input to specify the Example: |
- 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
-sdstartup option in the action. - In MATLAB R2019a and later, the Run MATLAB Tests action uses the
-batchoption to start MATLAB noninteractively. MATLAB settings do not persist across different MATLAB sessions launched with the-batchoption. To run code that requires the same settings, use a single action. - When you use the Run MATLAB Tests action, you execute third-party code that is licensed under separate terms.
- Action for Running MATLAB Builds
- Action for Running MATLAB Commands
- Action for Setting Up MATLAB
- Continuous Integration with MATLAB and Simulink
If you encounter a product licensing issue, consider requesting a MATLAB batch licensing token to use in your workflow. For more information, see Use MATLAB Batch Licensing Token.
If you have an enhancement request or other feedback about this action, create an issue on the Issues page.
For support, contact MathWorks Technical Support.
