This topic describes a general approach to running ReadyAPI functional tests from Jenkins.

Overview

We need to create a Jenkins job that will run ReadyAPI functional tests from Jenkins agent machines (or Jenkins nodes). To run functional tests, you need to install ReadyAPI on each Jenkins node and use the ReadyAPI Functional Testing plugin or ReadyAPI command-line runners to run the tests.

The ReadyAPI Functional Testing plugin provides you with an easy way to run functional tests from Jenkins jobs and Jenkins Pipelines. If you need to run load or secure tests, or if you need to specify advanced options for a functional test run, use the command-line runners.

Note:

To run ReadyAPI tests in TestEngine, use the ReadyAPI TestEngine Jenkins Plugin.
To deploy, start, stop or update virtual services on VirtServer, use the Jenkins VirtServer plugin.

Required license

In order to run ReadyAPI tests, you need to activate the appropriate license on each node. The easiest way to do this is to install ReadyAPI on a node and activate the license through the ReadyAPI user interface. However, it is considered to be a good practice to clean up the test environment after the test run is over. In other words, you may want to configure nodes automatically before each run, and this means you may want to automate the ReadyAPI license activation. ReadyAPI supports a special command-line tool to automate activation (see below).

Tip:

You can use a trial license to try ReadyAPI out. To learn how to get it, see Online Activation of a Trial License Without ReadyAPI.

Which license to use: Floating or Fixed? It is reasonable to select a Floating license as it suites dynamic testing environments in a better way. You will activate the license on some computer in your network (let’s call it license server) and configure ReadyAPI instances on Jenkins nodes to connect to this server and to check out the license from it.

Requirements to Jenkins nodes

One of the supported Java versions installed.
Network access to the license server with the Floating license activated (by default, the server works on port 1099).
Access to the ReadyAPI License Manager. You can download it in the .zip format from our website. Unpack the downloaded .zip archive and copy its content to your Jenkins node or put it to a shared network folder, to which the node has access.
Access to the ReadyAPI installation program (you can copy it to your Jenkins nodes, or you can put it to a shared network folder).
On Windows Jenkins nodes, disable the User Account Control (UAC). You can do this in the Control Panel. Otherwise, Windows can display various system confirmation dialogs, which require user interaction.

ReadyAPI Functional Testing plugin

To make the communication between Jenkins and ReadyAPI easier, consider installing the ReadyAPI Functional Testing plugin. To install it:

Open Jenkins and click Manage Jenkins:
Open Manage Plugins:

Click the image to enlarge it.
On the Available page, type ReadyAPI in the Filter field and select ReadyAPI Functional Testing.

Click the image to enlarge it.
Click Install without restart or Download now and install after restart:

Click the image to enlarge it.

1. Create and configure Jenkins nodes

Jenkins documentation includes a detailed guide on configuring Jenkins nodes. Follow the instructions on this page:

https://wiki.jenkins.io/display/JENKINS/Step+by+step+guide+to+set+up+master+and+agent+machines+on+Windows

Tip: We recommend using Java Web Start for launching nodes in most scenarios. The optimal method depends on your environment.

2. Install ReadyAPI on Jenkins nodes

To install ReadyAPI automatically:

Use the Execute batch command build step. The way you add it depends on the operating system of the Jenkins node:
- Windows Jenkins nodes: select Add build step > Execute Windows batch command.
- Linux or macOS nodes: select Add build step > Execute shell.
Click the image to enlarge it.
Configure the step to run the ReadyAPI installer. Add the -q argument to the installer command line. This way, the installation will run in silent mode, that is, without any user interaction, and will use the default values for all options.

To change the installation folder, you can use the -dir argument. -varfile lets you specify additional installation parameters. You can find more information in the install4j documentation.

Here is a sample command line that installs ReadyAPI in silent mode:

"c:\sample\ReadyAPI-x64-3.8.1.exe" -q -dir "c:\readyapi-folder" -varfile response.varfile

