Skip to content
matlab-actions

GitHub Action

Run MATLAB Tests

v2.1.1 Latest version

Run MATLAB Tests

matlab-actions

Run MATLAB Tests

Run MATLAB and Simulink tests and generate artifacts

Installation

Copy and paste the following snippet into your .yml file.

              
- name: Run MATLAB Tests

              
  uses: matlab-actions/run-tests@v2.1.1
Learn more about this action in matlab-actions/run-tests

Choose a version

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. The action uses the topmost MATLAB version on the system path.

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 run 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@v4
      - name: Run tests
        uses: matlab-actions/run-tests@v2

Generate Artifacts on GitHub-Hosted Runner

Before you run tests and generate artifacts on a GitHub-hosted runner, first use the Setup MATLAB action. The action sets up your specified MATLAB release (R2021a or later) on a Linux®, Windows®, or macOS runner. If you do not specify a release, the action sets up the latest release of MATLAB.

For example, set up 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 test results in JUnit-style XML format and code coverage results in Cobertura XML format.

name: Generate Test and Coverage 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@v4
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2
      - name: Run tests and generate artifacts
        uses: matlab-actions/run-tests@v2
        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@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 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-folder: source
Example: source-folder: 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: select-by-folder: test
Example: select-by-folder: 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: select-by-tag: Unit
strict

(Optional) Option 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 action generates a qualification failure whenever a test issues a warning.

Example: strict: true
use-parallel

(Optional) Option to run tests in parallel, 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 input requires a Parallel Computing Toolbox™ license.

Example: use-parallel: true
output-detail

(Optional) Amount of event detail displayed for the test run, specified as none, terse, concise, detailed, or verbose. By default, the action displays failing and logged events at the detailed level and test run progress at the concise level.

Example: output-detail: verbose
logging-level

(Optional) Maximum verbosity level for logged diagnostics included for the test run, specified as none, terse, concise, detailed, or verbose. By default, the action includes diagnostics logged at the terse level.

Example: logging-level: detailed
test-results-pdf

(Optional) Path to write the test results in PDF format. On macOS platforms, this input is supported in MATLAB R2020b and later.

Example: test-results-pdf: test-results/results.pdf
test-results-junit

(Optional) Path to write the test results in JUnit-style XML format.

Example: test-results-junit: 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-simulink-test: test-results/results.mldatx
code-coverage-cobertura

(Optional) Path to write the code coverage results in Cobertura XML format.

Example: code-coverage-cobertura: code-coverage/coverage.xml
model-coverage-cobertura

(Optional) Path to write the model coverage results in Cobertura XML format. This input requires a Simulink Coverage™ license and is supported in MATLAB R2018b and later.

Example: model-coverage-cobertura: model-coverage/coverage.xml
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 -batch or -r option is not supported.

Example: startup-options: -nojvm
Example: startup-options: -nojvm -logfile output.log

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, include the -sd startup option in the action.
  • In MATLAB R2019a and later, the Run MATLAB Tests action uses the -batch option to start MATLAB. 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

Contact Us

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