4. Invoking Reactis from Jenkins

Reactis is invoked from Jenkins by running a script in MATLAB which uses the Reactis MATLAB API.

Fig. 4.1 The version of MATLAB to use in a Jenkins project is selected as part of the project build environment.

The following steps are required to invoke Reactis from Jenkins using MATLAB:

1. In Jenkins, create a freestyle project. It’s also possible to add a build step to an existing project which will invoke Reactis.

2. Under the Build Environment check Use MATLAB version and select the same version of MATLAB that Reactis is configured to invoke, as shown in Figure 4.1.

3. Under the Build Triggers, add a build step Run MATLAB Command and enter a MATLAB command which will call the testing script below.

4.1. Invoking MATLAB from Jenkins

The details of the Run MATLAB Command text will depend on the details of your project. The simplest approach is to have a one-line command which runs a script. For example:

run('C:\MyScripts\reactis_test.m');

will run the MATLAB script C:\MyScripts\reactis_test.m.

It’s also possible to pass parameters from Jenkins to MATLAB. For example:

addpath('C:\MyScripts'); 
reactis_test('C:\Program Files\Reactis V2021', 'C:\MyProject\MyModel.slx');

will add the directory C:\MyScripts to the MATLAB search path and then run the MATLAB script C:\MyScripts\reactis_test.m. The Reactis installation directory and pathname of the model under test are passed as arguments to the script.

Fig. 4.2 A Jenkins build action which uses the MATLAB plugin.

An example Jenkins build action which calls the MATLAB plugin is shown in Figure 4.2.

4.2. Invoking Reactis from MATLAB

MATLAB scripts invoke Reactis using the Reactis API. A sample script is shown below. The Reactis API documentation can be found on the Reactis Support page.

function reactis_test(reactisDir,modelFile)
  workDir = pwd();
  [mdlDir,mdlBase,mdlExt] = fileparts(modelFile);
  rsiFile=fullfile(mdlDir,  [mdlBase,'.rsi']);
  rstFile=fullfile(workDir, [mdlBase,'.rst']);
  htmFile=fullfile(workDir,'test_report.htm');
  addpath(fullfile(reactisDir,'lib','api','MATLAB','reactis'));
  cd(mdlDir);
  rsOpen();
  fprintf('Creating %s\n',rstFile);
  suite = rsTester(modelFile, rsiFile, rstFile);
  fprintf('Creating %s\n',htmFile);
  sim = rsSimOpen(modelFile, rsiFile);
  rsSimRunSuite(sim, suite, htmFile);
  rsSuiteClose(suite);
  rsSimClose(sim);
  rsClose();
end

The script takes two arguments. The first argument (reactisDir) is the directory where Reactis is installed, and the second argument (modelFile) is the pathname of the model to test. The script first calculates the path names for all the files it will access and adds the Reactis API directory to the MATLAB search path. After this initial configuration is complete, the script uses the Reactis API to create a test suite and test execution report (the relevant part of the script starts at the call to rsOpen and ends at the call to rsClose). The heavy lifting is done by the Reactis API functions rsTester, which creates a test suite, and rsSimRunSuite, which creates a test execution report.

4.3. Importing Test Results into Jenkins

The script shown above will create a test execution report which will appear as file test_report.htm in the Jenkins workspace directory. The report is imported into Jenkins using the HTML Publisher plugin.

Fig. 4.3 A Jenkins post-build action which uses the HTML publisher plugin to retrieve an HTML report.

To import the report, a post-build action is required, as shown in Figure 4.3. To add a post-build action to a Jenkins project, go to the Post-Build Actions section of the project selection and add a Publish HTML Reports action. The HTML Publisher plugin requires you to specify the directory and index file(s) from which it will retrieve the HTML files. In our example, the name of the HTML directory is empty (it defaults to the Jenkins workspace directory) and the file name of the index file is test_report.htm.

Fig. 4.4 A Jenkins project which includes a Reactis-generated test report.

Once the project is up and running, the project status page will contain a link to the Reactis test results for the most recent build, as shown in Figure 4.4. Note the status page includes a link named Reactis Test Results. Clicking on this link will display a Reactis test execution report, as shown in Figure 4.5.

Fig. 4.5 Viewing a Reactis test execution report within Jenkins.

4.4. Summary

To recap, the steps required to use Reactis with Jenkins can be summarized as follows.

The following steps are required only once.

1. Configure Reactis to use the version of MATLAB which will be used with Jenkins.

2. Configure Jenkins by adding the MATLAB and HTML Publisher plugins if needed and adding the MATLAB installation directory to the Jenkins global tool configuration.

The following steps are required each time a project is configured to use Reactis.

1. Select the MATLAB version in the project build environment.

2. Add a MATLAB build action which calls a MATLAB .m script that uses the Reactis API to perform testing activities.

3. Add an HTML publisher post-build action which collects the test execution report produced by Reactis.