3. Get ReadyAPI license

On your Jenkins node, create a text file that will contain the code of the ReadyAPI application, whose license you want to consume:

1 ReadyAPI Test

2 ReadyAPI Performance

3 Secure (if you have an old license)

4 ReadyAPI Virtualization

5 VirtServer

6 ReadyAPI Bundle

7 TestEngine

8 SwaggerHub

9 SwaggerHub 2

Tip: If you use the ReadyAPI Functional Testing plugin, specify 1.
To get the ReadyAPI license, run the license-manager.bat (on Windows node) or .sh file (on Linux and macOS nodes) from the command line. To do this, add another Execute batch command step to your Jenkins job. Use the -s license-server-IP:port < file argument to specify the license server from which the License Manager will consume a Floating license:

license-manager.bat -s 10.0.81.128:1099 < c:\readyapi-folder\MyCode.txt

Here, MyCode.txt is the file that contains the code of the licensed ReadyAPI application (see above).

Note: The License Manager requires Java 12. You can use Java shipped with ReadyAPI or download the required version from https://jdk.java.net/archive/.

4. Copy test projects and data files to nodes

To run ReadyAPI tests from a Jenkins node, you need to copy your ReadyAPI project to this node. You also need to copy the data files your tests use.

If your tests use custom script libraries, copy the libraries to the <ReadyAPI installation>/bin/scripts folder on the Jenkins node.

To copy the files, use the Jenkins Copy file build step. A possible alternative is to place the project and data file to some shared network folder to which Jenkins nodes have access.

5. Run tests

By using the ReadyAPI Functional Testing plugin

To run functional tests in Jenkins:

Make sure the ReadyAPI Functional Testing plugin is installed.
In Jenkins, select a job and click Configure.
In the Build section, click Add build step > ReadyAPI Test: Run functional Test:
Jenkins will add the step to the build:

Click the image to enlarge it.

Configure the following build step options:

Option	Description
Path to TestRunner	Specifies the fully-qualified path to the test runner binary (testrunner.bat or testrunner.sh). By default, you can find it in the <ReadyAPI installation>/bin directory.
Path to ReadyAPI project	Specifies the fully-qualified path to the ReadyAPI project you want to run.
Test Suite	Specifies the test suite to run. To run all the test suites of your project, leave the field blank.
Test Case	Specifies the test case to run. If you leave the field blank, the runner will execute all the test cases of the specified test suite, or, if you have not specified a test suite, all the test cases of your project.
Test Suite Tags	Specifies which tags the test suite must contain to be run. To create complex conditions, use the `\|\|` (logical OR), `&&` (logical AND) and `!` (logical NOT) operators.
Test Case Tags	Specifies which tags the test case must contain to be run. To create complex conditions, use the `\|\|` (logical OR), `&&` (logical AND) and `!` (logical NOT) operators.
Project Password	Specifies the encryption password, if you encrypted the entire project or some of its custom properties. See Protecting Sensitive Data.
Environment	Specifies the environment configuration for the test run.

If you want to specify additional arguments for the test runner, call the test runner using the command line – see below.

Analyze results

If you use the ReadyAPI Functional Testing plugin, the functional test runner exports a JUnit-style HTML report to your Jenkins workspace directory.

You can also view a PDF version of the report directly from Jenkins. To do that, open the needed project and build, then click the ReadyAPI Test Results link to the left:

Click the image to enlarge it.

By using Jenkins Pipeline

The ReadyAPI Functional Testing plugin supports launching tests from Jenkins Pipeline. To run a test, you need to add the SoapUI Pro Pipeline step to your Pipeline script:

Make sure the ReadyAPI Functional Testing and Jenkins Pipeline plugins are installed.
In Jenkins, select a Pipeline and click Configure.
In the Pipeline section, add the SoapUI Pro Pipeline step to your Pipeline script:

Click the image to enlarge it.

Below is an example of a Pipeline script with a SoapUI Pro Pipeline step:

