Create and set up a Jenkins project

To run a Ranorex Studio test as a build step in Jenkins, you need to create a project in Jenkins. On this page, you’ll find out how to create and configure a Jenkins project, including the settings for the Ranorex Test Execution Plugin.

In this chapter

Create Jenkins project

To create a project in Jenkins:

Click…

…New Item.
…Create new jobs.

Enter a project name.

Select Freestyle project as template and click OK.

Once Jenkins has created the project, it displays the settings for it.

Configure Jenkins project

There are many ways in which you can configure a Jenkins project. On this page, we focus on the settings relevant to the integration of Ranorex Studio tests.

The project settings are displayed automatically after creating a project. Alternatively, you can also bring them up at any time as follows:

With the project open, click Configure.

Source Code Management

This is where you configure how Jenkins accesses the repository where your files are under version control.

In our case, we use GitHub, so we make the following configurations:

Into Repository URL, paste your GitHub repository’s URL.

If credentials are necessary to access the repository, enter them under Credentials.

MSBuild step

You need to add and configure an MSBuild step so that Jenkins will build the Ranorex Studio solution correctly. To do so:

Click Add build step.

Click Build a Visual Studio project or solution using MSBuild.

Select an MSBuild version (defined as part of ⇢ plugin configuration).

Enter the path to the Visual Studio version (.sln) of your Ranorex Studio solution (.rxsln). The path must be relative to your version control repository’s root folder. In our example, the .sln file is located directly in the root folder, so the file name is enough.

Run a Ranorex test suite build step

Finally, we need to add a build step to run the Ranorex Studio test. The following basic configurations are required. Additional settings are explained further below.

Click Add build step.

Click Run a Ranorex test suite.

Enter the path to the test suite file (.rxtst) relative to the solution folder. By default, the test suite file is located in the output folder, i.e. <solution folder>/bin/Debug/<test suite file>.rxtst

Advanced settings

Aside from the required settings above, the Ranorex test suite build step also contains a range of advanced settings. They can be used to customize the test run. These settings are available from the Advanced… button in the build step.

Ranorex run configuration

Here you can specify a run configuration. If you don’t specify one, the test uses the run configuration that was active when the Ranorex Studio solution was last saved.

The available run configurations in the test suite view in Ranorex Studio

The desired run configuration needs to be spelled exactly the same way in the Jenkins field

Change report directory, name, and file extension

You can change the default report name and directory in Jenkins. The default name and directory are indicated in yellow below the respective fields if they are left empty. Here’s an example:

Custom report directory. The path must be relative to the output folder (bin/debug) of the Ranorex Studio project

Custom report name with Jenkins variables. You can also use the available ⇢ Ranorex Studio report name placeholders

File extension selector: rxlog and xml are available

The console output when building a project with the above settings

JUnit-compatible report

The JUnit data format is used by many CI systems to interpret test result data. When activated, this setting adds a copy of the report in JUnit format.

Ensure you have the Jenkins JUnit plugin installed and actived, as explained in ⇢ Install and configure plugins.

Activate the JUnit-compatible report.

In the Jenkins project, click Add post build action.

Click Publish JUnit test result report.

Under Test report XMLs, enter the Ranorex Studio report directory.

When you’ve run a build, the build summary will contain a link to the JUnit report.

Compressed copy of Ranorex report

To create a compressed copy of the report:

Activate the compressed report copy.
Enter a custom directory if desired. The path must be relative to the output folder (bin/debug) of the Ranorex Studio project. If you leave the field empty, the default report directory is used.
Enter a custom name for the compressed report if desired. You can use Jenkins and Ranorex Studio variables.

Ranorex TestRail integration

These settings allow you to pass test results to TestRail. They correspond to the command line parameters for the TestRail integration.

Global parameters

If the test suite contains global parameters, you can define values for them here. They will then override any existing values for these parameters when the build runs.

To define values:

Enter parameters and values according to the following pattern: “ParameterName=Value”. Separate parameters with semicolons.

Command line arguments

In this field, you can pass any command line arguments available in Ranorex Studio.

Archive build artifacts

Build artifacts are files that are created as a result of the build, i.e. the executable build of the test and the report files.  You can make these artifacts available for download from Jenkins, which is more convenient than hunting for the files in the respective directories.

To do so:

In the Jenkins project, click Add post build action.

Click Archive the artifacts.

Specify the files you want to archive.

In the image, the post-build step archives all files that are in the directory /myReports/, contain the Jenkins build name and number, and whose file ending contains “rx”.

After the build has executed, the artifacts are available for download as shown below: