Skip to content

Commit aafd56e

Browse files
tsharmaMWtsharmaMW
committed
initial commit
0 parents  commit aafd56e

6 files changed

Lines changed: 356 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# This is a basic workflow to help you get started with MATLAB Actions
2+
3+
name: MATLAB Build
4+
5+
# Controls when the action will run.
6+
on:
7+
# Triggers the workflow on push or pull request events but only for the main branch
8+
push:
9+
branches: [ main ]
10+
pull_request:
11+
branches: [ main ]
12+
13+
# Allows you to run this workflow manually from the Actions tab
14+
workflow_dispatch:
15+
16+
jobs:
17+
# This workflow contains a single job called "build"
18+
build:
19+
# The type of runner that the job will run on
20+
runs-on: ubuntu-latest
21+
22+
# Steps represent a sequence of tasks that will be executed as part of the job
23+
steps:
24+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
25+
- uses: actions/checkout@v4
26+
27+
# Sets up MATLAB on a GitHub-hosted runner
28+
- name: Set up MATLAB
29+
uses: matlab-actions/setup-matlab@v2
30+
31+
# TASK 0 - Runs a MATLAB command using run-command action
32+
# - name: Run MATLAB command
33+
# uses: matlab-actions/run-command@v2
34+
# with:
35+
# command: ver
36+
37+
# TASK 1 - Runs all tests in the repository using run-tests action
38+
# - name: Run all tests
39+
# uses: matlab-actions/run-tests@v2
40+
# with:
41+
# source-folder: ??
42+
43+
# TASK 2 - Run all tests in the repository using run-build action
44+
# - name: Run all tests using buildtool
45+
# uses: matlab-actions/run-build@v2
46+
# with:
47+
# tasks: ??
48+
49+
# - name: Upload test results
50+
# uses: actions/upload-artifact@v4
51+
# if: always()
52+
# with:
53+
# name: test-results
54+
# path: test-results/results.xml

