|
1 | | -This guide shows you examples of how to configure the Jenkins™ plugin for MATLAB®, considering a Microsoft® Windows® platform. |
| 1 | +You can use the Jenkins™ plugin for MATLAB® in freestyle and multi-configuration projects. This guide demonstrates how to run MATLAB code on Jenkins, considering a Microsoft® Windows® platform. |
2 | 2 |
|
3 | | -## Contents |
| 3 | +- [Use MATLAB for Build](#use-matlab-for-build) |
| 4 | +- [Specify Build Steps](#specify-build-steps) |
| 5 | + - [Run MATLAB Tests](#run-matlab-tests) |
| 6 | + - [Run MATLAB Command](#run-matlab-command) |
| 7 | +- [Set Up Freestyle Project](#set-up-freestyle-project) |
| 8 | +- [Set Up Multi-Configuration Project](#set-up-multi-configuration-project) |
4 | 9 |
|
5 | | -- [Configure Plugin for Freestyle Project](#configure-plugin-for-freestyle-project) |
6 | | - - [Freestyle Project with Automatic Test Mode](#option-1-freestyle-project-with-automatic-test-mode) |
7 | | - - [Freestyle Project with Custom Test Mode](#option-2-freestyle-project-with-custom-test-mode) |
8 | | -- [Configure Plugin for Multi-Configuration Project](#configure-plugin-for-multi-configuration-project) |
9 | | - - [Multi-Configuration Project with Automatic Test Mode](#option-1-multi-configuration-project-with-automatic-test-mode) |
10 | | - - [Multi-Configuration Project with Custom Test Mode](#option-2-multi-configuration-project-with-custom-test-mode) |
11 | | - |
12 | | -## Configure Plugin for Freestyle Project |
13 | | -To configure the plugin for a freestyle project, select **Run MATLAB Tests** from the **Add build step** list. Then, enter the value returned by the **matlabroot** function in the **MATLAB root** field. |
| 10 | +## Use MATLAB for Build |
| 11 | +Once you install the plugin on Jenkins, the **Use MATLAB version** checkbox appears in the **Build Environment** section of the project configuration window. |
14 | 12 |
|
15 | | -  |
16 | | - |
17 | | -  |
18 | | - |
19 | | -### Option 1: Freestyle Project with Automatic Test Mode |
20 | | -With the Jenkins plugin for MATLAB, you have the option to run your tests in either *automatic* or *custom* mode. The automatic test mode employs a default setting to run tests written using the MATLAB Unit Testing Framework and/or Simulink Test. If your source code is organized as files and folders within a project, the plugin will consider any test files in the project that have been tagged as **Test**. If your code does not leverage a project or uses a MATLAB version prior to R2019a, the plugin will consider all tests in the current Jenkins workspace including the subfolders. |
21 | | - |
22 | | -If you use a source code management (SCM) system such as Git, then your job must include the appropriate SCM configuration to check out the code before it can invoke the MATLAB plugin. If you do not use any SCM systems to manage your code, then an additional build step is required to ensure that the code is available in the Jenkins workspace before the build starts. |
23 | | - |
24 | | -The automatic test execution feature of the plugin enables you to generate different types of test artifacts. To publish the test results, you can use these artifacts with other Jenkins plugins. To configure the Jenkins build where MATLAB tests run automatically, follow these steps. |
25 | | - |
26 | | -1) From the **Test mode** drop-down list, select the **Automatic** option (**Automatic** is the default testing mode). |
27 | | - |
28 | | -  |
29 | | - |
30 | | -2) Select your desired test artifacts. |
31 | | - |
32 | | -  |
33 | | - |
34 | | - The selected artifacts will be saved in the **matlabTestArtifacts** folder of the Jenkins workspace. |
35 | | - |
36 | | -  |
37 | | - |
38 | | -  |
39 | | - |
40 | | - If you do not select any of the test artifact check boxes, the **matlabTestArtifacts** folder will not be created in the workspace. However, tests will still run and potential test failures will fail the build. |
41 | | - |
42 | | - The **Automatic** test mode results in a MATLAB script file named **runMatlabTests.m** in the Jenkins workspace. The plugin uses this file to run the tests and generate the test artifacts. You can review the contents of the script to understand the testing workflow. |
43 | | - |
44 | | -  |
45 | | - |
46 | | - **Note:** Producing a PDF test report is not currently supported on MacOS platforms. |
47 | | - |
48 | | -### Option 2: Freestyle Project with Custom Test Mode |
49 | | -This option enables you to develop your custom MATLAB commands for running tests. To configure the Jenkins build where you can customize the MATLAB test execution, follow these steps. |
50 | | - |
51 | | -1) From the **Test mode** drop-down list, select the **Custom** option. |
| 13 | + |
52 | 14 |
|
53 | | -  |
| 15 | +Select the **Use MATLAB version** checkbox to specify the full path to the MATLAB root folder that should be used for the build. The information in the **MATLAB root** box enables the plugin to prepend MATLAB to the PATH environment variable of the build agent. |
54 | 16 |
|
55 | | -2) Enter your commands in the **MATLAB command** field. If you specify more than one MATLAB command, use a comma or semicolon to separate the commands. The build will fail if the execution of any command results in an error. |
| 17 | +If the build agent already has your desired MATLAB on the path, then you are not required to select the **Use MATLAB version** checkbox. When the checkbox is clear, the plugin uses the first MATLAB instance it encounters on the path. The build fails if the operating system cannot find MATLAB on the path. |
56 | 18 |
|
57 | | -  |
| 19 | +## Specify Build Steps |
| 20 | +When you set up the **Build** section of the project configuration window, the plugin provides you with the **Run MATLAB Tests** and **Run MATLAB Command** build steps. |
58 | 21 |
|
59 | | - **Note:** If you need several MATLAB commands to run your tests, consider writing a MATLAB script or function as part of your repository and executing this script or function instead. Test artifacts are not autogenerated if you choose to run tests using custom MATLAB commands. You can generate your desired test artifacts by configuring the test runner in the script or function that you invoke from the **MATLAB command** field. |
| 22 | +### Run MATLAB Tests |
| 23 | +This build step uses a default setting to run tests authored using the MATLAB Unit Testing Framework and/or Simulink® Test™. If your source code is organized as files and folders within a MATLAB project, then the plugin includes any test files in the project that have been labeled as **Test**. If your code does not leverage a MATLAB project or uses a MATLAB release before R2019a, then the plugin includes all tests in the current Jenkins workspace including its subfolders. |
60 | 24 |
|
61 | | -  |
| 25 | +If you use a source code management (SCM) system such as Git™, then your project must include the appropriate SCM configuration to check out the code before it can invoke the MATLAB plugin. If you do not use any SCM systems to manage your code, then an additional build step is required to ensure that the code is available in the Jenkins workspace before the build starts. |
62 | 26 |
|
63 | | -## Configure Plugin for Multi-Configuration Project |
64 | | -In addition to freestyle projects, the Jenkins plugin for MATLAB supports [multi-configuration (matrix) projects](https://wiki.jenkins.io/display/JENKINS/Building+a+matrix+project). Multi-configuration projects are useful when builds include similar steps, for example when the same test suite should run on different platforms (e.g., Windows, Linux, and Mac) or using several MATLAB versions. |
65 | | - |
66 | | - |
67 | | - |
68 | | -As in a freestyle project, you can run your tests in automatic or custom mode within a multi-configuration project. The configuration requires you to specify the location where MATLAB is installed as well as the test execution mode. You should also add user-defined axes in the **Configuration Matrix** to specify the duplicating build steps. |
| 27 | +The **Run MATLAB Tests** build step enables you to easily generate different types of test artifacts. To publish the test results, you can use these artifacts with other Jenkins plugins. The selected artifacts are saved in the **matlabTestArtifacts** folder of the Jenkins workspace. If you do not select any of the test artifact check boxes, the folder is not created. However, the tests still run and test failures fail the build. |
| 28 | + |
| 29 | + |
| 30 | + |
| 31 | +The **Run MATLAB Tests** build step produces a MATLAB script file named **runMatlabTests.m** in the Jenkins workspace. The plugin uses this file to run the tests and generate the test artifacts. You can review the contents of the script to understand the testing workflow. |
| 32 | + |
| 33 | +**Note:** Producing a PDF test report is not currently supported on MacOS platforms. |
| 34 | + |
| 35 | +### Run MATLAB Command |
| 36 | +The **Run MATLAB Command** build step enables you to specify MATLAB commands tailored to your specific needs. For example, you can use this build step to customize your test run or add a different build step to your pipeline. |
69 | 37 |
|
70 | | -### Option 1: Multi-Configuration Project with Automatic Test Mode |
| 38 | +If you specify more than one MATLAB command, use a comma or semicolon to separate the commands. The build fails if the execution of any command results in an error. |
71 | 39 |
|
72 | | -To configure the plugin for a matrix build where tests run automatically in multiple MATLAB versions, create a multi-configuration project and follow these steps. |
| 40 | + |
73 | 41 |
|
74 | | -1) Add a user-defined axis in the **Configuration Matrix** to represent the MATLAB versions in the build. Specify the name of the axis in the **Name** field and its values in the **Values** field. Separate the elements in the **Values** field with a space. In this example, four MATLAB versions are specified, which will be used to run the same set of tests. |
| 42 | +If you need to specify several MATLAB commands, consider writing a MATLAB script or function as part of your repository and executing this script or function instead. |
75 | 43 |
|
76 | | - |
| 44 | +Test artifacts are not autogenerated if you choose to run tests using this build step. You can generate your desired test artifacts by configuring the test runner in the script or function that you invoke from the **Command** box. |
77 | 45 |
|
78 | | -2) In the **Run MATLAB Tests** section of the project, include the user-defined axis name in the **MATLAB root** field to specify the locations where MATLAB is installed. In this example, **$VERSION** will be replaced by one axis value per build step. |
| 46 | +## Set Up Freestyle Project |
| 47 | +To configure the plugin for a freestyle project, specify the location where MATLAB is installed as well as the required build steps. |
79 | 48 |
|
80 | | - |
| 49 | +1) In the **Build Environment** section of the project configuration window, select **Use MATLAB version**. Then, enter the value returned by the **matlabroot** function in the **MATLAB root** box. (You can skip this step if MATLAB has already been added to the path on the build agent.) |
81 | 50 |
|
82 | | -You can select the test artifact check boxes when tests run automatically. Once you have made your selections, save your settings and run the build. |
| 51 | + |
| 52 | + |
| 53 | +2) Add the required build steps in the **Build** section: |
| 54 | + * If you add the [**Run MATLAB Tests**](#run-matlab-tests) build step, select check boxes for the artifacts to be generated in the project workspace. |
| 55 | + * If you add the [**Run MATLAB Command**](#run-matlab-command) build step, enter your commands in the **Command** box. |
83 | 56 |
|
84 | | -**Note:** Producing a PDF test report is not currently supported on MacOS platforms. |
| 57 | +## Set Up Multi-Configuration Project |
| 58 | +In addition to freestyle projects, the plugin supports [multi-configuration (matrix) projects](https://wiki.jenkins.io/display/JENKINS/Building+a+matrix+project). Multi-configuration projects are useful when builds include similar steps. For example: |
| 59 | +* The same test suite is run on different platforms (Windows, Linux, and Mac). |
| 60 | +* The same test suite is run against different versions of MATLAB. |
85 | 61 |
|
86 | | -### Option 2: Multi-Configuration Project with Custom Test Mode |
| 62 | +To configure the plugin for a multi-configuration project, specify the locations where MATLAB is installed as well as the required build steps. In addition, add user-defined axes in the **Configuration Matrix** section to specify the duplicating build steps. |
87 | 63 |
|
88 | | -To configure the matrix build where you can customize the MATLAB test execution, create a multi-configuration project and follow these steps. |
| 64 | +1) Add a user-defined axis in the **Configuration Matrix** section to represent the MATLAB versions in the build. Specify the name of the axis in the **Name** box and its values in the **Values** box. Separate the values with a space. In this example, four MATLAB versions are specified to run the same set of tests. |
89 | 65 |
|
90 | | -1) Add a user-defined axis in the **Configuration Matrix** to represent the MATLAB versions in the build. |
| 66 | + |
91 | 67 |
|
92 | | - |
| 68 | +You can define several axes in the **Configuration Matrix** section. For example, add the TEST_TAG axis specifying the possible test tags for a group of tests. |
93 | 69 |
|
94 | | -2) Add another user-defined axis using the **Add axis** button. In this example, the **TEST_TAG** axis specifies the possible test tags for a group of test elements. |
| 70 | + |
95 | 71 |
|
96 | | - |
| 72 | +2) In the **Build Environment** section, select **Use MATLAB version** and then specify the locations where MATLAB is installed using the user-defined axis name. In this example, **$VERSION** in the **MATLAB root** box will be replaced by one axis value per build iteration. |
97 | 73 |
|
98 | | -3) In the **Run MATLAB Tests** section of the project, use the **VERSION** axis to specify the locations where MATLAB is installed. |
| 74 | + |
99 | 75 |
|
100 | | - |
| 76 | +3) Add the required build steps in the **Build** section: |
| 77 | + * If you add the [**Run MATLAB Tests**](#run-matlab-tests) build step, select check boxes for the artifacts to be generated in the project workspace. |
| 78 | + * If you add the [**Run MATLAB Command**](#run-matlab-command) build step, enter your commands in the **Command** box. You can use the user-defined axes to create your commands. For example: |
101 | 79 |
|
102 | | -4) From the **Test mode** drop-down list, select the **Custom** option. Use the second user-defined axis to create your commands and enter them in the **MATLAB command** field. Then, save your settings and run the build. |
| 80 | + |
103 | 81 |
|
104 | | - |
| 82 | +**Note:** |
| 83 | +* For a user-defined axis named **VAR**, **$VAR** and **${VAR}** are both valid formats for accessing the values. |
105 | 84 |
|
106 | | -**Notes:** |
107 | | -1) For a user-defined axis named **VAR**, **$VAR** and **${VAR}** are both valid formats for accessing the values. |
| 85 | +* A multi-configuration project creates a separate workspace for each user-defined axis value. If you specify the full paths to where MATLAB is installed as axis values, Jenkins fails to create separate workspaces and fails the build. |
108 | 86 |
|
109 | | -2) A multi-configuration project creates a separate workspace for each user-defined axis value. If you specify the full paths to where MATLAB is installed as axis values, Jenkins fails to create separate workspaces and fails the build. |
| 87 | +## See Also |
| 88 | +[Run MATLAB Tests on Jenkins Server](examples/Run-MATLAB-Tests.md) |
0 commit comments