Incorporate review feedback

mw-hrastega · mw-hrastega · commit 868485b81adb · 2020-06-17T11:42:33.000-04:00
diff --git a/CONFIGDOC.md b/CONFIGDOC.md
@@ -1,13 +1,23 @@
-You can use the Jenkins&trade; plugin for MATLAB&reg; in freestyle and multi-configuration projects. This guide demonstrates how to run your MATLAB code or Simulink&reg; model on Jenkins.
+When you define a [Jenkins&trade; Pipeline](https://www.jenkins.io/doc/book/pipeline/), wether in the web UI or with a [`Jenkinsfile`](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#setting-environment-variables), you can use the plugin to run your MATLAB&reg; code or Simulink&reg; models on Jenkins. This guide demonstrates how to configure the plugin and use it in freestyle, multi-configuration, and Pipeline projects.
 
--  [Use MATLAB for Build](#use-matlab-for-build)
--  [Specify Build Steps](#specify-build-steps)
-      - [Run MATLAB Tests](#run-matlab-tests)
-      - [Run MATLAB Command](#run-matlab-command)
+
+-  [Configure Plugin in Web UI](#configure-plugin-in-web-ui)
+      -  [Use MATLAB for Build](#use-matlab-for-build)
+      -  [Specify Build Steps](#specify-build-steps)
+         - [Run MATLAB Command](#run-matlab-command)
+         - [Run MATLAB Tests](#run-matlab-tests)
 -  [Set Up Freestyle Project](#set-up-freestyle-project)
 -  [Set Up Multi-Configuration Project](#set-up-multi-configuration-project)
+-  [Set Up Pipeline Project](#set-up-pipeline-project)
+   -  [Add MATLAB to System Path](#add-matlab-to-system-path)
+   -  [Use `RunMATLABCommand` Step](#use-runmatlabcommand-step)
+   -  [Use `RunMATLABTests` Step](#use-runmatlabtests-step) 
+   -  [Use MATLAB for Matrix Build](#use-matlab-for-matrix-build)
+
+## Configure Plugin in Web UI
+You can use the web UI provided by Jenkins to configure the plugin in freestyle and multi-confiuraton projects. To run MATLAB or Simulink in a Pipeline project, see [Set Up Pipeline Project](#set-up-pipeline-project).
 
-## Use MATLAB for Build
+### Use MATLAB for Build
 Once you install the plugin, **Use MATLAB version** appears in the **Build Environment** section of the project configuration window.
 
 ![matlab_path](https://user-images.githubusercontent.com/48831250/76883191-1c528b00-6852-11ea-9242-7d143f8a5c46.png)
@@ -24,12 +34,12 @@ If the build agent already has your desired MATLAB on the path, then you are not
 | Linux&reg;   | /usr/local/MATLAB/R2019a        |
 | Mac          | /Applications/MATLAB_R2019a.app |
 
-## Specify Build Steps
+### Specify Build Steps
 When you set up the **Build** section of the project configuration window, the plugin provides you with the **Run MATLAB Command** and **Run MATLAB Tests** build steps.
 
 If you use a source code management (SCM) system such as Git&trade;, then your project must include the appropriate SCM configuration to check out the code before it can invoke the 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.
 
-### Run MATLAB Command
+#### Run MATLAB Command
 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.
 
 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.
@@ -40,12 +50,13 @@ If you need to specify several MATLAB commands, consider writing a MATLAB script
 
 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.
 
-### Run MATLAB Tests
+#### Run MATLAB Tests
 This build step uses a default setting to run tests authored using the MATLAB Unit Testing Framework or Simulink Test&trade;. If your source code is organized into 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 project workspace, including its subfolders. 
 
 The **Run MATLAB Tests** build step enables you to generate different types of test artifacts. To publish the test results, you can use these artifacts with other Jenkins plugins. By default, the plugin assigns a name to each selected artifact and stores it in the `matlabTestArtifacts` folder of the project workspace. You can override the default artifact name and location by specifying a path relative to the project folder in the **File path** box. (If you leave the text box empty, the plugin does not generate an artifact.)  
  
-![run_matlab_tests](https://user-images.githubusercontent.com/48831250/83892479-b7098a00-a71c-11ea-80c9-dacc1374dfe0.png)
+![run_matlab_tests](https://user-images.githubusercontent.com/48831250/84545463-54406180-accd-11ea-890e-7a6bb9ee051b.png)
+
 
 If you do not select any of the test artifact check boxes, the tests still run, and test failures fail the build.
 
@@ -97,6 +108,201 @@ You can define several axes in the **Configuration Matrix** section. For example
 
 * 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.
 
+## Set Up Pipeline Project
+When you define your Pipeline with a `Jenkinsfile`, the plugin provides you with a step to run MATLAB scripts, functions, and statements. The plugin also provides a step to run MATLAB and Simulink tests. (These steps are common to both Declarative and Scripted Pipeline.) 
+
+To configure the plugin for a Pipeline project:
+1) Define your Pipeline in a `Jenkinsfile` in the root of your repository.
+2) In the **Pipeline** section of the project configuration window, select **Pipeline script from SCM** from the **Definition** drop-down menu. 
+3) Select your source control system from the **SCM** drop-down menu.
+4) Paste your repository URL into the **Repository URL** box.
+
+You also can define your Pipeline directly in the project configuration window. If you select **Pipeline script** from the **Definition** drop-down menu, you can author your Pipeline code in the **Script** box. When you define your Pipeline this way, your Pipeline must include an additional stage to check out MATLAB code from source control.
+
+### Add MATLAB to System Path
+When Jenkins executes your Pipeline, it invokes the first MATLAB instance on the system path. If the PATH environment variable of the build agent does not inculde any MATLAB instances, you must update the variable with the MATLAB root folder that should be used for the build.
+
+To update the system PATH environment variable using Declarative Pipeline syntax, use an `environment` block in your `Jenkinsfile`. For example, prepend MATLAB R2019a to the system PATH enviroment variable and use it to run your command.
+
+```groovy
+pipeline {
+   agent any
+   environment {
+       PATH = "C:\\Program Files\\MATLAB\\R2019a\\bin;${PATH}"   // Windows agent
+    // PATH = "/usr/local/MATLAB/R2019a/bin:${PATH}"   // Linux agent
+    // PATH = "/Applications/MATLAB_R2019a.app/bin:${PATH}"   // Mac agent    
+   }
+    stages{
+        stage('Run MATLAB Command') {
+            steps
+            {
+               runMATLABCommand "disp('Hello World!')"
+            }       
+        }                
+    } 
+}
+``` 
+If you define your Pipeline using scripted syntax, set the PATH environment variable in the `node` block. For example: 
+
+```groovy
+node {
+        env.PATH = "C:\\Program Files\\MATLAB\\R2019a\\bin;${env.PATH}"   //Windows agent
+     // env.PATH = "/usr/local/MATLAB/R2019a/bin:${env.PATH}"   //Linux agent
+     // env.PATH = "/Applications/MATLAB_R2019a.app/bin:${env.PATH}"   //Mac agent
+        runMATLABCommand "disp('Hello World!')"
+}
+``` 
+
+### Use `runMATLABCommand` Step
+Use the `runMATLABCommand` step in your Pipeline to run MATLAB scripts, functions, and statements tailored to your specific needs. You can use this task to flexibly customize your test run or add a build step to your pipeline.
+
+You must provide `runMATLABCommand` with a string that specifies the command you want to execute. If the command is the name of a MATLAB script or function, do not specify the file extension. If you specify more than one MATLAB command, use a comma or semicolon to separate the commands.
+
+**Example:** `runMATLABCommand 'myscript'`<br/>
+**Example:** `runMATLABCommand 'results = runtests, assertSuccess(results);'` 
+
+For example, in your `Jenkinsfile`, define a Declarative Pipeline to run the commands in a file named `myscript.m`.
+
+
+```groovy
+pipeline {
+    agent any
+    stages{
+        stage('Run MATLAB Command') {
+            steps
+            {
+                runMATLABCommand 'myscript'
+            }       
+        }                
+    } 
+}
+``` 
+
+You also can use `runMATLABCommand` in a Scripted Pipeline.
+
+```groovy
+node {
+    runMATLABCommand 'myscript'  
+}
+``` 
+
+MATLAB exits with exit code 0 if the specified script, function, or statement executes successfully without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the build to fail. You can use the [`assert`](https://www.mathworks.com/help/matlab/ref/assert.html) or [`error`](https://www.mathworks.com/help/matlab/ref/error.html) functions in the command to ensure that builds fail when necessary.
+
+When you use the `runMATLABCommand` step, all of the required files must be on the MATLAB search path.
+
+### Use `runMATLABTests` Step
+
+Use the `runMATLABTests` step in your Pipeline to run all tests in your MATLAB project and generate artifacts. MATLAB includes any files in your project that have a `Test` label. If your Pipeline does not leverage a MATLAB project or uses a MATLAB release before R2019a, then MATLAB includes all tests in the the root of your repository including its subfolders.
+
+For example, in your `Jenkinsfile`, define a Declarative Pipeline to run the tests in your project and fail the build if any of the tests fails.
+
+
+```groovy
+pipeline {
+    agent any
+    stages{
+        stage('Run MATLAB Tests') {
+            steps
+            {
+                runMATLABTests()
+            }       
+        }                
+    } 
+}
+``` 
+
+ Use the `runMATLABTests` step in a Scripted Pipeline to run the tests in your project.
+
+```groovy
+node {
+    runMATLABTests()  
+}
+``` 
+
+ To generate artifacts using the `runMATLABTests` step, provide the step with one or more name-value pair arguments to specify the artifacts and the locations to save them. Use a colon to Separate names and values.
+
+ For example, define a Declarative Pipeline to run the tests in your MATLAB project automatically, and then generate a JUnit test results report and a Cobertura code coverage report at specified locations on the build agent.
+
+
+```groovy
+pipeline {
+    agent any
+    stages{
+        stage('Run MATLAB Tests') {
+            steps
+            {
+                runMATLABTests(testResultsJUnit: 'test-results/results.xml',
+                               codeCoverageCobertura: 'code-coverage/coverage.xml')
+            }       
+        }                
+    } 
+}
+``` 
+
+Define a Scripted Pipeline to run your tests and generate artifacts.
+
+```groovy
+node {
+    runMATLABTests(testResultsJUnit: 'test-results/results.xml',
+                   codeCoverageCobertura: 'code-coverage/coverage.xml') 
+}
+``` 
+
+
+ 
+ This table lists the name-value pair arguments that you can specify with the `runMATLABTests` step.
+
+| Name               	| Value                                                                                                                	|
+|-------------------------	|----------------------------------------------------------------------------------------------------------------------------	|
+| testResultsPDF          	| Path to write test results report in PDF format (currently not supported on Mac platforms).<br/>**Example:** `'test-results/results.pdf'`                  	|
+| testResultsTAP          	| Path to write test results report in TAP format.<br/>**Example:** `'test-results/results.tap'`                  	|
+| testResultsJUnit        	| Path to write test results report in JUnit XML format.<br/>**Example:** `'test-results/results.xml'`            	|
+| testResultsSimulinkTest 	| Path to export Simulink Test&trade; Manager results in MLDATX format (requires Simulink Test license and is supported in MATLAB R2019a or later).<br/>**Example:** `'test-results/results.mldatx'` 	|
+| codeCoverageCobertura   	| Path to write code coverage report in Cobertura XML format.<br/>**Example:** `'code-coverage/coverage.xml'`     	|
+| modelCoverageCobertura  	| Path to write model coverage report in Cobertura XML format (requires Simulink Coverage™ license and is supported in MATLAB R2018b or later).<br/>**Example:** `'model-coverage/coverage.xml'`   	|
+
+
+## Use MATLAB for Matrix Build
+Similar to multi-configuration projects, you can use the plugin to perform [matrix](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-matrix) builds in Pipeline projects. For example, you can define a Declarative Pipeline to run your test suite on different platforms or against different versions of MATLAB. (Matrix build is not supproted in Scripted Pipelines.)
+
+Your Pipeline must have a `matrix` section to define the possible name-value combinations that should run in parallel. This example shows how to define a Pipeline to run your MATLAB code and generate test artifacts using MATLAB R2018b, R2019a, and R2020a.
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('BuildAndTest') {
+            matrix {
+                agent any
+                environment {
+                    PATH = "C:\\Program Files\\MATLAB\\${VERSION}\\bin;${PATH}"   // Windows agent
+                }
+                axes {
+                    axis {
+                        name 'VERSION'
+                        values 'R2018b', 'R2019a', 'R2019b'
+                    }
+                }
+                stages {
+                    stage('Run MATLAB commands') {
+                        steps {
+                            runMATLABCommand 'ver'
+                            runMATLABCommand 'pwd'
+                        }
+                    }
+                    stage('Run MATLAB tests'){
+                        steps {
+                            runMATLABTests(testResultsJUnit: 'test-results/results.xml',
+                                           codeCoverageCobertura: 'code-coverage/coverage.xml')
+                        }  
+                    }
+                }
+            } 
+        }
+    }
+}
+``` 
+
 ## See Also
 [Run MATLAB Tests on Jenkins Server](examples/Run-MATLAB-Tests.md)<br/>
 [Continuous Integration (MATLAB)](https://www.mathworks.com/help/matlab/continuous-integration.html)<br/>
diff --git a/examples/Run-MATLAB-Tests.md b/examples/Run-MATLAB-Tests.md
@@ -45,8 +45,7 @@ Create a new project and configure it by following these steps:
 
 6. In the **Build** section of Jenkins, select **Add build step > Run MATLAB Tests**. Then, select your desired test artifacts to be generated in the project workspace. The plugin in this example is configured to generate Cobertura code coverage and JUnit test result reports. For more information on how to configure the plugin, see [Plugin Configuration Guide](../CONFIGDOC.md).
 
-![run_matlab_tests](https://user-images.githubusercontent.com/48831250/83893537-11efb100-a71e-11ea-8bb6-9c6f450ad8a7.png)
-
+![run_matlab_tests](https://user-images.githubusercontent.com/48831250/84545885-17c13580-acce-11ea-8a29-b78386a7f0ef.png)
 
 7. In the **Post-build Actions** section of Jenkins, add two post-build actions to publish the Cobertura code coverage and JUnit test result reports. For each report, provide the path to the report file.
 