View example

View exampleHide example

Scripted Pipeline

Scripted Pipeline

node('master') {
  stage('Build') {
    sh 'make'
  }

  stage('Test') {
    SoapUIPro ( pathToTestrunner: 'SmartBear/ReadyAPI-3.8.1/bin/testrunner.sh', pathToProjectFile: 'ReadyAPI-Projects/sample-soapui-test.xml', testSuite: '', testCase: '', testSuiteTags: '(tag1 || tag2) && !tag3', projectPassword: '', environment: '' )
  }

  stage('Deploy') {
    sh 'make publish'
  }
}

Tip: To learn more about the Pipeline syntax, see https://jenkins.io/doc/book/pipeline/syntax/.
Click Save.

Note:

This instruction describes adding a SoapUI Pro Pipeline step to a Pipeline using the classic Jenkins UI. You can also do that in Blue Ocean, or, if you store the Jenkinsfile with the script in a source control system, you can just edit it manually.

SoapUI Pro Pipeline step

The format of the Pipeline step is as follows:

SoapUIPro (
    pathToTestrunner: '<path>',
    pathToProjectFile: '<path>',
    testSuite: '[<testSuiteName>]',
    testCase: '[<testCaseName>]',
    testSuiteTags: '<test suite tags>',
    testCaseTags: '<test case tags>'
    projectPassword: '[<password>]',
    environment: '[<environmentName>]' )

pathToTestrunner

Required. Specifies the fully-qualified path to the test runner binary (testrunner.bat or testrunner.sh). By default, you can find it in the <ReadyAPI installation>/bin directory.

pathToProjectFile

Required. Specifies the fully-qualified path to the ReadyAPI Test project you want to run.

testSuite

Optional. Specifies the test suite to run. If not specified, the runner will execute all the test suites of your project.

testCase

Optional. Specifies the test case to run. If not specified, the runner will execute all the test cases of the specified test suite, or, if you have not specified a test suite, all the test cases of your project.

testSuiteTags

Optional. Specifies which tags must contain the test suite to be run. To create complex conditions, use the || (logical OR), && (logical AND) and ! (logical NOT) operators.

testCaseTags

Optional. Specifies which tags must contain the test case to be run. To create complex conditions, use the || (logical OR), && (logical AND) and ! (logical NOT) operators.

projectPassword

Optional. Specifies the encryption password, if you encrypted the entire project or some of its custom properties. See Protecting Sensitive Data.

environment

Optional. Specifies the environment configuration for the test run.

If you want to specify additional arguments for the test runner, call the test runner using the command line – see below.

By using command-line runners

To run tests, use one of the ReadyAPI command-line test runners:

Functional TestRunner – Runs functional tests.
Security TestRunner – Runs security tests.
Performance TestRunner – Runs load tests created with ReadyAPI Performance.
VirtRunner – Starts or stops a virtual API created with ReadyAPI Virtualization.

To run any of these tools, add an Execute batch command step to your Jenkins job. As we wrote above, the way you do this depends on the operating system of your Jenkins node.

Below is a sample command line that starts a functional test on a Windows Jenkins node:

"c:\readyapi-folder\bin\testrunner.bat" "-sTest Suite 1" -cSimpleRequest "-RTestCase Report" "-EDefault environment" "c:\work\projects\my-project.xml"

For complete information on the command-line arguments, follow the links above.

Possible issues

By default, Jenkins runs jobs by using its own user profile. In this case, if you use a Fixed license, ReadyAPI will not be able to find it. To learn how to fix this issue, see Jenkins: "License Not Found" Issue.
The ReadyAPI Functional Testing plugin ver. 1.4 fixed a security vulnerability in project password storage. If you update to ver. 1.4 from an earlier version, to ensure the security of your passwords, you need to do the following for all the jobs that use the plugin:
1. Select a job and click Configure.
2. Save the configuration without making any changes by clicking Save or Apply.

Running ReadyAPI Tests From Jenkins