‎README.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
| **GitHub<sup>&reg;</sup>&nbsp;Actions** |
2+
|:---------------------------------------:|
3+
| [![MATLAB](https://github.com/mathworks/ci-configuration-examples/actions/workflows/ci.yml/badge.svg)](https://github.com/mathworks/ci-configuration-examples/actions/workflows/ci.yml) <br><br> |
4+
5+
6+
# Continuous Integration (CI) configuration examples for MATLAB<sup>&reg;</sup>
7+
8+
Are you interested in automating your testing with CI?
9+
10+
Not sure how to connect MATLAB with CI systems?
11+
12+
We've got you covered!
13+
14+
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.
15+
16+
<br>
17+
18+
19+
## Getting started
20+
### <u>Quick start guide</u>
21+
Here's how to quickly get this repository running on a CI system:
22+
1. Fork the repository to your own GitHub account
23+
2. Go to one of the supported CI platforms and install the available MATLAB CI plugin ***Note:*** GitHub Actions does not require this step
24+
3. Create a new CI job using your forked repository
25+
4. Enjoy using CI with MATLAB!
26+
27+
That's really it!
28+
29+
To use your MATLAB code or Simulink<sup>&reg;</sup> models with this repository, simply replace the existing code and tests in "source" 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.
30+
31+
***Notes:***
32+
* 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
33+
* The default branch for this repository is "main"
34+
35+
<br>
36+
37+
38+
### <u>Step-by-step getting started guide for GitHub Actions</u>
39+
Our Continuous Integration with MATLAB and GitHub Actions Workshop provides a step-by-step guide for getting started with GitHub Actions.
40+
* https://github.com/mathworks/ci-with-matlab-and-github-actions-workshop
41+
42+
43+
<br>
44+
45+
46+
## Badges
47+
48+
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.
49+
50+
<br>
51+
52+
| **GitHub&nbsp;Actions** | |
53+
|:-----------------------------|:-|
54+
| Badge | [![MATLAB](https://github.com/mathworks/ci-configuration-examples/actions/workflows/ci.yml/badge.svg)](https://github.com/mathworks/ci-configuration-examples/actions/workflows/ci.yml) |
55+
| 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) |
56+
| Badge Help | [GitHub Actions documentation for setting up badges](https://docs.github.com/en/actions/managing-workflow-runs/adding-a-workflow-status-badge) |
57+
58+
<br>
59+
60+
**How to use the Badge Code:**
61+
1. Copy-paste the badge code into your README.md file
62+
* The badge code you copy should start with "`[!`" and not "`\[\!`"
63+
2. Replace all ***BOLD+ITALIC*** names with your specific credentials/names
64+
* Replace ***GITHUB_ORG*** with your GitHub organization name (usually your GitHub username)
65+
* Replace ***GITHUB_REPO_NAME*** with the name of your GitHub repository
66+
* Replace ***SOURCE_CONTROL_SYSTEM*** with the name of the source control system you are pointing to (gh = GitHub, bb = BitBucket)
67+
* Replace ***DEFAULT_BRANCH_NAME*** with the repository branch name you want to get the pipeline status from
68+
69+
<br>
70+
71+
## About the code
72+
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).
73+
74+
Each of these pipeline definitions does four things:
75+
76+
1. Install the latest MATLAB release on a Linux<sup>&reg;</sup>-based build agent
77+
2. Run all MATLAB tests in the root of your repository, including its subfolders
78+
3. Produce a test results report (if necessary)
79+
4. Produce a code coverage report in Cobertura XML format for the source folder
80+
* To see an example of using [Codecov](https://about.codecov.io/) to show coverage results, please refer to [https://github.com/mathworks/matlab-codecov-example](https://github.com/mathworks/matlab-codecov-example)
81+
82+
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.
83+
84+
Notes:
85+
* MATLAB already includes a day-of-year calculation using `day(d,"dayofyear")`, where `d` is a datetime object. This code is only used as an example since it is a concept that is familiar to most people.
86+
* 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%.
87+
88+
There are 2 test classes provided:
89+
1. TestExamples.m - A simple set of equality and negative tests
90+
2. ParameterizedTestExamples.m - A set of 12 equality tests set up using the parameterized test format
91+
92+
The repository includes these files:
93+
94+
| **File Path** | **Description** |
95+
|:---------------------------|:----------------|
96+
| [`source/dayofyear.m`](source/dayofyear.m) | The [`dayofyear`](source/dayofyear.m) function returns the day-of-year number for a given date string "mm/dd/yyyy" |
97+
| [`tests/TestExamples.m`](tests/TestExamples.m) | The [`TestExamples`](tests/TestExamples.m) class provides a few equality and negative tests for the [`dayofyear`](source/dayofyear.m) function |
98+
| [`tests/ParameterizedTestExample.m`](tests/ParameterizedTestExample.m) | The [`ParameterizedTestExample`](tests/ParameterizedTestExample.m) class provides 12 tests for the [`dayofyear`](source/dayofyear.m) function using the parameterized test format |
99+
| [`.github/workflows/ci.yml`](###GitHub-Actions) | The [`ci.yml`](.github/workflows/ci.yml) file defines the pipeline that runs on [GitHub Actions](https://github.com/matlab-actions/overview) |
100+
101+
<br>
102+
103+
## Caveats
104+
* On cloud-hosted agents provided by Azure DevOps, CircleCI, and GitHub Actions, you need a [MATLAB batch licensing token](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md#matlab-batch-licensing-token) if your project is private or if your pipeline includes transformation products, such as MATLAB Coder&trade; and MATLAB Compiler&trade;. You can request a token by contacting MathWorks&reg; at [batch-tokens@mathworks.com](mailto:batch-tokens@mathworks.com).
105+
106+
<br>
107+
108+
109+
## Links
110+
- [Continuous Integration with MATLAB and Simulink](https://www.mathworks.com/solutions/continuous-integration.html)
111+
112+
<br>
113+
114+
115+
## Contact Us
116+
If you have any questions or suggestions, please contact MathWorks at [continuous-integration@mathworks.com](mailto:continuous-integration@mathworks.com).

‎buildfile.m‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
function plan = buildfile
2+
3+
% Add the source folder to the path
4+
addpath("source");
5+
6+
% Create a plan
7+
plan = buildplan(localfunctions);
8+
9+
% Add a task to run tests
10+
plan("test") = matlab.buildtool.tasks.TestTask("tests", TestResults="test-results/results.xml");
11+
plan("test").Description = "Run all unit tests";
12+
13+
end

‎source/dayofyear.m‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
function doy = dayofyear(mmddyy,dateFormat)
2+
%DAYOFYEAR Converts a date string ("mm/dd/yyyy") to the day number of the
3+
%year.
4+
5+
% NOTE: MATLAB already does easily this using:
6+
% doy = day(d,"dayofyear")
7+
% where d is a datetime object
8+
9+
% Copyright 2022 The MathWorks, Inc.
10+
11+
arguments
12+
mmddyy string;
13+
dateFormat (1,1) string {mustBeMember(dateFormat,["mm/dd/yyyy","dd/mm/yyyy"])} = "mm/dd/yyyy";
14+
end
15+
16+
% Check that mmddyy was provided in the appropriate format
17+
if numel(split(mmddyy,"/")) ~= 3
18+
error("dayofyear:InvalidDateFormat","Invalid date string. Expected date formatted as dd/mm/yyyy.")
19+
end
20+
21+
% Create a datetime object depending on the dateFormat provided
22+
if dateFormat == "mm/dd/yyyy"
23+
d = datetime(mmddyy,"Format","MM/dd/uuuu");
24+
else
25+
d = datetime(mmddyy,"Format","dd/MM/uuuu");
26+
end
27+
28+
% Initialize the days per month
29+
daysPerMonth = [ ...
30+
31; % January
31+
28; % February
32+
31; % March
33+
30; % April
34+
31; % May
35+
30; % June
36+
31; % July
37+
31; % August
38+
30; % September
39+
31; % October
40+
30; % November
41+
31]; % December
42+
43+
% Check for leap year
44+
if mod(d.Year,4) == 0
45+
% This is a leap year, so change February to 29 days
46+
daysPerMonth(2) = 29;
47+
end
48+
49+
% Calculate day of year
50+
doy = sum(daysPerMonth(1:d.Month-1)) + d.Day;
51+
52+
53+
end
54+

‎tests/ParameterizedTestExample.m‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
classdef ParameterizedTestExample < matlab.unittest.TestCase
2+
% Creates 12 test points, one test point for the 15th day of every month of 2021
3+
4+
% Copyright 2022 The MathWorks, Inc.
5+
6+
properties (TestParameter)
7+
monthNum = num2cell(1:12);
8+
dayNum = {15};
9+
yearNum = {2021};
10+
end
11+
12+
methods (Test)
13+
function testDayofyear(testCase,monthNum,dayNum,yearNum)
14+
% Convert numeric values to mm/dd/yyyy string
15+
% Note: MATLAB will automatically convert numbers to strings
16+
% when performing number+string arithmetic
17+
dateStr = monthNum + "/" + dayNum + "/" + yearNum;
18+
19+
% Compute expected result
20+
dt = datetime(dateStr,"Format","MM/dd/uuuu");
21+
doyExpected = day(dt,"dayofyear");
22+
23+
% Compute actual result
24+
doyActual = dayofyear(dateStr);
25+
26+
% Verify that the actual result matches the expected result
27+
testCase.verifyEqual(doyActual,doyExpected)
28+
end
29+
end
30+
31+
end
32+

‎tests/TestExamples.m‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
classdef TestExamples < matlab.unittest.TestCase
2+
% TestExamples contains a set of 4 simple tests:
3+
% 1) an equality test for a non-leap year date
4+
% 2) an equality test for a leap year date
5+
% 3) a negative test for an invalid date format input
6+
% 4) a negative test for a correct date format but an invalid date
7+
% 5) an equality test for a non-leap year date using the alternate
8+
% dateFormat (COMMENTED OUT)
9+
%
10+
% Notes:
11+
% A) A negative test verifies that the code errors/fails in an
12+
% expected way (e.g., the code gives the right error for a
13+
% specific bad input)
14+
% B) The 5th test is included for completeness, but is commented
15+
% out to illustrate missing code coverage in continous
16+
% integration (CI) systems
17+
18+
% Copyright 2022 The MathWorks, Inc.
19+
20+
methods (Test)
21+
22+
function testNonLeapYear(testCase)
23+
% Create non-leap year date of March 1st, 2021
24+
dateStr = "03/01/2021";
25+
26+
% Calculate expected result
27+
dt = datetime(dateStr,"Format","MM/dd/uuuu");
28+
doyExpected = day(dt,"dayofyear");
29+
30+
% Get actual result
31+
doyActual = dayofyear(dateStr);
32+
33+
% Verify that the two are equal
34+
testCase.verifyEqual(doyActual,doyExpected)
35+
end
36+
37+
function testLeapYear(testCase)
38+
% Create leap year date of March 1st, 2020
39+
dateStr = "03/01/2020";
40+
41+
% Calculate expected result
42+
dt = datetime(dateStr,"Format","MM/dd/uuuu");
43+
doyExpected = day(dt,"dayofyear");
44+
45+
% Get actual result
46+
doyActual = dayofyear(dateStr);
47+
48+
% Verify that the two are equal
49+
testCase.verifyEqual(doyActual,doyExpected)
50+
end
51+
52+
function testInvalidDateFormat(testCase)
53+
% Create invalid date of April 1st, 2021
54+
dateStr = "04-01-2021";
55+
56+
% Verify that our function throws an error
57+
testCase.verifyError(@() dayofyear(dateStr),"dayofyear:InvalidDateFormat");
58+
end
59+
60+
function testCorrectDateFormatButInvalidDate(testCase)
61+
% Create invalid date of February 30th, 2021
62+
dateStr = "02/30/2021";
63+
64+
% Verify that our function throws an error
65+
testCase.verifyError(@() dayofyear(dateStr),"MATLAB:datetime:ParseErr");
66+
end
67+
68+
% function testAlternateDateFormat(testCase)
69+
% % Create date of April 1st, 2021 in alternate date format
70+
% dateStr = "01/04/2021";
71+
% dateFormat = "dd/mm/yyyy";
72+
%
73+
% % Calculate expected result
74+
% dt = datetime(dateStr,"Format","dd/MM/uuuu");
75+
% doyExpected = day(dt,"dayofyear");
76+
%
77+
% % Get actual result
78+
% doyActual = dayofyear(dateStr,dateFormat);
79+
%
80+
% % Verify that the two are equal
81+
% testCase.verifyEqual(doyActual,doyExpected)
82+
% end
83+
84+
end
85+
86+
end
87+

0 commit comments

Comments
 (0)