Azure® DevOps | CircleCI® | GitHub® Actions | Travis CI™ |
---|---|---|---|
|
|
|
|
Are you interested in automating your testing with CI?
Not sure how to connect MATLAB with CI systems?
We've got you covered!
This repository makes it easy to run your MATLAB tests on some of the most common CI platforms. The configuration files take care of setting up MATLAB to work with the CI system and automatically executing your MATLAB tests.
Take a look at the "Quick Start Guide" below to get started!
Here's how to quickly get this repository running on a CI system:
- Fork the repository to your own GitHub account
- Go to one of the supported CI platforms and install the available MATLAB CI plugin Note: GitHub Actions does not require this step
- Create a new CI job using your forked repository
- Enjoy using CI with MATLAB!
That's really it!
To use your MATLAB code or Simulink® models with this repository, simply replace the existing code and tests in "code" and "tests" with your own code and tests. There's no need to modify any of the CI configuration files because they are all completely agnostic of the MATLAB code being used.
Notes:
- In most cases, the configuration files will automatically get picked up by the CI platform during step 3, but some platforms may require you to specify which file to use
- The default branch for this repository is "main"
Badges look really great, but they're not always easy to set up. Take a look at the badges, badge code, and reference links below to get started with badges for your repository.
Azure DevOps | |
---|---|
Badges | |
Badge Code | [![Build Status](https://dev.azure.com/AZURE_DEVOPS_ORG/AZURE_DEVOPS_PROJECT_NAME/_apis/build/status/GITHUB_USERNAME.GITHUB_REPO_NAME)](https://dev.azure.com/AZURE_DEVOPS_ORG/AZURE_DEVOPS_PROJECT_NAME/_build) ![Azure DevOps Coverage](https://img.shields.io/azure-devops/coverage/AZURE_DEVOPS_ORG/AZURE_DEVOPS_PROJECT_NAME/AZURE_DEVOPS_DEFINITION_ID) |
Badge Help | Blog with helpful information for setting up Azure DevOps badges |
CircleCI | |
---|---|
Badge | |
Badge Code | [![CircleCI](https://circleci.com/SOURCE_CONTROL_SYSTEM/GITHUB_USERNAME/GITHUB_REPO_NAME.svg?style=svg)](https://circleci.com/SOURCE_CONTROL_SYSTEM/GITHUB_USERNAME/GITHUB_REPO_NAME) |
Badge Help | CircleCI documentation for setting up badges |
GitHub Actions | |
---|---|
Badge | |
Badge Code | [![MATLAB](https://github.com/GITHUB_USERNAME/GITHUB_REPO_NAME/actions/workflows/ci.yml/badge.svg)](https://github.com/GITHUB_USERNAME/GITHUB_REPO_NAME/actions/workflows/ci.yml) |
Badge Help | GitHub Actions documentation for setting up badges |
Travis CI | |
---|---|
Badge | |
Badge Code | [![Build Status](https://app.travis-ci.com/GITHUB_USERNAME/GITHUB_REPO_NAME.svg)](https://app.travis-ci.com/GITHUB_USERNAME/GITHUB_REPO_NAME) |
Badge Help | Travis CI documentation for setting up badges |
GitLab CI/CD | |
---|---|
Badge Code | [![Pipeline Status](https://gitlab.com/GITLAB_PROJECT_PATH/badges/DEFAULT_BRANCH_NAME/pipeline.svg)](https://gitlab.com/GITLAB_PROJECT_PATH) |
Badge Help | GitLab CI/CD documentation for setting up badges |
How to use the Badge Code:
- Copy-paste the badge code into your README.md file
- The badge code you copy should start with "
[!
" and not "\[\!
"
- The badge code you copy should start with "
- Replace all BOLD+ITALIC names with your specific credentials/names
- Replace GITHUB_ORG with your GitHub organization name (usually your GitHub username)
- Replace GITHUB_REPO_NAME with the name of your GitHub repository
- Replace SOURCE_CONTROL_SYSTEM with the name of the source control system you are pointing to (gh = GitHub, bb = BitBucket)
- Replace AZURE_DEVOPS_ORG with the name of your Azure DevOps organization name (usually your Azure DevOps username)
- Replace AZURE_DEVOPS_PROJECT_NAME with the name of the Azure DevOps project that will run the CI job
- Replace AZURE_DEVOPS_DEFINITION_ID with the definition ID for your Azure DevOps pipeline
- To find the definition ID for your Azure DevOps pipeline, you must:
- go to your Azure DevOps project
- select "Pipelines" from the left-side navigation menu
- select the pipeline you want to get coverage for
- look at the end of the resulting URL for the number in "definitionId=###"
- To find the definition ID for your Azure DevOps pipeline, you must:
- Replace GITLAB_PROJECT_PATH with the path of your GitLab project
- Replace DEFAULT_BRANCH_NAME with the repository branch name you want to get the pipeline status from
- Azure DevOps
- CircleCI
- GitHub Actions
- Jenkins™
- Travis CI
- GitLab CI/CD
The primary goal of this repository is to provide a set of configuration files as templates that illustrate how to run MATLAB on various CI platforms (e.g., Azure DevOps, CircleCI, GitHub Actions, Jenkins, Travis CI).
Each of these pipeline definitions does four things:
- Install the latest MATLAB release on a Linux®-based build agent
- Run all MATLAB tests in the root of your repository, including its subfolders
- Produce a test results report (if necessary)
- Produce a code coverage report in Cobertura XML format for the source folder
- Currently, only Azure DevOps supports code coverage directly
- To see an example of using Codecov to show coverage results, please refer to https://github.com/mathworks/matlab-codecov-example
The example MATLAB code example dayofyear.m
is a simple function takes a date string "mm/dd/yyyy"
and returns the day-of-year number.
Notes:
- MATLAB already includes a day-of-year calculation using
day(d,"dayofyear")
, whered
is a datetime object. This code is only used as an example since it is a concept that is familiar to most people. - The code coverage is intentionally set below 100% to show how missing coverage looks with badges. Uncomment the last test in
TestExamples.m
to increase the coverage to 100%.
There are 2 test classes provided:
- TestExamples.m - A simple set of equality and negative tests
- ParameterizedTestExamples.m - A set of 12 equality tests set up using the parameterized test format
The repository includes these files:
File Path | Description |
---|---|
code/dayofyear.m |
The dayofyear function returns the day-of-year number for a given date string "mm/dd/yyyy" |
tests/TestExamples.m |
The TestExamples class provides a few equality and negative tests for the dayofyear function |
tests/ParameterizedTestExample.m |
The ParameterizedTestExample class provides 12 tests for the dayofyear function using the parameterized test format |
azure-pipelines.yml |
The azure-pipelines.yml file defines the pipeline that runs on Azure DevOps. |
.circleci/config.yml |
The config.yml file defines the pipeline that runs on CircleCI |
.github/workflows/ci.yml |
The ci.yml file defines the pipeline that runs on GitHub Actions |
Jenkinsfile |
The Jenkinsfile file defines the pipeline that runs on Jenkins |
.travis.yml |
The .travis.yml file defines the pipeline that runs on Travis CI |
.gitlab-ci.yml |
The .gitlab-ci.yml file defines the pipeline that runs on GitLab CI/CD |
pool:
vmImage: Ubuntu 16.04
steps:
- task: InstallMATLAB@0
- task: RunMATLABTests@0
inputs:
sourceFolder: code
codeCoverageCobertura: code-coverage/coverage.xml
testResultsJUnit: test-results/results.xml
- task: PublishTestResults@2
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'test-results/results.xml'
- task: PublishCodeCoverageResults@1
inputs:
codeCoverageTool: 'Cobertura'
summaryFileLocation: 'code-coverage/coverage.xml'
pathToSources: 'code/'
# As an alternative to RunMATLABTests, you can use RunMATLABCommand to execute a MATLAB script, function, or statement.
# - task: RunMATLABCommand@0
# inputs:
# command: addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);
version: 2.1
orbs:
matlab: mathworks/matlab@0
codecov: codecov/codecov@1
jobs:
build:
machine:
image: ubuntu-1604:201903-01
steps:
- checkout
- matlab/install
- matlab/run-tests:
source-folder: code
# As an alternative to run-tests, you can use run-command to execute a MATLAB script, function, or statement.
# - matlab/run-command:
# command: addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);
# This is a basic workflow to help you get started with MATLAB Actions
name: MATLAB Build
# Controls when the action will run.
on:
# Triggers the workflow on push or pull request events but only for the main branch
push:
branches: [ main ]
pull_request:
branches: [ main ]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v2
# Sets up MATLAB on the GitHub Actions runner
- name: Setup MATLAB
uses: matlab-actions/setup-matlab@v0
# Runs a set of commands using the runners shell
- name: Run all tests
uses: matlab-actions/run-tests@v0
with:
source-folder: code
# As an alternative to run-tests, you can use run-command to execute a MATLAB script, function, or statement.
#- name: Run all tests
# uses: matlab-actions/run-command@v0
# with:
# command: addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);
pipeline {
agent any
stages {
stage('Run MATLAB Tests') {
steps {
runMATLABTests(
sourceFolder: 'code'
)
// As an alternative to runMATLABTests, you can use runMATLABCommand to execute a MATLAB script, function, or statement.
// runMATLABCommand "addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);"
}
}
}
}
language: matlab
script: matlab -batch "addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);"
stages:
- matlab-test
matlab-test:
stage: matlab-test
script:
- matlab -batch "addpath('code'); results = runtests('IncludeSubfolders', true); assertSuccess(results);"
- MATLAB builds on Travis CI are available only for public projects.
- MATLAB builds on Azure DevOps, CircleCI, and GitHub Actions that use CI service-hosted agents are also available only for public projects. However, these integrations can also be used in private projects that leverage self-hosted runners/agents.
If you have any questions or suggestions, please contact MathWorks at [email protected].